README

将WordPress的短代码语法作为独立包实现。编辑器、数据库等内容的扫描可以通过短代码管理器进行，并用自定义回调替换内容。

需求

短代码需要PHP 7.1或更高版本。

Composer

可以通过运行以下命令将此包作为Composer依赖项安装

composer require maiorano84/shortcodes

如果您想使用最新不稳定版本，可以运行

composer require maiorano84/shortcodes:dev-master

什么是“短代码”

短代码是在各种CMS、编辑器和库中常用的一种宏支持格式。最著名的例子可能是WordPress短代码API，它为开发者提供了一条增强其主题或插件易用性的途径。

短代码的组成如下

[tag] - No content, no attributes
[tag]Content[/tag] - Tag with content
[tag atribute=value] - Tag with attributes
[tag atribute=value]Content[/tag] - Tag with content and attributes

短代码可以遵循许多格式，但最终的想法是当匹配到短代码标签时，其内容将被服务器端回调替换。

使用方法

此包包含您开始定义自定义短代码及其相应回调所需的一切。要程序化地定义自定义短代码，可以使用SimpleShortcode类

use Maiorano\Shortcodes\Manager;
use Maiorano\Shortcodes\Library;

//Instantiate a Shortcode Manager
$manager = new Manager\ShortcodeManager;
//Create your shortcode
$example = new Library\SimpleShortcode('example', ['foo'=>'bar'], function($content=null, array $atts=[]){
    return $content.$atts['foo'];
});
$manager->register($example)->doShortcode('[example]Foo[/example]'); //Outputs: Foobar

现在，当您处理包含[example]的字符串时，它将被您的自定义回调替换。

嵌套短代码

在大多数情况下，SimpleShortcode类足以满足您应用程序的需求。但是，某些情况可能需要更多的配置，这是SimpleShortcode类默认不假设的。

您可能会遇到的一个相当常见的情况是需要嵌套短代码

'[foo][bar/][/foo]'

到目前为止的所有示例中，没有一个涵盖了当您注册两个短代码，其中一个包含另一个时会发生什么。让我们看看会发生什么

$manager = new ShortcodeManager([
    'foo' => new Library\SimpleShortcode('foo', null, function ($content) {
        return 'foo' . $content;
    }),
    'bar' => new Library\SimpleShortcode('bar', null, function () {
        return 'bar';
    })
]);
echo $manager->doShortcode('[foo][bar/][/foo]'); //Outputs: foo[bar/]

短代码——根据其本质——旨在封装内容。该内容被处理并返回给管理器以输出。

问题是[bar/]被匹配并通过管理器作为内容传递。而不是短代码。

要处理这个问题，我们可以采取几种途径。让我们设置一个使用三个短代码的管理器

$manager = new ShortcodeManager([
    'foo' => new Library\SimpleShortcode('foo', null, function ($content) {
        return 'foo' . $this->manager->doShortcode($content, 'bar');
    }),
    'bar' => new Library\SimpleShortcode('bar', null, function ($content) {
        return 'bar' . $content;
    }),
    'baz' => new Library\SimpleShortcode('baz', null, function () {
        return 'baz';
    })
]);

[foo] - 将短代码作为文本渲染，内容附加，允许[bar]被处理
[bar] - 将短代码作为文本渲染，内容附加
[baz] - 将短代码作为文本渲染

选项1：选择性

echo $manager->doShortcode('[foo][bar/][/foo]'); //Outputs: foobar
echo $manager->doShortcode('[foo][baz/][/foo]'); //Outputs: foo[baz/]

这种方法的优点是您可以决定什么内容被处理，什么内容不被处理。如果您的短代码中可能包含应该由调用它的管理器处理的内容，那么您的最佳选择是返回包装在另一个doShortcode调用的内容。

选项2：宽容性

echo $manager->doShortcode('[foo][baz/][/foo]', 'foo', true); //Outputs: foo[baz/]
echo $manager->doShortcode('[foo][baz/][/foo]', 'foo|baz', true); //[baz] Permitted in this instance

在doShortcode中可以设置一个可选的第三个参数，这将允许管理器决定哪些标签要渲染并递归运行，直到处理完所有内容。

尽管我们已定义只有[bar]可以在[foo]回调中处理，但短代码管理器可以选择随时覆盖它。

选项3：焦土政策

不在乎？只想处理所有可能的简码，让结果顺其自然？

拿着我的啤酒

echo $manager->doShortcode('[foo][bar][baz/][/bar][/foo]', null, true); //Outputs: foobarbaz

别名

如果您想为现有的简码创建别名，有多种方法可以做到这一点

$manager = new ShortcodeManager;
$bold = new SimpleShortcode('bold', null, function($content){
    return sprintf('<strong>%s</strong>', $content);
});
$manager->register($bold);
$manager->alias('bold', 'b');

现在当您使用 [bold] 或 [b] 时，它们都会执行相同的功能。

请注意：在注册别名时，默认情况下取消注册原始简码也会取消注册其相关别名。

如果您想取消注册特定的简码但保留其别名，您可以提供第二个参数，以告知管理器不要取消注册别名

$manager->deregister('bold', false);

现在，[b] 将继续渲染，但 [bold] 将不再被识别。

快捷键

提供了一些快捷键供您使用。注册可以像这样简单

$manager[] = $bold;

您还可以直接为 SimpleShortcode 赋予别名

$bold->alias('b');

除了上述方法外，您还可以直接在 SimpleShortcode 上运行 doShortcode。这两个语句是相同的

$manager->doShortcode('[bold]Bold[/bold][b]Bold[/b]', 'bold|b');
$bold->doShortcode('[bold]Bold[/bold][b]Bold[/b]');

最后，取消注册简码及其别名可以这样操作

unset($manager['bold']);

其他注意事项

您可能已经注意到，SimpleShortcode 类可以通过调用受保护的成员来实现某些结果。在每个利用从 CallableTrait 中继承的 handle 方法的简码中，回调绑定到该特定实例的作用域。这意味着即使在声明了受保护和私有成员的情况下，您仍然可以在回调的作用域内访问这些成员。

最终的目标是尽可能保持灵活性，让您——开发者——以您想要的方式构建您的应用程序。

祝您享受！