README

这个库提供了一个用于包含"短代码"的文本的简单解析器，"短代码"是BBCode的底层格式。

本项目旨在将包含通用短代码的纯文本转换为相应的数据结构。这应该尽可能地快和高效，即使是大量文本和深度嵌套的结构。本项目不涉及支持任何超出此范围的处理。对于更灵活的解决方案，该方案针对较小的文本量进行了优化，请参阅Shortcode。

安装

composer require off-by-n/shortcode-templates

用法

(new ShortcodeParser)->parse($inputString);

示例输入字符串

Lorem ipsum dolor sit amet, consetetur sadipscing elitr, [hr bold][color=red]sed diam nonumy eirmod [color="green"]tempor invidunt ut labore et[/color] dolore [url="https://example.org" alt="Magna"]magna[/url] aliquyam [/color] erat, [b]sed[/b] diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.

这将产生以下数据结构的等效。如您所见，允许使用闭合和未闭合的短代码。短代码之间的纯文本是输出的一部分

[
    "Lorem ipsum dolor sit amet, consetetur sadipscing elitr, ",
    {
        "name": "hr",
        "value": null,
        "attributes": {
            "bold": true
        },
        "children": null
    },
    {
        "name": "color",
        "value": "red",
        "attributes": {},
        "children": [
            "sed diam nonumy eirmod ",
            {
                "name": "color",
                "value": "green",
                "attributes": {},
                "children": [
                    "tempor invidunt ut labore et"
                ]
            },
            " dolore ",
            {
                "name": "url",
                "value": "https:\/\/example.org",
                "attributes": {
                    "alt": "Magna"
                },
                "children": [
                    "magna"
                ]
            },
            " aliquyam "
        ]
    },
    " erat, ",
    {
        "name": "b",
        "value": null,
        "attributes": {},
        "children": [
            "sed"
        ]
    },
    " diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet."
]

然后您可以自行编写逻辑进行后续处理。基本示例

function process($chunks = [])
{
    $output = '';
    foreach ($chunks as $chunk) {
        if ($chunk->isShortcode()) {
            $shortcode = $chunk->asShortcode();
            if ($shortcode->getName() == 'raw') {
                $output .= $shortcode->getInnerSource();
            } else {
                $output .= process($shortcode->getChildren());
            }
        } else {
            $output .= $chunk;
        }
    }

    return $output;
}

属性

短代码的结构假定如下

[<name>=<value> <attributeName1>=<attributeValue1> <attributeNameN>=<attributeValueN>]<children>[/<name>]

除了开头的名称和括号之外的所有部分都是可选的。以下方法可用于每个短代码

• getName() - 获取短代码的名称
• getValue() - 获取短代码的值，如果没有提供则返回 null
• getAttributes() - 以关联数组的形式获取所有属性
• getAttribute($name) - 通过名称获取单个属性，如果没有定义则返回 null
• getChildren() - 获取所有子块数组，对于未闭合的短代码返回 null
• getInnerSource() - 获取短代码开标签和闭标签之间的未解析源文本或对于未闭合的短代码返回 null
• getOuterSource() - 获取短代码的未解析源文本，包括开标签和闭标签

所有块，包括文本块，都有一个方法 isShortcode() 来区分块类型：shortcode 或 text。

为什么使用正则表达式

默认情况下，这个库使用PHP自带的正则表达式扩展在源文本中搜索控制结构。这样做的原因是性能和易于设置：Shortcodes格式由大量包含相对较短的已知格式的控制结构的文本组成。正则表达式扩展已优化以找到这种结构。由于它是本地实现，通常会比任何用PHP代码构建的解决方案有更好的性能。由于该扩展已存在于大多数安装中，因此无需安装此解析器即可安装任何其他扩展。如果需要其他实现，应该相对容易添加。