README

轻松为Laravel中的Eloquent模型创建短链接。

注意：以下说明适用于最新版本的Laravel。
如果您使用的是旧版本，请安装与您的Laravel版本相对应的包版本。

Eloquent-Sluggable

背景：什么是短链接？

短链接是字符串的简化版本，通常是URL友好的。对字符串进行“短链接”操作通常涉及将其转换为单一种大小写，并删除任何非URL友好的字符（空格、带重音的字母、和号等）。生成的字符串可以用来作为特定资源的标识符。

例如，如果您有一个博客，其中包含帖子，您可以通过ID引用每个帖子

http://example.com/post/1
http://example.com/post/2

...但这并不特别友好（尤其是对于SEO）。您可能更希望使用帖子的标题作为URL，但如果您的帖子标题是“我与安德烈和弗朗索瓦的晚餐”，这看起来也很丑陋

http://example.com/post/My+Dinner+With+Andr%C3%A9+%26+Fran%C3%A7ois

解决方案是为标题创建一个短链接并使用它。您可能希望使用Laravel的内置Str::slug()方法将标题转换为更友好的格式

http://example.com/post/my-dinner-with-andre-francois

这样的URL会让用户更满意（它可读，易于输入等）。

有关更多信息，您可能想阅读维基百科上的此描述。

短链接通常也是唯一的。因此，如果您写另一篇具有相同标题的帖子，您将需要以某种方式区分它们，通常是在短链接的末尾添加一个递增计数器

http://example.com/post/my-dinner-with-andre-francois
http://example.com/post/my-dinner-with-andre-francois-1
http://example.com/post/my-dinner-with-andre-francois-2

这保持了URL的唯一性。

Laravel的包旨在自动处理所有这些，配置最少。

安装

根据您的Laravel版本，您应该安装不同版本的包。

注意：从版本6.0开始，包的版本应与Laravel版本相匹配。

较老的Laravel版本可以使用旧版本的包，尽管它们不再受支持或维护。有关详细信息，请参阅CHANGELOG.md和UPGRADING.md，并确保您正在阅读您版本的正确的README.md（GitHub默认在master分支中显示版本，这可能不是您想要的）。

通过Composer安装包
```
$ composer require cviebrock/eloquent-sluggable
```
包将自动注册其服务提供者。

可选地，如果您想更改任何默认值，可以发布配置文件

php artisan vendor:publish --provider="Cviebrock\EloquentSluggable\ServiceProvider"

更新您的Eloquent模型

您的模型应使用Sluggable特性，该特性包含一个抽象方法sluggable()，您需要对其进行定义。在这里可以设置任何特定模型的配置（有关详细信息，请参阅下面的配置）

use Cviebrock\EloquentSluggable\Sluggable;

class Post extends Model
{
    use Sluggable;

    /**
     * Return the sluggable configuration array for this model.
     *
     * @return array
     */
    public function sluggable(): array
    {
        return [
            'slug' => [
                'source' => 'title'
            ]
        ];
    }
}

当然，您的模型和数据库需要一个用于存储slug的列。您可以使用slug或任何其他合适的名称；您的配置数组将决定数据将存储在哪个字段中。您需要通过自己的迁移手动添加该列（该列应该是NULLABLE）。

就这样...您的模型现在是“可生成slug的”了！

使用

保存模型很简单

$post = Post::create([
    'title' => 'My Awesome Blog Post',
]);

检索slug也同样简单

echo $post->slug;

注意：如果您正在使用Eloquent的replicate()方法复制模型，包将自动重新生成slug以确保唯一性。

$post = Post::create([
    'title' => 'My Awesome Blog Post',
]);
// $post->slug is "my-awesome-blog-post"

$newPost = $post->replicate();
// $newPost->slug is "my-awesome-blog-post-1"

注意：空字符串、非字符串或其他“奇怪”的源值将生成不同的slug

