README

基于WordPress的短代码，为Laravel框架提供共享变量、调试栏集成、灵活的配置和其他有用功能。

使用短代码在内容或视图中构建强大且简单的布局，例如这样

[b]Bold text[/b]

[row]
  [col md=8]
    [posts_list types="post,gallery" show_tags="yes"]
  [/col]
  [col md=4]
    [poll id="1"]
    [user_info username="test_user" website="mywebsite.com" active="yes"]
    [last_free_post title="Free Posts"]
  [/col]
[/row]

安装

通过Composer

$ composer require vedmant/laravel-shortcodes

配置

发布配置。

php artisan vendor:publish --tag=shortcodes

它将发布配置文件 shortcodes.php，根据需要编辑它。

使用方法

短代码类

短代码类应该继承抽象类 \Vedmant\LaravelShortcodes\Shortcode。

此包添加了 make:shortcode artisan 命令

php artisan make:shortcode PostsListShortcode

该命令默认在 app/Shortcodes 文件夹中生成短代码类。

注册短代码

您可以使用 AppServiceProvider::boot 方法注册所有需要的短代码。

使用短代码类

Shortcodes::add('b', BShortcode::class);

对于大量的短代码，建议使用数组使用短代码类

Shortcodes::add([
   'a' => AShortcode::class,
   'b' => BShortcode::class,
]);

使用闭包

Shortcodes::add('test', function ($atts, $content, $tag, $manager) {
   return new HtmlString('<strong>some test shortcode</strong>');
});

渲染短代码

视图自动渲染

默认情况下，此包扩展了 View 类以在视图渲染期间解析所有短代码。此功能可以在配置文件中禁用： 'render_views' => false。对于大量视图，建议禁用视图自动渲染以获得更好的性能。

按视图启用/禁用渲染

您还可以使用以下方法启用/禁用特定视图的短代码渲染

view('some-view')->withShortcodes();
// Or
view('some-view')->withoutShortcodes();

使用外观渲染短代码

{{ Shortcodes::render('[b]bold[/b]') }}

使用blade指令渲染短代码

@shortcodes
   [b class="block"]Content[/b]
@endshortcodes

Or

@shortcodes('[b]bold[/b]')

使用 shortcodes() 辅助函数渲染短代码

<div class="some-block">
   {{ shortcodes('[b]bold[/b]') }}
</div>

共享属性

偶尔，您可能需要与应用程序中渲染的所有短代码共享一些数据。您可以使用短码外观的 share 方法这样做。通常，您应该在控制器或服务提供者启动方法中放置共享的调用。

Shortcodes::share('post', $post);

然后您可以在短代码类中获取共享属性

$post = $this->shared('post');
$allShared = $this->shared();

属性转换

您的短代码类上的 $casts 属性提供了一种将属性转换为常见数据类型的方法。$casts 属性应是一个数组，键是要转换的属性名称，值是要将列转换为的类型。支持的类型有： int、integer、real、float、double、boolean、array（以逗号分隔的值）和 date。

class YourShortcode extends Shortcode
{
    /**
     * The attributes that should be cast to native types.
     *
     * @var array
     */
    protected $casts = [
        'show_ids' => 'array',
    ];
}

现在当您访问 show_ids 属性时，它始终被转换为数组。 (数组属性是从逗号分隔的字符串转换而来的，例如 "1,2,3")。

属性验证

有一个简单的方法来验证属性。错误信息将在短代码位置渲染。为了方便，它将返回属性。

class YourShortcode extends Shortcode
{
    /**
     * Render shortcode
     *
     * @param string $content
     * @return string
     */
    public function render($content)
    {
        $atts = $this->validate([
            'post_id' => 'required|numeric|exists:posts,id', 
        ]);
    
        //
    }
}

从短代码中抛出异常的选项

有一个有用的选项，可以避免在其中一个短代码抛出异常时，整个页面（500）错误。

要启用它，请将 'throw_exceptions' => false, 设置在 shortcodes.php 配置文件中。

这将渲染异常详细信息在短代码的位置，并且不会用500错误崩溃整个页面请求。它仍然会将异常记录到日志文件中，如果集成了 Sentry，它还会报告。

为文档生成数据

可能存在数百个已注册的短代码，而能够显示所有短代码的文档是一种相当好的功能。存在一种简单的方法可以收集所有已注册短代码的描述和属性数据

$data = Shortcodes::registeredData();

它返回一个包含生成数据的Collection对象，这些数据可用于生成任何帮助信息。

与Laravel Debugbar集成

此包支持Laravel Debugbar，并添加一个包含渲染短代码详细信息的标签页。可以在配置文件中使用选项禁用集成：'debugbar' => false,。

测试

$ vendor/bin/phpunit

待办事项

1. 为调试器集成添加自定义小部件
2. 创建性能配置测试，优化性能

贡献

有关详细信息及待办事项清单，请参阅contributing.md。

安全

如果您发现任何安全相关的问题，请通过电子邮件vedmant@gmail.com联系，而不是使用问题跟踪器。

鸣谢

• 所有贡献者

许可证

MIT。请参阅许可证文件获取更多信息。