laravel sluggable

保存 Eloquent 模型时生成 slugs

该包提供了一个特征，可以在保存任何 Eloquent 模型时生成唯一的 slug。

 $model = new EloquentModel();$model->name = 'activerecord 太棒了';$model->save();echo $model->slug; // 输出“activerecord-is-awesome”

slugs 是使用 Laravels Str::slug方法生成的，其中空格被转换为“-”。

Spatie 是一家位于比利时安特卫普的网页设计机构。您可以在我们的网站上找到所有开源项目的概述。

支持我们

我们投入了大量资源来创建一流的开源包。您可以通过购买我们的一款付费产品来支持我们。

我们非常感谢您从家乡寄给我们一张明信片，并注明您正在使用我们的哪种套餐。您可以在我们的联系页面上找到我们的地址。我们在虚拟明信片墙上发布所有收到的明信片。

安装

您可以通过 Composer 安装该软件包：

作曲家需要 spatie/laravel-sluggable

用法

您的 Eloquent 模型应使用SpatieSluggableHasSlug特征和SpatieSluggableSlugOptions类。

该特征包含一个抽象方法getSlugOptions() ，您必须自己实现。

您的模型的迁移应该有一个字段来保存生成的 slug。

这是如何实现该特征的示例：

命名空间应用程序;使用 SpatieSluggableHasSlug;使用 SpatieSluggableSlugOptions;使用 IlluminateDatabaseEloquentModel;类 YourEloquentModel 扩展模型
{use HasSlug;/** * 获取生成 slug 的选项。     */公共函数 getSlugOptions() : SlugOptions{return SlugOptions::create()
            ->generateSlugsFrom('名称')
            ->saveSlugsTo('slug');
    }
}

随着它的迁移：

使用 IlluminateDatabaseMigrationsMigration;使用 IlluminateDatabaseSchemaBlueprint;使用 IlluminateSupportFacadesSchema;类 CreateYourEloquentModelTable 扩展 Migration
{公共函数up()
    {
        Schema::create('your_eloquent_models', function (Blueprint $table) {$table->increments('id');$table->string('slug'); // 字段名称与您的 `saveSlugsTo`$table 相同->string('name');$table->timestamps();
        });
    }
}

在路线中使用 slugs

要在路由中使用生成的 slug，请记住使用 Laravel 的隐式路由模型绑定：

命名空间应用程序;使用 SpatieSluggableHasSlug;使用 SpatieSluggableSlugOptions;使用 IlluminateDatabaseEloquentModel;类 YourEloquentModel 扩展模型
{use HasSlug;/** * 获取生成 slug 的选项。     */公共函数 getSlugOptions() : SlugOptions{return SlugOptions::create()
            ->generateSlugsFrom('名称')
            ->saveSlugsTo('slug');
    }/** * 获取模型的路由键。     * * @return string */public function getRouteKeyName()
    {返回“蛞蝓”;
    }
}

使用多个字段来创建 slug

想要使用多个字段作为 slug 的基础吗？没问题！

公共函数 getSlugOptions() : SlugOptions{return SlugOptions::create()
        ->generateSlugsFrom(['名字', '姓氏'])
        ->saveSlugsTo('slug');
}

自定义 slug 生成

您还可以将callable传递给generateSlugsFrom 。

默认情况下，包将通过将“-”和数字附加到已存在的 slug 来生成唯一的 slug。

您可以通过调用allowDuplicateSlugs来禁用此行为。

公共函数 getSlugOptions() : SlugOptions{return SlugOptions::create()
        ->generateSlugsFrom('名称')
        ->saveSlugsTo('slug')
        ->allowDuplicateSlugs();
}

限制 slue 的长度

您还可以对创建的 slug 设置最大大小限制：

公共函数 getSlugOptions() : SlugOptions{return SlugOptions::create()
        ->generateSlugsFrom('名称')
        ->saveSlugsTo('slug')
        ->slugsShouldBeNoLongerThan(50);
}

由于添加了后缀以使其唯一，因此该段可能会比指定的值稍长。

您还可以通过调用usingSeparator来使用自定义分隔符

公共函数 getSlugOptions() : SlugOptions{return SlugOptions::create()
        ->generateSlugsFrom('名称')
        ->saveSlugsTo('slug')
        ->usingSeparator('_');
}

设置 slug 语言

要设置Str::slug使用的语言，您可以调用usingLanguage

公共函数 getSlugOptions() : SlugOptions{return SlugOptions::create()
        ->generateSlugsFrom('名称')
        ->saveSlugsTo('slug')
        ->usingLanguage('nl');
}

压倒性的蛞蝓

您还可以通过将生成的 slug 设置为生成的 slug 之外的另一个值来覆盖生成的 slug。

 $model = EloquentModel::create(['name' => '我的名字']); //slug 现在是“my-name”;$model->slug = 'my-custom-url';$model->save(); //slug 现在是“my-custom-url”；

防止在某些情况下生成段塞

如果您不想在模型有状态时创建 slug，可以使用skipGenerateWhen函数。

公共函数 getSlugOptions() : SlugOptions{return SlugOptions::create()
        ->generateSlugsFrom('名称')
        ->saveSlugsTo('slug')
        ->skipGenerateWhen(fn () => $this->state === '草稿');
}

防止创建时生成段头

如果您不想在模型最初创建时创建 slug，您可以使用doNotGenerateSlugsOnCreate()函数进行设置。

