README

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

用法

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

<?php
use Mingos\uMacro\Parser;
use Mingos\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实例中。它们影响参数字符串的解析方式，并允许不同的语法。

`Mingos\uMacro\ParamParser\ParseStr`

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

`Mingos\uMacro\ParamParser\XMLAttributes`

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

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

创建自己的参数解析器

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

<?php
namespace My\App;

use Mingos\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

创建YouTubeiframe。

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

Vimeo

创建Vimeoiframe。

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

Soundcloud

创建Soundcloudiframe。

名称：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 Mingos\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() 明确检查这些参数，如果参数未提供，它将返回 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');

mingos / umacro

维护者

详细信息