README

uMacro 是一个 PHP 工具，用于解析和替换字符串中的宏。

使用方法

创建一个宏解析器很简单：只需创建一个 Parser 类的实例，并将实现 ParamParserInterface 的对象传递给它。

<?php
use UmbraProjekt\uMacro\Parser;
use UmbraProjekt\uMacro\ParamParser\ParseStr;

$parser = new Parser(new ParseStr());

从这一点开始，可以将任何字符串传递到 Parser#replace() 方法中，以便替换宏。

<?php
$string = "Watch this video: {{{youtube?id=ykwqXuMPsoc}}}";
echo $parser->replace($string);

每当找到匹配宏模式的字符串时，都会解析宏。使用上述配置的默认模式是 {{{macro_name?query_params}}}。换句话说，宏被三重花括号包围，由宏名称和参数组成。宏名称与参数之间由问号分隔。参数的形式为查询字符串，即可以被 parse_str() 解析的字符串。

请注意，此配置可以更改。

可用的参数解析器

有两个可用的参数解析器可以注入到 Macro 实例中。它们影响参数字符串的解析方式，并允许使用不同的语法。

`UmbraProjekt\uMacro\ParamParser\ParseStr`

接受查询字符串格式的参数，例如 {{{youtube?id=ykwqXuMPsoc&width=560}}}

`UmbraProjekt\uMacro\ParamParser\XMLAttributes`

接受 XML 属性格式的参数，例如 [youtube id="ykwqXuMPsoc" width="560"]。

注意，上述示例显示了宏分隔符和分隔符的非默认设置（请参阅有关宏自定义的部分）。

创建自己的参数解析器

如果需要为参数使用不同的语法，可以创建一个新的参数解析器。解析器类必须实现 UmbraProjekt\uMacro\ParamParserInterface 接口。该接口强制实现 parse() 方法。该方法接收参数作为原始字符串，正好像它们在文本宏中出现的那样。输出始终是参数的关联数组。

<?php
namespace My\App;

use UmbraProjekt\uMacro\ParamParserInterface;

class MyParser implements ParamParserInterface
{
    public function parse($paramsString)
    {
        $output = [];
        // extract param names and values from $paramsString

        return $output;
    }
}

要使用新的参数解析器，只需在 Parser 构造函数中注入新创建的对象。

<?php
$parser = new Parser(new MyParser());

自定义宏

Parser 类构造函数接受三个可选参数：宏的开启分隔符、宏/参数分隔符、宏的关闭分隔符。因此，如果默认设置在特定项目中不可接受，则应将新的设置传递给 Parser 构造函数。

<?php
$parser = new Parser(new XMLAttributes(), "[", " ", "]");

使用此类解析器解析的字符串仅对定义的宏语法做出反应。

<?php
$string = 'Watch this video: [youtube id="ykwqXuMPsoc" width="560"]';
echo $parser->replace($string);

可用的宏

有一些预定义的宏可用。

YouTube

创建 YouTube iframe。

名称：youtube
参数
- id（必需）
- width（可选，默认：560）
- height（可选，默认：315）
示例：{{{youtube?id=ykwqXuMPsoc&width=320&height=240}}}

Vimeo

创建 Vimeo iframe。

名称：youtube
参数
- id（必需）
- width（可选，默认：560）
- height（可选，默认：315）
示例：{{{vimeo?id=17798681&width=320&height=240}}}

Soundcloud

创建 Soundcloud iframe。

名称：soundcloud
参数
- id（必需）
- width（可选，默认：100%）
- height（可选，默认：166）
- auto_play（可选，默认：false）
- show_artwork（可选，默认：true）
- color（可选，默认：ff7700）
示例：{{{soundcloud?id=62438266&width=80%&height=200}}}

创建自定义宏

每个新的宏都需要扩展 Macro 抽象类。

<?php
namespace My\App;

use UmbraProjekt\uMacro\Macro;

class MyMacro extends Macro
{
    public function configParams()
    {
        // ...
    }
    public function run()
    {
        // ...
    }
}

宏必须实现两个方法：configParams() 和 run()。第一个方法告诉宏要查找哪些参数以及它们是否有默认值（即可以省略）。参数配置是通过使用 addParam() 方法完成的

<?php
public function configParams()
{
    $this->addParam("id"); // mandatory
    $this->addParam("width", "560"); // optional, with
                                     // default value
}

如果参数是可选的，但没有默认值（即可以完全省略，但如果在宏字符串中提供，则会被考虑），则不需要在 configParams() 方法中定义它，但应在 run() 方法中检查它。

run() 方法构建宏的输出并返回它。它可以使用 getParam() 和 getParams() 方法来获取传递给宏的参数。

所有提供的参数将通过 getParams 返回——用户传递给宏字符串的参数以及在配置中有默认值的参数。然而，省略的参数将不会出现。应该使用 getParam() 显式检查它们，如果参数未提供，则 getParam() 将返回 null。

<?php
public function run()
{
    $id = $this->getParam("id");
    $params = $this->getParams();
    $optional = $this->getParam("optional");
    return "<output>{$id} {$params['width']}</output>" .
        (null === $optional ? "" : "Optional provided!");
}

一旦创建了宏，就应该为其添加一个映射，以便解析器能够识别它

<?php
$parser->addMap("my_macro", 'My\App\MyMacro');

umbraprojekt / umacro

维护者

详细信息