pine3ree/pine3ree-plates-extension

一个常见的基于抽象的 Plates 扩展，具有自动注册方法和更多功能

维护者

详细信息

github.com/pine3ree/pine3ree-plates-extension

主页

源代码

问题

文档

安装: 5

依赖: 0

建议者: 0

安全: 0

星标: 1

关注者: 1

分支: 0

开放问题: 0

1.0.1 2023-07-09 11:32 UTC

Requires

Requires (Dev)

BSD-3-Clause 4e7b6397baed197f918f36aceadc4413105a0d9c

templateextensionplatespine3ree

This package is auto-updated.

Last update: 2024-09-15 22:55:16 UTC

README

此包引入了一个通用的基于抽象的扩展，用于 Plates 原生 PHP 模板引擎，提供以下功能：

  • 自动注册公共方法（可以禁用此功能）
  • 手动以简短语法注册公共方法的能力
  • 在扩展注册时添加函数别名的能力
  • 在扩展注册之前添加函数别名的能力

自动注册公共方法

默认情况下，除了魔术方法外，所有公共方法都注册为 Plates 引擎的模板助手，使用方法名称作为模板助手名称，基本上为你执行以下操作：

<?php

namespace my\App\Plates;

use League\Plates\Engine;
use League\Plates\Extension\ExtensionInterface

class MyCoolExtension implements ExtensionInterface
{
    public function register(Engine $engine)
    {
        $engine->registerFunction('foo', [$this, 'foo']);
        $engine->registerFunction('baz', [$this, 'baz']);
    }

    public function foo(string $bar): string
    {
        return 'foo' . $bar;
    }

    public function baz(string $bar): string
    {
        return $bar . 'baz';
    }

    //...
}

你可以将之前的代码重写为

<?php

namespace my\App\Plates;

use League\Plates\Extension\ExtensionInterface
use pine3ree\Plates\Extension

class MyCoolExtension extends Extension implements ExtensionInterface
{
    public function foo(string $bar): string
    {
        return 'foo' . $bar;
    }

    public function baz(string $bar): string
    {
        return $bar . 'baz';
    }

    //...
}
<?php
// file: path/to/templates/my-template.phtml

use League\Plates\Template\Template;
use My\App\Plates\MyCoolExtension;

/** @var Template|MyCoolExtension $this */

禁用自动注册并手动注册你的公共方法

如果你不想将所有扩展的公共方法包含为模板助手，可以通过构造函数或属性分配禁用自动注册，或者覆盖扩展的 register 方法，但最后一个选项将移除此包提供的其他功能。

<?php

namespace my\App\Plates;

use League\Plates\Engine;
use League\Plates\Extension\ExtensionInterface

class MyCoolExtension implements ExtensionInterface
{
    // 1. Disable via class property override
    protected bool $autoregisterPublicMethods = false;
    
    // 2.a Disable via constructor
    public function __construct()
    {
        $this->autoregisterPublicMethods = false;
    }

    // 2.b Customize via constructor (for factories reading configuration)
    public function __construct(bool $autoregisterPublicMethods)
    {
        $this->autoregisterPublicMethods = $autoregisterPublicMethods;
    }

    // 3. Disable via 'register' method override (not advisable, please read following sections)
    public function register(Engine $engine)
    {
        // Manually register your public method keeping the methods'name as template helper name
        $this->registerOwnFunction($engine, 'foo');

        // Manually register your public method 'baz' using different helper name 'doBaz'
        $this->registerOwnFunction($engine, 'baz', 'doBaz');
    }

    public function foo(string $bar): string
    {
        return 'foo' . $bar;
    }

    public function baz(string $bar): string
    {
        return $bar . 'baz';
    }

    //...
}

注册其他函数和别名

此包提供了一些可覆盖的方法，其中你可以注册除了扩展的公共方法之外的其他函数或注册到已注册函数的别名

namespace my\App\Plates;

use League\Plates\Engine;
use League\Plates\Extension\ExtensionInterface

/**
 * Include your external methods to achieve full ide-autocompletion in template files
 *
 * @method string toUppercase(string $string) Convert string to uppercase
 * @method string uc(string $string) Alias of @see self:.toUppercase()
*/
class MyCoolExtension implements ExtensionInterface
{
    protected function registerFunctions(Engine $engine): void
    {
        $engine->registerFunction($engine, 'toUppercase', function (string $string): string {
            return mb_strtoupper($string);
        });
    }

    protected function registerAliases(Engine $engine): void
    {
        $this->registerAlias($engine, 'uc', 'toUppercase');
    }
}

在不继承的情况下注册别名

你有机会在第三方扩展扩展此包的抽象类并在 Plates 引擎中进行注册之前注册额外的别名，例如在扩展工厂内部。

use League\Plates\Engine;
use Third\Party\Plates\OtherExtension;
use Third\Party\Plates\OtherExtensionFactory;

// $plates is the app League\Plates\Engine instance
// $container is the app Psr\Container\ContainerInterface
// OtherExtension extends pine3ree\Plates\Extension providing `doSomething` 
// and `doSomethingElse` template helpers

$otherExtension = OtherExtensionFactory::create($container);

// Add aliases here before extension registration (or inside your application 
// OtherExtension factory)

$otherExtension->addAlias('ds', 'doSomething');
$otherExtension->addAlias('dse', 'doSomethingElse');

$plates->loadExtension($otherExtension);

使用 addAlias($alias, $funcName) 添加的别名实际上是在扩展由 Plates 引擎加载时注册的，在自动注册公共方法之后，在注册额外方法和注册内部定义的别名之后。请参阅 Extension::register(Engine $engine) 的源代码。