（上述值还将受到任何唯一性或其他检查的影响。）

SlugService类

生成slug的所有逻辑都由\Cviebrock\EloquentSluggable\Services\SlugService类处理。

通常，您不需要直接访问此类，尽管有一个静态方法可以用来为给定的字符串生成slug，而无需实际创建或保存相关的模型。

use \Cviebrock\EloquentSluggable\Services\SlugService;

$slug = SlugService::createSlug(Post::class, 'slug', 'My First Post');

这对于Ajax控制器或类似的情况很有用，在这些情况下，您想在实际上创建模型之前显示用户给定的测试输入将生成的唯一slug。该方法的前两个参数是要测试的模型和slug字段，第三个参数是用于测试slug的源字符串。

您还可以传递一个可选的配置值数组作为第四个参数。这些值将覆盖要测试的slug字段的正常配置值。例如，如果您的模型配置为使用唯一slug，但出于某种原因您想要生成slug的“基础”版本，则可以执行以下操作：

$slug = SlugService::createSlug(Post::class, 'slug', 'My First Post', ['unique' => false]);

何时为模型创建短链接？

目前，模型是在Eloquent的saving事件上生成slug的。这意味着slug是在将任何新数据写入数据库之前生成的。

对于新模型，这意味着主键尚未设置，因此不能用作slug源的一部分，例如：

public function sluggable(): array
{
    return [
        'slug' => [
            'source' => ['title', 'id']
        ]
    ];
}

$model->id在模型保存之前是null。然而，挂钩到saving事件的优点是，我们只需要进行一次数据库查询即可保存所有模型的数据，包括slug。

可选的，模型可以在Eloquent的saved事件上生成slug。
这意味着所有其他模型属性都已持久化到数据库中，并且确实可用作slug源。因此，上述配置将工作。唯一的缺点是，将模型保存到数据库需要额外的查询：第一个查询用于保存所有非slug字段，然后第二个查询用于更新slug字段。

这种行为是一个破坏性的变化，并且可能不会影响大多数用户（除非您在模型的slug字段上执行某些预保存验证）。我们认为其优点超过了缺点，因此这可能会成为包未来主要版本的新默认行为。尽管如此，为了使过渡更容易，您可以通过特性提供的sluggableEvent方法来配置这种行为。

    public function sluggableEvent(): string
    {
        /**
         * Default behaviour -- generate slug before model is saved.
         */
        return SluggableObserver::SAVING;

        /**
         * Optional behaviour -- generate slug after model is saved.
         * This will likely become the new default in the next major release.
         */
        return SluggableObserver::SAVED;
    }

请注意，如果您想使用模型的主键作为slug源字段的一部分，则需要使用SluggableObserver::SAVED。

事件

Sluggable模型将触发两个Eloquent模型事件：“slugging”和“slugged”。

“生成别名”事件在生成别名之前触发。如果此事件的回调返回false，则不执行生成别名。如果返回其他任何内容，包括null，则将执行生成别名。

“已生成别名”事件在生成别名之后触发。如果模型不需要生成别名（由needsSlugging()方法确定），则不会调用此事件。

您可以通过像其他Eloquent模型事件一样的方式，将这些事件连接到任何地方。

Post::registerModelEvent('slugging', static function($post) {
    if ($post->someCondition()) {
        // the model won't be slugged
        return false;
    }
});

Post::registerModelEvent('slugged', static function($post) {
    Log::info('Post slugged: ' . $post->getSlug());
});

配置

配置旨在尽可能灵活。您可以为所有Eloquent模型设置默认值，然后为单个模型覆盖这些设置。

默认情况下，全局配置在config/sluggable.php文件中设置。如果未设置配置，则使用包默认值。以下是一个配置示例，显示了所有默认设置：

