README

Eloquent 模型规范化特性

此包提供了一种特性，用于在保存任何 Eloquent 模型时生成规范化字段。

$model = new EloquentModel();
$model->name = 'HeLlO WoRLd';
$model->save();

$model->name_canonical === 'hello world';

安装

通过 Composer

$ composer require boomdraw/laravel-canonicalizable

Lumen

在引导文件中取消以下行的注释

// bootstrap/app.php:
$app->withEloquent();
$app->withFacades();

注册 CanonicalizerServiceProvider

// bootstrap/app.php:
$app->register(Boomdraw\Canonicalizer\CanonicalizerServiceProvider::class);

用法

您的 Eloquent 模型应使用 Boomdraw\Canonicalizable\HasCanonical 特性、Boomdraw\Canonicalizable\CanonicalFieldsCollection 和 Boomdraw\Canonicalizable\CanonicalField 类。

该特性包含一个抽象方法 getCanonicalFields()，您必须自行实现。

您的模型迁移应包含一个字段以保存规范化值。

以下是如何实现该特性的示例

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;
use Boomdraw\Canonicalizable\HasCanonical;
use Boomdraw\Canonicalizable\CanonicalField;
use Boomdraw\Canonicalizable\CanonicalFieldsCollection;

class YourEloquentModel extends Model
{
    use HasCanonical;
    
    /**
     * Get the options for generating the canonical.
     */
    public function getCanonicalFields(): CanonicalFieldsCollection
    {
        return CanonicalFieldsCollection::create()
            ->addField(
                CanonicalField::create()
                    ->from('name')
            )->addField(
                CanonicalField::create()
                    ->from('email')
                    ->type('email')
                    ->to('canonicalized_email')
                    ->doNotGenerateOnUpdate()
            );
    }
}

及其迁移

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

class CreateYourEloquentModelTable extends Migration
{
    /**
     * Run the migrations.
     *
     * @return void
     */
    public function up()
    {
        Schema::create('your_eloquent_models', function (Blueprint $table) {
            $table->increments('id');
            $table->string('name');
            $table->string('name_canonicalized'); // Field name same as your `to`
            $table->string('email');
            $table->string('canonicalized_email'); // Field name same as your `to`
            $table->timestamps();
        });
    }
}

默认情况下，该包将生成非唯一规范化字段。您可以通过调用 disallowDuplicate() 来禁止重复。

public function getCanonicalFields(): CanonicalFieldsCollection
{
    return CanonicalFieldsCollection::create()
        ->addField(
            CanonicalField::create()
                ->from('name')
                ->disallowDuplicate()
        );
}

即使已手动设置并使用 doNotGenerateOnUpdate 或 doNotGenerateOnCreate，也会检查规范化的唯一性。

规范化的唯一性将通过追加 - 和一个数字来保证。

要添加规范化和数字之间的自定义分隔符，请将其作为参数传递给 disallowDuplicate()。

public function getCanonicalFields(): CanonicalFieldsCollection
{
    return CanonicalFieldsCollection::create()
        ->addField(
            CanonicalField::create()
                ->from('name')
                ->disallowDuplicate('#')
        );
}

您可以通过提供字段类型来调用自定义规范化方法。

public function getCanonicalFields() : CanonicalFieldsCollection
{
    return CanonicalFieldsCollection::create()
        ->addField(
            CanonicalField::create()
                ->from('name')
                ->type('other')
        );
}

特性将在模型中查找 canonicalizeOther(string $string) 方法，并在 boomdraw/canonicalizer 及其 宏 中查找 other(string $string) 方法。

规范化方法也可以通过使用 callback 函数来提供。

public function getCanonicalFields() : CanonicalFieldsCollection
{
    return CanonicalFieldsCollection::create()
        ->addField(
            CanonicalField::create()
                ->from('name')
                ->callback(function($string) {
                    return mb_strtoupper($string);
                })
        );
}

如果提供了 callback 函数，则忽略类型。

您可以通过在类型方法中提供参数数组来向基于类型的类型方法传递额外的参数。

public function getCanonicalFields() : CanonicalFieldsCollection
{
    return CanonicalFieldsCollection::create()
        ->addField(
            CanonicalField::create()
                ->from('name')
                ->type('custom', [$arg1, $arg2])
                ->callback(function($string, $arg, $arg2) {
                    return mb_strtoupper($string.$arg.$arg2);
                })
        )->addField(
             CanonicalField::create()
                 ->from('name')
                 ->type('slug', [$separator])
        );
}

您也可以通过将其设置为与生成的规范化值不同的值来覆盖生成的规范。

$model = EloquentModel::create(['name' => 'John']); //The canonical is now "john"; 
$model->name_canonical = 'Ivan';
$model->save(); //The canonical is now "Ivan"; 

要强制在手动设置规范化时进行规范化，请使用 forceCanonicalization() 方法。

public function getCanonicalFields() : CanonicalFieldsCollection
{
    return CanonicalFieldsCollection::create()
        ->addField(
             CanonicalField::create()
                 ->from('name')
                 ->type('slug')
                 ->forceCanonicalization()
        );
}
...
$model = EloquentModel::create(['name' => 'John']); //The canonical is now "john"; 
$model->name_canonical = 'Test User';
$model->save(); //The canonical is now "test-user"; 

public function getCanonicalFields() : CanonicalFieldsCollection
{
    return CanonicalFieldsCollection::create()
        ->addField(
             CanonicalField::create()
                 ->from('name')
                 ->to('name')
                 ->type('slug')
                 ->forceCanonicalization()
        );
}
...
$model = EloquentModel::create(['name' => 'John']); //The is now "john"; 
$model->name = 'Test User';
$model->save(); //The name is now "test-user"; 

如果您不想在模型最初创建时创建规范，请使用 doNotGenerateOnCreate() 函数。

public function getCanonicalFields() : CanonicalFieldsCollection
{
    return CanonicalFieldsCollection::create()
        ->addField(
            CanonicalField::create()
                ->from('name')
                ->doNotGenerateOnCreate()
        );
}

如果您不想在模型最初创建时创建规范，请使用 doNotGenerateOnUpdate() 函数。

public function getCanonicalFields() : CanonicalFieldsCollection
{
    return CanonicalFieldsCollection::create()
        ->addField(
            CanonicalField::create()
                ->from('name')
                ->doNotGenerateOnUpdate()
        );
}

这可以帮助创建直到您明确想要更改的字段。

$model = EloquentModel::create(['name' => 'John']); //The canonical is now "john"; 
$model->save();

$model->name = 'Ivan';
$model->save(); //The canonical stays "john"

如果您想显式更新模型上的规范，您可以在任何时间调用模型上的 canonicalize(string $fieldName) 来根据其他选项重新生成规范。别忘了 save() 模型以将更新持久化到数据库。

变更日志

请参阅 CHANGELOG 了解最近更改的详细信息。

测试

您可以使用以下命令运行测试

composer test

贡献

有关详细信息以及待办事项列表，请参阅 CONTRIBUTING。

安全

如果您发现任何与安全相关的问题，请通过电子邮件 pkgsecurity@boomdraw.com 而不是使用问题跟踪器来报告。

许可证

MIT 协议