Download the PHP package civicrm/php-array-doc without Composer

PhpArrayDocument

This is a parser/printer for a subset of PHP focused on data. (It serves a role similar to a full-service YAML library - except with `.php` data-files.*) Key features:

• Allows array values and scalar values (string, int, bool, etc).
• Allows comments for the overall document and for individual items in the tree.
• Allows tagged-values (a.k.a. factory-functions) which look like global or static method-calls.
• Allows deferred construction (fn() => [...data...])
• Prohibits objects, loops, math, concatenation, includes, custom functions, etc.

Examples: Data documents

A basic document looks like this:

This next example is similar, but it adds a "tagged value" or "factory function" called MyHelper::translate():

Note that H::translate('Hello world') takes exactly one parameter. It only supports a subset of PHP function-calls -- i.e. with one parameter; with global-function or static-method. (H::translate is less like an open-ended function-call and more like a tag that describes Hello world.)

The same concept can be applied to generate objects/records, as long as there is exactly one parameter:

Value resolution may be defererd, as in:

Examples: File manipulation

Generate a new *.php data file. Populate it with importData($array):

Read an existing file. Update individual items in the parse-tree. Save the updated file.

Update an existing file. Do a global search (walkNodes()). Find references to OldHelper::method and replace them with NewHelper::method.

Cheatsheet

Some commands to help with debugging:

Model

• Basic Concepts
  • Substance: Each "PHP array document" contains a tree of arrays and scalars.
  • Metadata: Individual values may be annotated with comments and/or factory-functions (such as ts(...)).
  • Evaluation: If you include or require the PHP document directly, you will literally get arrays and scalars.
  • Read/Write: If you need to programmatically inspect or update the content, then the PhpArrayDocument aims to help.
• Verbs
  • Parse: Read the PHP document as an instance of PhpArrayDocument
  • Print: Render PhpArrayDocument as a string (<?php return [...])
  • Import Data: Add basic PHP array data to a PhpArrayDocument (without any metadata/comments/factory-functions)
  • Export Data: Grab the PHP (discarding any metadata/comments/factory-functions)
  • Walk Nodes: Visit all the nodes in the tree. Useful for general filtering/searching/replacing.
• Classes
  • Data-Focused Classes
    • PhpArrayDocument: This captures the overall *.php file, including any top-level elements (use or docblocks) and the root array.
    • ArrayNode (extends BaseNode): An element in the tree that corresponds to array()
    • ArrayItemNode (extends BaseNode): A key-value pair that exists within an array()
    • ScalarNode (extends BaseNode): An atomic value that lives inside an array.
  • Functionality-Focused Classes
    • Parser: Take a raw string. Generate a PhpArrayDocument.
    • Printer: Take a PhpArrayDocument. Generate a string