return [
    'source'             => null,
    'method'             => null,
    'onUpdate'           => false,
    'separator'          => '-',
    'unique'             => true,
    'uniqueSuffix'       => null,
    'firstUniqueSuffix'  => 2,
    'includeTrashed'     => false,
    'reserved'           => null,
    'maxLength'          => null,
    'maxLengthKeepWords' => true,
    'slugEngineOptions'  => [],
];

对于单个模型，配置由您需要实现的sluggable()方法处理。该方法应返回一个索引数组，键代表存储别名值的字段，值是该字段的配置。这意味着您可以根据不同的源字符串和不同的配置选项为同一模型创建多个别名。

public function sluggable(): array
{
    return [
        'title-slug' => [
            'source' => 'title'
        ],
        'author-slug' => [
            'source' => ['author.lastname', 'author.firstname'],
            'separator' => '_'
        ],
    ];
}

源

这是构建别名的字段或字段的数组。每个$model->field通过空格分隔连接，以构建可别名的字符串。这些可以是模型属性（即数据库中的字段）、关系属性或自定义获取器。

要引用相关模型的字段，使用点表示法。例如，以下书籍的别名将从其作者姓名和书籍标题生成：

class Book extends Eloquent
{
    use Sluggable;

    protected $fillable = ['title'];

    public function sluggable(): array
    {
        return [
            'slug' => [
                'source' => ['author.name', 'title']
            ]
        ];
    }
    
    public function author(): \Illuminate\Database\Eloquent\Relations\BelongsTo
    {
        return $this->belongsTo(Author::class);
    }
}
...
class Author extends Eloquent
{
    protected $fillable = ['name'];
}

使用自定义获取器的示例

class Person extends Eloquent
{
    use Sluggable;

    public function sluggable(): array
    {
        return [
            'slug' => [
                'source' => 'fullname'
            ]
        ];
    }

    public function getFullnameAttribute(): string
    {
        return $this->firstname . ' ' . $this->lastname;
    }
}

如果source为空、false或null，则将使用$model->__toString()的值作为生成别名的源。

方法

定义将可别名的字符串转换为别名的所使用的方法。此配置有三个可能的选项：

当method为null（默认设置）时，包使用默认的别名生成引擎——cocur/slugify——来创建别名。
当method是可调用的，那么将使用该函数或类方法。该函数/方法应期望两个参数：要处理的字符串和分隔符字符串。例如，要使用Laravel的Str::slug，您可以这样做：

'method' => ['Illuminate\\Support\\Str', 'slug'],

您还可以将method定义为闭包（再次，期望两个参数）

'method' => static function(string $string, string $separator): string {
    return strtolower(preg_replace('/[^a-z]+/i', $separator, $string));
},

对于method的任何其他值将抛出异常。

对于更复杂的别名生成要求，请参阅下面的扩展Sluggable。

onUpdate

默认情况下，更新模型不会尝试生成新的别名值。假设您的别名生成后，您不希望它改变（这可能特别适用于您使用别名作为URL，并且不希望破坏您的SEO效果）。

如果您想重新生成模型的一个或多个别名字段，在更新之前将这些字段设置为null或空字符串。

$post->slug = null;
$post->update(['title' => 'My New Title']);

如果您希望在每次更新模型时都执行此行为，则将onUpdate选项设置为true。

分隔符

这定义了构建别名时使用的分隔符，并将其传递给上面定义的method。默认值是连字符。

唯一

这是一个布尔值，定义别名是否应在给定类型的所有模型之间唯一。例如，如果您有两个博客文章，并且它们都称为“我的博客文章”，那么如果unique为false，它们都将别名为“my-blog-post”。这可能是一个问题，例如，如果您使用别名作为URL。

将unique设置为true，则第二个Post模型将被转换为“my-blog-post-1”。如果存在标题相同的第三个帖子，则将其转换为“my-blog-post-2”，依此类推。每个后续模型都将获得附加到slug末尾的增量值，以确保唯一性。

唯一后缀

