README

这是一个主要用于 Perch CMS 的工具库

安装

建议通过 Composer 使用 require 命令进行安装，如下所示：

$ composer require cognetif/perch-cms-utlities

开发要求

PHP 7.2
Composer
PHP Unit 8+
XDebug：用于代码覆盖率报告

测试

要从项目根目录运行应用程序的测试，请执行： $ ./phpunit 测试使用 PHP Unit 运行，构建报告可以在以下位置找到：/Tests/Report/index.html。

当将提交推送到 develop 或 master 时，PHP 7.2 和 PHP 7.3 的测试会自动作为 CI 流水线的一部分运行。

许可证

本项目采用 MIT 许可证。它是免费的、开源的，且对 GPL 友好。您可以使用它进行商业项目、开源项目，或几乎任何您想做的事情。

本项目维护者不对使用本软件导致的任何损失承担任何责任。

使用方法

本项目中的大多数工具都可以通过常规的 Composer 自动加载包括在内。有一些例外

模板过滤器

要包含特定的模板过滤器，您需要启用 perch 的模板过滤器功能 config.php 文件

define('PERCH_TEMPLATE_FILTERS', true);

并在 perch/addons/templates/filters.php 中注册每个模板过滤器

# Rot13Filter
PerchSystem::register_template_filter('rot13', '\Cognetif\PerchCms\TemplateFilters\Rot13Filter');

然后，在模板字段上使用模板过滤器

    <perch:content id="email" type="text" filter="rot13" label="Email" />

集合

尝试使用 Collection 对象代替数组，这会大大减少内存消耗。此外，它们的使用方式几乎与数组相同。它们是类型化的，因此您不需要担心元素是否是正确类或原始类型的实例

    $typeCollection = Cognetif\PerchCms\App\Collection::forType('My\Application\Namespace\MyTypeClass');
    // or
    $intCollection =  Cognetif\PerchCms\App\Collection::forInt();
    // or
    $floatCollection =  Cognetif\PerchCms\App\Collection::forFloat();
    // or
    $boolCollection =  Cognetif\PerchCms\App\Collection::forBoolean();
    // or
    $stringCollection =  Cognetif\PerchCms\App\Collection::forString();

集合函数

每个集合都有以下 API

Collection::add($value, $key = null): self : 向集合添加项，可选地带有键。
Colleciton::has($key):bool : 如果在集合中通过键找到项，则返回 true。
Colleciton::get($key) : 如果在集合中通过键找到项，则返回该项，如果没有找到，则返回 null。

计数和迭代集合

集合实现了 \Countable 接口和 IteratorAggregate 接口，因此它们可以在 foreach 循环和 count 函数中使用，就像数组一样。您主要用数组做什么，对吧？

Perch CMS 工厂包装器

该库中存在两个类，旨在帮助实现自定义应用程序的 Perch 工厂方法。

use Cognetif\PerchCms\App\Factory;
use Cognetif\PerchCms\App\ValidatedModel;

Factory 类是 PerchAPI_Factory 类的包装器，但包括 standard_restrictions() 函数，用于填充 sql 语句的 where 子句。要在扩展的子类中使用，只需将 $this->where 属性设置为类似 AND ... 的内容，这将用作 PerchFactory 中使用的 sql 语句的第一部分。请注意，每次调用 standard_restrictions() 时，where 条件都会重置为 ''，因此如果需要对所有查询使用静态内容，您可以覆盖 standard_restrictions() 函数以提供该功能。

