README

这是一个针对PHP数据子集的解析器/打印器。文档看起来像

<?php
return [
  'key_1' => 'value_1',
  'key_2' => [2.1, 2.2, 2.3],
  'key_3' => [
    'part_a' => 'Apple',
    'part_b' => 'Banana',
  ]
];

此外，您还可以声明标签/工厂值

<?php
use MyHelper as H;
return [
  'name' => 'greeter',
  'label' => H::translate('Hello World'),
];

甚至

use MyHelper as H;
return H::record([
  'name' => 'greeter',
  'label' => H::translate('Hello World'),
]);

PhpArrayDocument 是与PHP兼容的子集，考虑以下因素

• 允许 array 值和 scalar 值（string、int、bool 等）。
• 允许 tagged-values 或 factory-functions，它们看起来像 全局或静态方法调用。
• 允许延迟构建（fn() => [...data...]）。
• 禁止对象、循环、数学、连接、包含、自定义函数等。

模型

• 基本概念
  • 内容：每个 "PHP数组文档" 包含一个由 array 和 scalar 组成的树。
  • 元数据：单个值可以被注释和/或工厂函数（如 ts(...)）注释。
  • 评估：如果您直接 include 或 require PHP文档，您将直接得到 array 和 scalar。
  • 读写：如果您需要以编程方式检查或更新内容，那么 PhpArrayDocument 旨在帮助您。
• 动词
  • 解析：将PHP文档作为 PhpArrayDocument 实例读取。
  • 打印：将 PhpArrayDocument 作为字符串渲染（<?php return [...]）。
  • 导入数据：将基本的PHP数组数据添加到 PhpArrayDocument（不包含任何元数据/注释/工厂函数）。
  • 导出数据：获取PHP（丢弃任何元数据/注释/工厂函数）。
  • 遍历节点：访问树中的所有节点。对于通用过滤/搜索/替换很有用。
• 类
  • 数据关注类
    • PhpArrayDocument：这捕获了整个 *.php 文件，包括任何顶级元素（use 或 docblocks）和根 array。
    • ArrayNode（扩展 BaseNode）：树中对应于 array() 的元素。
    • ArrayItemNode（扩展 BaseNode）：存在于 array() 中的键值对。
    • ScalarNode（扩展 BaseNode）：存在于数组中的原子值。
  • 功能关注类
    • Parser：接受原始 string。生成 PhpArrayDocument。
    • Printer：接受 PhpArrayDocument。生成字符串。

示例

# Generate a file from basic array data
use PhpArrayDocument\PhpArrayDocument;
$doc = PhpArrayDocument::create();
$doc->getRoot()->importData([
  'foo...',
  'bar...',
]);
file_put_contents($file, (new Printer())->print($doc));

# Update a file
use PhpArrayDocument\Parser;
$file = 'my-example.data.php';
$doc = (new Parser())->parse(file_get_contents($file));

$doc->root['label'] = ScalarNode::create('Hello World')
	->setFactory('E::ts');

file_put_contents($file, (new Printer())->print($doc));

# Rename a factory method
$doc = (new Parser())->parse(file_get_contents($file));
foreach ($doc->root->walkNodes() as $node) {
  if ($node->getFactory() === 'OldHelper::method') {
    $node->setFactory('NewHelper::method');
  }
} 

速查表

一些有助于调试的命令

## Parse a PHP file
cat examples/simple-array.php | ./scripts/parse.php | less

## Parse an improvised PHP snippet
echo '<?php return [1,2,3];' | ./scripts/parse.php

## Tokenize a PHP file
cat examples/simple-array.php | ./scripts/tokenize.php | less

## Tokenize an improvised PHP snippet
echo '<?php return [1,2,3];' | ./scripts/tokenize.php