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)。請參閱許可證文件以獲取更多資訊。