ValidatedModel 类提供了一种验证用于 PerchAPI_Base 对象的数据的方法。在扩展了 ValidatedModel 类的类中，你可以使用 ValidatedModel::addValidator(string $field, ValidatorAbstract $validator) 函数。这将对给定的字段应用给定的验证规则。为了验证模型，请在构造函数中添加你的字段验证器。

    /** MyModel.php */
    use \Cognetif\PerchCms\App\ValidatedModel;
    use Cognetif\PerchCms\App\Validation\Validators\Required;
    use Cognetif\PerchCms\App\Validation\Validators\MaxLength;
    use Cognetif\PerchCms\App\Validation\Validators\Multi;

    class MyModel extends ValidatedModel
    {
        public function __construct() {
            parent::__construct();

            /**
            * Adds a required validator to the 'email' field
            * Adds a required AND max length of 45 chars validators to the 'first_name' field. 
            */
            $this->addValidator('email', new Required('Property 1 is required'))
                 ->addValidator('first_name', 
                        (new Multi())->addValidator(new Required('First name is required'))
                                     ->addValidator(new MaxLength(45, 'First name must be at most 45 characters'))
                 );
        }
    
    }

然后在你的应用程序的其他地方，你可以使用实例创建验证

    $model = new MyModel();
    $response = $model->validateData(['email' => 'me@email.com']);

或者静态验证

    $response = MyModel::Validate(['email' => 'me@email.com']);

或者验证自身

        $model = new MyModel(['email' => 'me@email.com']);
        $response = $model->validateSelf();

validateData 和 Validate 函数都返回一个 ValidationResponse 对象，你可以从中验证模型是否通过验证，并从响应体中检索未通过验证的每个字段的错误信息。

    /** @var Cognetif\PerchCms\App\Validation\ValidationResponse $response */
    if (!$response->isValid()){
        foreach($response->getBody as $field => $message) {
            echo "Field: {$field}  Error:  {$message}";
        }
    }

验证模块

ValidatedModel 对象中显示的验证器也可以单独使用

关于 $inclusive 标志的说明：默认为 true，当测试范围时，inclusive 将包含范围的边界，当为 false 时，边界将超出范围。关于 $strict 标志的说明：默认为 true，当测试数字验证器时，如果开启了严格模式，验证器将考虑类型。如果关闭，任何类型的数字表示都将通过，例如：10，10.0，'10' 都将通过在严格模式关闭时通过的 FloatValue 和 IntegerValue 验证器。

验证值

所有验证器都实现了 ValidationInterface，要求验证器实现一个 validate($value):bool 函数。它们还应扩展 ValidatorAbstract 验证器以继承消息和严格功能。

必需验证器示例

    $value = $_GET['param'];
    $validator = new Required('Please enter a value for param');
    if (!$validator->validate($value)) {
        echo $validator->getMessage();
    }

为单个值链式验证器

有一种特殊的验证器，它本身是验证器集合

Cognetif\PerchCms\App\Validation\Validators\Multi

这个验证器一旦实例化，就可以通过链式调用其自己的 Multi::addValidator(ValidatorAbstract $validator) 方法向相同的值添加多个验证器


    $value = $_GET['param'];
    $validator= new Multi();
    $validator->addValidator(new Required('Param is required'))
              ->addValidator(new MaxLength(45,  'Param must be at most 45 characters'));

    if (!$validator->validate($value)) {
            echo $validator->getMessage();
    }

注意，Multi 验证器将在第一个失败时停止验证，并且消息将表示失败的验证器。

验证器类型

所有来自 Cognetif\PerchCms\App\Validation\Validators 命名空间

Between($min, $max, bool $inclusive = true, string $message = '') : 验证整数或浮点值是否在最小和最大值之间。Null 和其他类型将返回 false。
FloatValue(string $message = '', bool $strict = true) : 验证值的类型是否为 Float。
IntegerValue(string $message = '', bool $strict = true): 验证值的类型是否为 Integer。
MaxValue($max, bool $inclusive = true, string $message = '') : 验证值小于最大边界。
MinValue($min, bool $inclusive = true, string $message = '') : 验证值大于最小边界。
MaxLength(int $length = 0, string $message = '') : 验证值不大于给定的长度。
MinLength(int $length = 0, string $message = '') : 验证值不小于给定的长度。
Multi() : 将多个验证器链式连接在一起进行验证。在第一个失败时停止验证。
Regexp(string $pattern = '', string $message = '') : 验证值是否与正则表达式模式匹配。
Required(string $message = '') : 验证值是否存在。

cognetif / perch-cms-utilities

维护者

详细信息