公共函数 getSlugOptions() : SlugOptions{return SlugOptions::create()
        ->generateSlugsFrom('名称')
        ->saveSlugsTo('slug')
        ->doNotGenerateSlugsOnCreate();
}

防止 slug 更新

同样，如果您想防止模型更新时更新 slug，请调用doNotGenerateSlugsOnUpdate() 。

公共函数 getSlugOptions() : SlugOptions{return SlugOptions::create()
        ->generateSlugsFrom('名称')
        ->saveSlugsTo('slug')
        ->doNotGenerateSlugsOnUpdate();
}

这对于创建在您明确希望之前不会更改的永久链接很有帮助。

 $model = EloquentModel::create(['name' => '我的名字']); //slug 现在是“my-name”;$model->save();$model->name = 'changed name';$model->save(); //slug 保持“我的名字”

再生蛞蝓

如果您想显式更新模型上的 slug，您可以随时在模型上调用generateSlug() ，以根据您的其他选项生成 slug。不要忘记save()模型以将更新保存到数据库中。

防止覆盖

您可以防止数据块被覆盖。

公共函数 getSlugOptions() : SlugOptions{return SlugOptions::create()
        ->generateSlugsFrom('名称')
        ->saveSlugsTo('slug')
        ->preventOverwrite();
}

使用范围

如果您有一个需要考虑的全局范围，您也可以使用extraScope来定义它。例如，如果您有一个包含多个网站页面的页面表，并且每个网站都有自己独特的 slugs。

公共函数 getSlugOptions() : SlugOptions{return SlugOptions::create()
        ->generateSlugsFrom('名称')
        ->saveSlugsTo('slug')
        ->extraScope(fn ($builder) => $builder->where('scope_id', $this->scope_id));
}

设置 slug 后缀起始索引

默认情况下，后缀索引从1开始，您可以设置起始编号。

公共函数 getSlugOptions() : SlugOptions{return SlugOptions::create()
        ->generateSlugsFrom('名称')
        ->saveSlugsTo('slug')
        ->startSlugSuffixFrom(2);
}

与 laravel-translatable 集成

您可以将此包与 laravel-translatable 一起使用来为每个语言环境生成一个 slug。您必须使用HasSlug特征，而不是使用HasTranslatableSlug特征，并将 slug 字段的名称添加到$translatable数组中。对于从单个字段或多个字段生成的数据块，您无需更改任何其他内容。

命名空间应用程序;使用 SpatieSluggableHasTranslatableSlug;使用 SpatieSluggableSlugOptions;使用 SpatieTranslatableHasTranslations;使用 IlluminateDatabaseEloquentModel;类 YourEloquentModel 扩展模型
{use HasTranslations, HasTranslatableSlug;public $translatable = ['name', 'slug'];/** * 获取生成 slug 的选项。     */公共函数 getSlugOptions() : SlugOptions{return SlugOptions::create()
            ->generateSlugsFrom('名称')
            ->saveSlugsTo('slug');
    }
}

对于从可调用生成的 slug，您需要使用createWithLocales方法实例化SlugOptions 。可调用对象现在采用两个参数，而不是一个。 $model和$locale都可以用来生成 slug。

命名空间应用程序;使用 SpatieSluggableHasTranslatableSlug;使用 SpatieSluggableSlugOptions;使用 SpatieTranslatableHasTranslations;使用 IlluminateDatabaseEloquentModel;类 YourEloquentModel 扩展模型
{use HasTranslations, HasTranslatableSlug;public $translatable = ['name', 'slug'];/** * 获取生成 slug 的选项。     */公共函数 getSlugOptions() : SlugOptions{return SlugOptions::createWithLocales(['en', 'nl'])
            ->generateSlugsFrom(function($model, $locale) {return "{$locale} {$model->id}";
            })
            ->saveSlugsTo('slug');
    }
}

隐式路由模型绑定

您还可以在控制器内使用 Laravel 隐式路由模型绑定来自动解析模型。要使用此功能，请确保 slug 列与routeNameKey匹配。
目前，只有部分数据库类型支持JSON操作。有关哪些数据库支持 JSON 的更多信息可以在 Laravel 文档中找到。

命名空间应用程序;使用 SpatieSluggableHasSlug;使用 SpatieSluggableSlugOptions;使用 IlluminateDatabaseEloquentModel;类 YourEloquentModel 扩展模型
{use HasTranslations, HasTranslatableSlug;public $translatable = ['name', 'slug'];/** * 获取生成 slug 的选项。     */公共函数 getSlugOptions() : SlugOptions{return SlugOptions::create()
            ->generateSlugsFrom('名称')
            ->saveSlugsTo('slug');
    }/** * 获取模型的路由键。     * * @return string */public function getRouteKeyName()
    {返回“蛞蝓”;
    }
}

按 slug 查找型号

为了方便起见，您可以使用别名findBySlug来检索模型。定义SlugOptions时，查询将与传递给saveSlugsTo的字段进行比较。

 $model = Article::findBySlug('my-article');

findBySlug还接受第二个参数$columns就像默认的 Eloquent find方法一样。

变更日志

请参阅变更日志以了解最近更改的更多信息。

测试

作曲家测试

贡献

详细信息请参阅贡献。

安全

如果您发现有关安全的错误，请发送邮件至 [email protected]，而不是使用问题跟踪器。

制作人员

• 弗里克·范德赫滕

• 所有贡献者

执照

麻省理工学院许可证 (MIT)。请参阅许可证文件以获取更多信息。