安装

此库需要 php >= 7.4

在您的项目目录中运行以下 shell 命令以安装它

$ composer require pine3ree/pine3ree-plates-extension

“为什么”...

“之前”...

<?php

namespace App\Plates\Extension;

// Other imports here
use League\Plates\Engine;
use League\Plates\Extension\ExtensionInterface;
// Other imports here

class FormExtension implements ExtensionInterface
{
    public function register(Engine $engine)
    {
        // Fieldsets/collections
        $engine->registerFunction($engine, [$this, 'form']);
        $engine->registerFunction($engine, [$this, 'formCollection']);
        $engine->registerFunction($engine, [$this, 'formFieldset']);
        $engine->registerFunction($engine, [$this, 'formLegend']);
        // Fields
        $engine->registerFunction($engine, [$this, 'formField']);
        $engine->registerFunction($engine, [$this, 'formRow']);
        $engine->registerFunction($engine, [$this, 'formLabel']);
        $engine->registerFunction($engine, [$this, 'formElement']);
        // Error messages
        $engine->registerFunction($engine, [$this, 'formErrors']);
        $engine->registerFunction($engine, [$this, 'formElementErrors']);
        // Inputs
        $engine->registerFunction($engine, [$this, 'formInput']);
        $engine->registerFunction($engine, [$this, 'formCheckbox']);
        $engine->registerFunction($engine, [$this, 'formColor']);
        $engine->registerFunction($engine, [$this, 'formCsrf']);
        $engine->registerFunction($engine, [$this, 'formDate']);
        $engine->registerFunction($engine, [$this, 'formDateTime']);
        $engine->registerFunction($engine, [$this, 'formDateTimeLocal']);
        $engine->registerFunction($engine, [$this, 'formEmail']);
        $engine->registerFunction($engine, [$this, 'formFile']);
        $engine->registerFunction($engine, [$this, 'formHidden']);
        $engine->registerFunction($engine, [$this, 'formImage']);
        $engine->registerFunction($engine, [$this, 'formMonth']);
        $engine->registerFunction($engine, [$this, 'formNumber']);
        $engine->registerFunction($engine, [$this, 'formPassword']);
        $engine->registerFunction($engine, [$this, 'formRange']);
        $engine->registerFunction($engine, [$this, 'formReset']);
        $engine->registerFunction($engine, [$this, 'formSearch']);
        $engine->registerFunction($engine, [$this, 'formSubmit']);
        $engine->registerFunction($engine, [$this, 'formText']);
        $engine->registerFunction($engine, [$this, 'formTel']);
        $engine->registerFunction($engine, [$this, 'formTime']);
        $engine->registerFunction($engine, [$this, 'formUrl']);
        $engine->registerFunction($engine, [$this, 'formWeek']);
        // Selects
        $engine->registerFunction($engine, [$this, 'formSelect']);
        $engine->registerFunction($engine, [$this, 'formDateTimeSelect']);
        $engine->registerFunction($engine, [$this, 'formDateSelect']);
        $engine->registerFunction($engine, [$this, 'formMonthSelect']);
        // Groups
        $engine->registerFunction($engine, [$this, 'formRadioGroup']);
        $engine->registerFunction($engine, [$this, 'formCheckboxGroup']);
        $engine->registerFunction($engine, [$this, 'formRadio']);
        $engine->registerFunction($engine, [$this, 'formMultiCheckbox']);
        // Others
        $engine->registerFunction($engine, [$this, 'formTextarea']);
        $engine->registerFunction($engine, [$this, 'formButton']);

        // Extension configuration helpers
        $engine->registerFunction($engine, [$this, 'setFormExtensionDefaultClasses']);
        $engine->registerFunction($engine, [$this, 'setFormFieldClass']);
        $engine->registerFunction($engine, [$this, 'setFormFieldsetClass']);
        $engine->registerFunction($engine, [$this, 'setFormControlClass']);
        $engine->registerFunction($engine, [$this, 'setFormButtonClass']);
        $engine->registerFunction($engine, [$this, 'setFormFieldWrap']);
        $engine->registerFunction($engine, [$this, 'setFormLabelImplicit']);
        $engine->registerFunction($engine, [$this, 'setFormLabelClass']);
        $engine->registerFunction($engine, [$this, 'setFormLabelTextClass']);
        $engine->registerFunction($engine, [$this, 'setFormCheckOptionClass']);
        $engine->registerFunction($engine, [$this, 'setFormCheckInputClass']);
        $engine->registerFunction($engine, [$this, 'setFormCheckLabelClass']);
        $engine->registerFunction($engine, [$this, 'setFormRangeClass']);
        $engine->registerFunction($engine, [$this, 'setFormSelectClass']);
        $engine->registerFunction($engine, [$this, 'setFormGroupClass']);
        $engine->registerFunction($engine, [$this, 'setFormDelimiterClass']);
        $engine->registerFunction($engine, [$this, 'setFormErrorsTag']);
        $engine->registerFunction($engine, [$this, 'setFormErrorsClass']);
        $engine->registerFunction($engine, [$this, 'setFormFieldErrorClass']);
        $engine->registerFunction($engine, [$this, 'setFormElementErrorClass']);
        $engine->registerFunction($engine, [$this, 'setFormCollectionTemplate']);
    }
    //...
    // Methods implementation here
    //..
}

...以及“之后”

<?php

namespace App\Plates\Extension;

// Other imports here
use League\Plates\Extension\ExtensionInterface;
use pine3ree\Plates\Extension;
// Other imports here

class FormExtension extends Extension implements ExtensionInterface
{
    //...
    // Methods implementation here
    //..
}