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的Eloquent-Sluggable包旨在自动处理所有这些，配置量最小。

安装

根据您的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或其他您想要的任何合适名称；您的配置数组将确定数据将存储在哪个字段。您需要手动通过自己的迁移添加该列（该列应该是NULLABLE）。

这就完成了...您的模型现在是“可生成缩略名”的！

使用

保存模型很简单

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

检索缩略名也很简单

echo $post->slug;

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

$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"

注意：空字符串、非字符串或其他“奇怪”的源值将导致不同的缩略名

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

SlugService类

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

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

use \Cviebrock\EloquentSluggable\Services\SlugService;

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

这对于Ajax控制器或其他类似情况很有用，在这些情况下，您想在创建模型之前显示用户给定测试输入的缩略名。该方法的前两个参数是要测试的模型和缩略名字段，第三个参数是要用于测试缩略名的源字符串。

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

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

何时对模型进行短链接处理？

目前，模型在Eloquent的saving事件上进行缩略。这意味着在将任何新数据写入数据库之前会生成缩略名。

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

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

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

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

这种行为是一个破坏性更改，并且可能不会影响大多数用户（除非你在模型的自定义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"。

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

"slugged"事件在生成slug之后触发。如果模型不需要slugging（由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()方法处理。该方法应返回一个索引数组，其中键表示存储slug值的字段，值是该字段的配置。这意味着您可以根据不同的源字符串和不同的配置选项为同一模型创建多个slug。

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

源

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

要引用相关模型的字段，请使用点表示法。例如，以下书籍的slug将根据其作者的名字和书名生成：

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()的值作为slug生成的源。

方法

定义将可slug字符串转换为slug的方法。此配置有三个可能的选项

当method为null（默认设置）时，包使用默认的slugging引擎-- cocur/slugify --来创建slug。
当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的其他任何值都会抛出异常。

有关更复杂的slugging需求，请参阅下文中的扩展Sluggable。

更新时

默认情况下，更新模型不会尝试生成新的slug值。假设一旦生成了slug，就不希望它改变（如果您使用slug作为URL，并且不想破坏您的SEO流量，这可能尤其正确）。

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

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

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

分隔符

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

唯一

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

将unique设置为true，则第二个文章模型的slug将转换为“my-blog-post-1”。如果有一个标题相同的第三个文章，它将转换为“my-blog-post-2”，依此类推。每个后续模型都将附加一个递增值到slug的末尾，以确保唯一性。

唯一后缀

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

该函数应接受四个参数

基本slug（即非唯一slug）
分隔符字符串
一个以相同slug开头的所有其他slug的\Illuminate\Support\Collection
第一个要使用的后缀（对于需要生成唯一slug的第一个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，因此软删除的模型在检查唯一性时不计入。

保留

一个数组，其中包含永远不会被允许作为slug的值，例如，防止与现有路由或控制器方法等冲突。这可以是一个数组，也可以是一个返回数组的闭包。默认为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为空（默认设置）时，该包使用默认的slugify引擎 -- cocur/slugify -- 来创建slug。如果您想在引擎实例化时传递一组自定义选项给Slugify构造函数，您就可以在这里定义这些选项。有关这些选项的详细信息，请参阅Slugify文档。另外，请查看customizeSlugEngine，了解其他自定义Slugify以用于slug的方法。

简短配置

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

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

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

扩展可短链接的

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

在这种情况下，该包提供对slugify工作流程的钩子，您可以在每个模型的基础上使用自己的函数，或者在自己的trait中扩展包的trait。

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

/**
 * 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引擎可以在slugify发生之前进行自定义。这可能就是您更改所使用的字符映射或修改语言文件等的地方。

您可以根据模型和属性来自定义引擎（例如，您的模型可能有两个slug字段，其中一个需要自定义）。

请参阅tests/Models/PostWithCustomEngine.php以获取示例。

另外，请参阅slugEngineOptions配置以了解其他自定义Slugify的方法。

带有唯一短链接约束的范围

/**
 * @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
{
    // ...
}

此方法应用于确定给定slug是否唯一的查询。传递给作用域的参数是

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

您可以根据需要使用这些值来编写查询作用域。例如，请查看tests/Models/PostWithUniqueSlugConstraints.php，其中slug是从标题生成的，但slug被限制在作者范围内。因此，Bob可以有一个与Pam的帖子相同的标题，但两者将具有相同的slug。

查找类似短链接的范围

/**
 * 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
{
    // ...
}

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

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

可短链接范围助手特性

将可选的SluggableScopeHelpers trait添加到您的模型中，允许您处理模型及其slugs。例如

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

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

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

由于模型可能有多个slug，这需要更多的配置。请参阅SCOPE-HELPERS.md以获取所有详细信息。

路由模型绑定

请参阅ROUTE-MODEL-BINDING.md以获取详细信息。

错误、建议、贡献和支持

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

请使用GitHub来报告错误，发表评论或提出建议。

有关如何贡献更改，请参阅CONTRIBUTING.md。

版权和许可

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

pavelpaliy / eloquent-sluggable

维护者

详细信息