DOCSEARCHbyAlgolia
Submit Docs

spatie/laravel-tags

repository·main·Indexed 23 days ago

https://github.com/spatie/laravel-tags

A Laravel package providing robust tagging capabilities for Eloquent models. It supports multiple tag types, translations via spatie/laravel-translatable, and sorting via spatie/eloquent-sortable. Key features include methods for attaching, detaching, and syncing tags, as well as Eloquent scopes like withAnyTags and withAllTags to filter models by their associated tags.

Tokens
7.1K
Snippets
26
Records
47
Agent score
33%

What's inside spatie/laravel-tags

  1. Use tag types and sorting

    main

    Tag Types

    You can categorize tags by assigning them a type. This is useful for separating 'categories' from 'topics'.

    • Create a tagged instance: Tag::findOrCreate('name', 'type').
    • Retrieve by type: $model->tagsWithType('type').

    Sorting Tags

    Tags are sortable via an order_column. You can manipulate the order of tags using the swapOrder method.

    • Get order: $tag->order_column.
    • Change order: $tag->swapOrder($anotherTag).

  3. Install laravel-tags

    main

    Install the package via Composer, publish the migrations, and run them to create the necessary tags and taggables tables.

    Requirements:

    • Laravel 8 or higher
    • PHP 8 or higher
    • A database supporting json fields and MySQL compatible functions.
    composer require spatie/laravel-tags

php artisan vendor:publish --provider="Spatie\Tags\TagsServiceProvider" --tag="tags-migrations"

php artisan migrate

  4. Set up database migrations for tags

    main

    To use the package, you must publish its migrations and run them to create the tags and taggables tables.

    1. Publish the migrations:
    php artisan vendor:publish --provider="Spatie\Tags\TagsServiceProvider" --tag="tags-migrations"
    1. Run the migrations:
    php artisan migrate
    php artisan vendor:publish --provider="Spatie\Tags\TagsServiceProvider" --tag="tags-migrations"
php artisan migrate

  6. Translate tags using setTranslation() and getTranslation()

    main

    By default, tags are stored in the current application locale. To support multilingual applications, you can use the setTranslation method to add translations for specific languages and getTranslation to retrieve them. Note that you must call save() on the tag model after setting translations to persist the changes.

    Translations are stored in the name column of the tags table as a json object. The package uses spatie/laravel-translatable under the hood, so you can utilize any methods provided by that package.

  11. Set a custom default locale for tags

    main

    In multi-language applications where the application's locale differs from the language used for tags, you can force tags to use a specific default locale.

    To do this, you must:

    1. Create a custom Tag model that extends Spatie\Tags\Tag.
    2. Override the getLocale() method in your custom model to return your desired locale code (e.g., 'nl' for Dutch).
    3. Update the tag_model configuration key in config/tags.php to point to your new custom class.
    namespace App\Models;

use Spatie\Tags\Tag as SpatieTag;

class YourTag extends SpatieTag
{
    public static function getLocale(): string
    {
        return 'nl';
    }
}
    // config/tags.php
return [
    // ...
    'tag_model' => App\Models\YourTag::class,
];

  12. Use a custom tag model

    main

    If you need to add extra functionality to tags or override existing behavior, you can use a custom Eloquent model instead of the default Spatie\Tags\Tag.

    To implement a custom tag model, follow these two steps in your model that uses the HasTags trait:

    1. Override getTagClassName(): Return the fully qualified class name of your custom tag model. Your custom model must extend Spatie\Tags\Tag and use the same tags table.
    2. Override tags(): You must manually define the tags() relationship to ensure the package continues to use the tag_id column for the relationship instead of attempting to use a column named after your custom model (e.g., your_tag_model_id).
    use Illuminate\Database\Eloquent\Model;
use Spatie\Tags\HasTags;

class YourModel extends Model
{
    use HasTags;
    
    public static function getTagClassName(): string
    {
        return YourTagModel::class;
    }
}

// ... inside YourModel

public function tags(): MorphToMany
{
    return $this
        ->morphToMany(self::getTagClassName(), 'taggable', 'taggables', null, 'tag_id')
        ->orderBy('order_column');
}