jamalhassouni/laravel-sluggable

为您的 Laravel 5 Eloquent 模型轻松创建短链接，支持阿拉伯语

维护者

详细信息

github.com/jamalhassouni/laravel-sluggable

主页

源代码

问题

安装: 7

依赖: 0

建议者: 0

安全: 0

星标: 0

关注者: 2

分支: 0

公开问题: 0

dev-master 2019-09-16 09:21 UTC

Requires

Requires (Dev)

MIT 69c952dce088ce625f5f352804a00710befa189c

  • Jamal Hassouni <jamalhassouni13.woop@gmail.com>

sluggablesluglaraveleloquentlumeneloquent-sluggablelaravel-sluggablenice-name

This package is auto-updated.

Last update: 2024-09-16 21:07:32 UTC

README

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

注意：以下说明适用于 Laravel 5.8。如果您使用的是 Laravel 5.7，请参阅上一个版本的文档。

Build Status Total Downloads Latest Stable Version Latest Unstable Version Scrutinizer Code Quality SensioLabsInsight License: MIT

背景：什么是短链接？

短链接是字符串的简化版本，通常是 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 5 的 Eloquent-Sluggable 包旨在自动处理所有这些，而配置量最小。

安装

注意：根据您的 Laravel 版本，您应安装不同版本的包

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

  1. 通过 Composer 安装包

    $ composer require jamalhassouni/laravel-sluggable

    包将自动注册其服务提供者。

  2. 可选，如果您想更改任何默认设置，则发布配置文件

    php artisan vendor:publish --provider="Jamalhassouni\LaravelSluggable\ServiceProvider"

更新您的 Eloquent 模型

您的模型应使用Sluggable特性，它包含一个抽象方法sluggable()，您需要定义它。在这里设置任何模型特定的配置（详情请见下文的配置）

use Jamalhassouni\LaravelSluggable\Sluggable;

class Post extends Model
{
    use Sluggable;

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

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

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

使用方法

保存模型很简单

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

$post->save();

检索slug也同样简单

echo $post->slug;

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

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

$post->save();
// $post->slug is "my-awesome-blog-post"

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

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

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

SlugService 类

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

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

use \Jamalhassouni\LaravelSluggable\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]);

事件

注意：事件应该可以正常工作，但尚未完全测试。请帮助我！

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

“slugging”事件在生成slug之前触发。如果此事件的回调返回false，则不执行slugging。

“slugged”事件在生成slug之后触发。在不需要slugging的情况下（由needsSlugging()方法确定），不会调用此事件。

您可以像其他任何Eloquent模型事件一样挂钩到这两个事件中的任何一个

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

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

配置

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

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

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

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

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

source

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

要从相关模型中引用字段，请使用点符号。例如，下面这本书的缩略名将由其作者姓名和书名生成。

class Book extends Eloquent
{
    use Sluggable;

    protected $fillable = ['title'];

    public function sluggable() {
        return [
            'slug' => [
                'source' => ['author.name', 'title']
            ]
        ];
    }

    public function author() {
        return $this->belongsTo(Author::class);
    }
}
...
class Author extends Eloquent
{
    protected $fillable = ['name'];
}

使用自定义获取器的一个示例

class Person extends Eloquent
{
    use Sluggable;

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

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

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

maxLength

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

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

maxLengthKeepWords

如果您正在使用 maxLength 设置截断缩略名，那么您可能想确保缩略名不会在单词中间被截断。例如，如果您的源字符串是 "My First Post"，并且您的 maxLength 是 10，生成的缩略名将变为 "my-first-p"，这并不理想。

默认情况下，maxLengthKeepWords 的值设置为 true，这将从缩略名末尾删除部分单词，结果为 "my-first" 而不是 "my-first-p"。

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

method

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

  1. 当 method 为 null（默认设置）时，包使用默认的缩略引擎 -- cocur/slugify -- 来创建缩略名。

  2. 当 method 是可调用的，则使用该函数或类方法。该函数/方法应期望两个参数：要处理的字符串和分隔符字符串。例如，要使用 Laravel 的 Str::slug，可以这样做：

'method' => ['Illuminate\\Support\\Str', 'slug'],
  1. 您还可以将 method 定义为闭包（同样，期望两个参数）。
'method' => function ($string, $separator) {
    return strtolower(preg_replace('/[^a-z]+/i', $separator, $string));
},

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

有关更复杂的缩略需求，请参阅下面的 扩展 Sluggable。

onUpdate

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

如果您想重新生成一个或多个模型的自定义缩略字段，可以在更新之前将这些字段设置为 null 或空字符串。

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

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

separator

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

unique

这是一个布尔值，定义了缩略名是否应在给定类型的所有模型之间唯一。例如，如果您有两篇博客文章，并且它们都称为 "My Blog Post"，则如果 unique 为 false，则它们都将缩略为 "my-blog-post"。这可能是一个问题，例如，如果您在 URL 中使用缩略名。

将 unique 设置为 true，则第二篇 Post 模型将缩略为 "my-blog-post-1"。如果有第三个与相同标题的文章，它将缩略为 "my-blog-post-2"，依此类推。每个后续模型都将将增量值追加到缩略名的末尾，以确保唯一性。

uniqueSuffix

如果您想使用不同的唯一性识别方式（而不是自动递增的整数），可以将 uniqueSuffix 配置设置为函数或可调用，该函数或可调用为您生成 "唯一" 值。

该函数应接受三个参数：基本短链接（即非唯一的短链接）、分隔符字符串，以及一个包含所有以相同短链接开始的其它短链接的 \Illuminate\Support\Collection。然后您可以进行任何操作来创建一个新后缀，该后缀未被集合中的任何短链接使用。例如，如果您想使用字母而不是数字作为后缀，这是实现这一目标的一种方法

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

    return chr($size + 96);
}

includeTrashed

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

reserved

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

简短配置

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

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

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

扩展 Sluggable

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

在这种情况下，该包提供了对短链接工作流程的钩子，您可以使用自己的函数，无论是按模型还是按自定义的扩展包的特质进行。

customizeSlugEngine

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

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

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

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

scopeWithUniqueSlugConstraints

/**
 * @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, $attribute, $config, $slug)
{
    ...
}

如果此作用域存在于您的模型中，则它还会应用于用于确定给定短链接是否唯一的查询。传递给作用域的参数是

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

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

scopeFindSimilarSlugs

/**
 * 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, $attribute, $config, $slug)
{
    ...
}

这是用于查找模型“类似”短链接的默认作用域。基本上，该包会寻找与 $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。

错误、建议、贡献和支持

感谢所有为这个项目做出贡献的人！特别感谢 JetBrains 的开源许可计划...以及当然，优秀的PHPStorm IDE!

JetBrains

请使用 Github 报告错误，发表评论或建议。

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

版权和许可

原始源代码 eloquent-sluggable 由 Colin Viebrock 编写，并发布在 MIT 许可证 下。

由 Jamal Hassouni 添加对阿拉伯语的支持。

版权所有 (c) 2019 Jamal Hassouni