README

Laravel Shortcodes

使用Laravel方式实现简单、优雅的WordPress-like Shortcodes。

要求

该软件包已开发和测试，可与其他最新的PHP和Laravel版本以及以下最低要求一起工作

• Laravel 6
• PHP 7.2

安装

通过Composer安装此软件包。

composer require tehwave/laravel-shortcodes

用法

Laravel Shortcodes与Wordpress的Shortcode API非常相似。

use tehwave\Shortcodes\Shortcode;

$compiledContent = Shortcode::compile('[uppercase]Laravel Shortcodes[/uppercase]');

// LARAVEL SHORTCODES

创建Shortcodes

运行以下命令，将新的Shortcode类放置到您的app/Shortcodes目录中。

php artisan make:shortcode ItalicizeText

输出

每个Shortcode类都包含一个handle方法，您可以使用它将输出放入编译内容中。

在handle方法中，您可以访问attributes和body属性。

注意：在解析时，attributes数组中的所有值都被转换为string类型。

<?php

namespace App\Shortcodes;

use tehwave\Shortcodes\Shortcode;

class ItalicizeText extends Shortcode
{
    /**
     * The code to run when the Shortcode is being compiled.
     *
     * You may return a string from here, that will then
     * be inserted into the content being compiled.
     *
     * @return string|null
     */
    public function handle(): ?string
    {
        if (isset($this->attributes['escape_html']) && $this->attributes['escape_html'] === 'true')) {
            return sprintf('<i>%s</i>', htmlspecialchars($this->body));
        }

        return sprintf('<i>%s</i>', $this->body);
    }
}

命名

短语的标签是从类名转换成snake_case得到的。

您可以使用tag属性或通过重写getTag方法来指定自定义标签。

短语标签必须是字母数字字符，并且可以包含下划线。

<?php

namespace App\Shortcodes;

use tehwave\Shortcodes\Shortcode;

class ItalicizeText extends Shortcode
{
    /**
     * The tag to match in content.
     *
     * @var string
     */
    protected $tag = 'italics';
}

编译Shortcodes

运行一个字符串通过编译器以解析所有短代码。

use tehwave\Shortcodes\Shortcode;

$compiledContent = Shortcode::compile('[italics escape_html="true"]<b>Hello World</b>[/italics]');

// <i>&lt;b&gt;Hello World&lt;/b&gt;</i>

您可以指定实例化的Shortcode类列表以限制解析的短代码。

use tehwave\Shortcodes\Shortcode;

$shortcodes = collect([
    new ItalicizeText,
]);

$compiledContent = Shortcode::compile('[uppercase]Hello World[/uppercase]', $shortcodes);

// [uppercase]Hello World[/uppercase]

示例

我为在gm48.net上使用用户提供的内客开发了Laravel Shortcodes。

内容使用名为Parsedown的Markdown转换器进行解析，由于不能信任用户，因此内容必须被转义。

不幸的是，这会导致双引号中的属性语法被转义，但也可以使用单引号以及省略任何引号。

注意：对于包含空白的任何属性值，都需要引号。

让我们看看以下包含一些基本的Row、Column和Image短语的示例内容。

# Controls:

[row]
    [column]
        [image align=left src=http://i.imgur.com/6CNoFYx.png alt='Move player character']
    [/column]
    [column]
        [image align=center src=http://i.imgur.com/8nwaVo0.png alt=Jump]
    [/column]
    [column]
        [image align=right src=http://i.imgur.com/QsbkkuZ.png alt='Go down through platforms']
    [/column]
[/row]

当运行以下代码时

$parsedDescription = (new Parsedown())
    ->setSafeMode(true)
    ->setUrlsLinked(false)
    ->text($this->description);

$compiledDescription = Shortcode::compile($parsedDescription);

我们可以预期看到以下输出

<h1>Controls:</h1>
<p></p>
<div class="container-fluid">
    <div class="row">
        <div class="col">
            <img src="http://i.imgur.com/6CNoFYx.png" class="mr-auto" alt="Move player character">
        </div>
        <div class="col">
            <img src="http://i.imgur.com/8nwaVo0.png" class="mx-auto" alt="Jump">
        </div>
        <div class="col">
            <img src="http://i.imgur.com/QsbkkuZ.png" class="ml-auto" alt="Go down through platforms">
        </div>
    </div>
</div>

您仍然应该在短语的handle中转义任何用户输入。

测试

运行以下命令以测试软件包。

composer test

安全

有关任何安全相关的问题，请发送邮件至peterchrjoergensen+shortcodes@gmail.com，而不是使用问题跟踪器。

变更日志

有关更改的详细信息，请参阅CHANGELOG。

贡献

有关如何贡献的详细信息，请参阅CONTRIBUTING。

致谢

• Peter Jørgensen
• 所有贡献者

灵感来源于https://github.com/webwizo/laravel-shortcodes和https://github.com/spatie/laravel-blade-x

关于

我在丹麦工作，是一名Web开发者，专注于Laravel和WordPress网站。

在Twitter上关注我@tehwave！

许可证

MIT许可证