如果您想使用其他方法来标识唯一性（除了自动递增的整数），则可以将uniqueSuffix配置设置为函数或可调用的对象，该对象为您生成“唯一”值。

该函数应接受四个参数

基本slug（即非唯一slug）
分隔符字符串
所有以相同slug开始的其它slug字符串的\Illuminate\Support\Collection
第一个要使用的后缀（对于第一个需要变为唯一的slug）您可以为创建一个尚未被集合中的任何slug使用的后缀执行任何操作。例如，如果您想使用字母而不是数字作为后缀，这是一种实现方式

'uniqueSuffix' => static function(string $slug, string $separator, Collection $list, $firstSuffix): string
    {
      $size = count($list);

      return chr($size + 96);
    }

首次唯一后缀

在添加唯一后缀时，我们从“2”开始计数，因此生成的slug列表看起来可能如下所示

my-unique-slug
my-unique-slug-2
my-unique-slug-3
等等。

如果您想从不同的数字开始（或将不同的值传递到上面的自定义uniqueSuffix函数中），则可以在此处定义。

注意：此包的早期版本从唯一后缀1开始。在版本8.0.5中，这被切换到2，因为它是附加到第二个slug的更“直观”的唯一值。

包含已删除的

将此设置为true将在尝试强制唯一性时检查已删除的模型。这仅影响使用软删除功能的Eloquent模型。默认值为false，因此软删除的模型在检查唯一性时不会被计算。

保留

一个不允许作为slugs的值的数组，例如，防止与现有的路由或控制器方法冲突等。这可以是一个数组，也可以是一个返回数组的闭包。默认为null：没有保留的slug名称。

最大长度

将此设置为正整数将确保生成的slug被限制在最大长度内（例如，以确保它们适合您的数据库字段）。默认值是null，不强制执行限制。

注意：如果启用了unique（默认情况下是启用的），并且您预计将具有几个具有相同slug的模型，那么您应该将此值设置为数据库字段长度的几个字符以下。原因是类将追加“-2”、“-3”、“-4”等，以保持后续模型的唯一性。这些增量扩展不包括在maxLength计算中。

最大长度保留单词

如果您正在使用maxLength设置截断slug，那么您可能想确保slug不会在单词中间被截断。例如，如果您的源字符串是“我的第一篇帖子”，并且您的maxLength是10，生成的slug将变成“my-first-p”，这不是理想的。

默认情况下，maxLengthKeepWords的值设置为true，这将从slug的末尾修剪部分单词，结果为“my-first”而不是“my-first-p”。

如果您想保留部分单词，则将此配置设置为false。

短链接引擎选项

当method为null（默认设置）时，该包使用默认的slugging引擎 -- cocur/slugify -- 来创建slug。如果您想在实例化引擎时传递自定义的选项集到Slugify构造函数，这里就是您定义的地方。有关这些选项的信息，请参阅Slugify文档。还可以查看customizeSlugEngine以获取其他自定义Slugify进行slugging的方法。

简短配置

如果您真的很懒，该包支持非常短的配置语法。

public function sluggable(): array
{
    return ['slug'];
}

这将会使用来自 config/sluggable.php 的所有默认选项，使用模型的 __toString() 方法作为源，并将短链接存储在 slug 字段中。

扩展Sluggable

有时配置选项不足以满足复杂需求（例如，可能需要考虑其他属性进行唯一性测试）。

在这种情况下，该软件包提供了对短链接工作流程的钩子，您可以在每个模型的基础上或是在扩展软件包特质的自定义特质中使用自己的函数。

注意：如果您将这些方法放入您自己的特质中，您需要在模型中指明PHP应使用您的特质方法而不是软件包的方法（因为一个类不能使用具有相同方法的两个特质），例如：

/**
 * Your trait where you collect your common Sluggable extension methods
 */
class MySluggableTrait {
    public function customizeSlugEngine(...) {}
    public function scopeWithUniqueSlugConstraints(...) {}
    // etc.
}

/**
 * Your model
 */
class MyModel {
    // Tell PHP to use your methods instead of the packages:
    use Sluggable,
        MySluggableTrait  {
            MySluggableTrait::customizeSlugEngine insteadof Sluggable;
            MySluggableTrait::scopeWithUniqueSlugConstraints insteadof Sluggable;
        }

    // ...
}

定制短链接引擎

/**
 * @param \Cocur\Slugify\Slugify $engine
 * @param string $attribute
 * @return \Cocur\Slugify\Slugify
 */
public function customizeSlugEngine(Slugify $engine, string $attribute): \Cocur\Slugify\Slugify
{
    // ...
    return $engine;
}

如果扩展此方法，则可以在短链接发生之前自定义Slugify引擎。这可能就是您更改所使用的字符映射或修改语言文件等的地方。

您可以根据每个模型和每个属性来自定义引擎（也许您的模型有两个短链接字段，其中一个需要自定义）。

请查看 tests/Models/PostWithCustomEngine.php 以获取示例。

此外，请查看 slugEngineOptions 配置以获取其他自定义Slugify的方式。

带有唯一短链接约束的scope

/**
 * @param \Illuminate\Database\Eloquent\Builder $query
 * @param \Illuminate\Database\Eloquent\Model $model
 * @param string $attribute
 * @param array $config
 * @param string $slug
 * @return \Illuminate\Database\Eloquent\Builder
 */
public function scopeWithUniqueSlugConstraints(
    Builder $query,
    Model $model,
    string $attribute,
    array $config,
    string $slug
): Builder
{
    // ...
}

此方法应用于确定给定短链接是否唯一的查询。传递给作用域的参数包括

$model -- 正在短链接的对象
$attribute -- 正在生成的短链接字段
$config -- 给定模型和属性的配置数组
$slug -- "基本"短链接（在应用任何唯一后缀之前）

您可以在查询作用域中随意使用这些值。例如，请查看 tests/Models/PostWithUniqueSlugConstraints.php，其中从标题生成短链接，但短链接被限制在作者范围内。因此Bob可以有一篇与Pam相同的标题的帖子，但两者将具有相同的短链接。

查找类似短链接的scope

/**
 * Query scope for finding "similar" slugs, used to determine uniqueness.
 *
 * @param \Illuminate\Database\Eloquent\Builder $query
 * @param string $attribute
 * @param array $config
 * @param string $slug
 * @return \Illuminate\Database\Eloquent\Builder
 */
public function scopeFindSimilarSlugs(Builder $query, string $attribute, array $config, string $slug): Builder
{
    // ...
}

这是用于找到模型"类似"短链接的默认作用域。基本上，该软件包查找与 $slug 参数相同的现有短链接，或以 $slug 加分隔符字符串开头的短链接。结果集合被传递给 uniqueSuffix 处理器。

通常，此查询作用域（在Sluggable特质中定义）应该保持不变。然而，您可以在模型中重载它。

SluggableScopeHelpers特性

将可选的 SluggableScopeHelpers 特质添加到您的模型中，允许您处理模型及其短链接。例如

$post = Post::whereSlug($slugString)->get();

$post = Post::findBySlug($slugString);

$post = Post::findBySlugOrFail($slugString);

由于模型可能具有多个短链接，这需要更多的配置。请参阅 SCOPE-HELPERS.md 了解所有详细信息。

路由模型绑定

请参阅 ROUTE-MODEL-BINDING.md 了解详细信息。

错误、建议、贡献和支持

感谢所有为此项目做出贡献的人！

请使用 GitHub 报告错误，并进行评论或建议。

请参阅 CONTRIBUTING.md 了解如何贡献更改。

版权和许可

eloquent-sluggable 由 Colin Viebrock 编写，并使用 MIT许可证发布。

版权（c）2013 Colin Viebrock

sajawd-yq / eloquent-sluggable-persian

维护者

详细信息