README

A Laravel package for tagging Eloquent models. Add the HasTags trait to any model and start tagging.

Installation

composer require foodieneers/laravel-tag

Publish and run the migrations:

php artisan vendor:publish --tag="laravel-tag-migrations"
php artisan migrate

Add the HasTags trait to your model (e.g. User):

use Foodieneers\Tag\Traits\HasTags;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    use HasTags;
}

That's it. Your model can now be tagged.

API Reference

HasTags Trait

Add to any Eloquent model that should be taggable.

tags() — BelongsToMany relation

Returns the tags relation. Use for attach, detach, sync, or querying.

$user->tags;                    // Collection of Tag models
$user->tags()->attach($tagId);  // Attach by ID
$user->tags()->detach($tagId);  // Detach by ID
$user->tags()->sync([1, 2, 3]); // Sync tag IDs

tag(string $name): void

Attaches a tag by name. Creates the tag if it doesn't exist.

$user->tag('developer');
$user->tag('admin');

detag(string $name): void

Removes a tag by name. No-op if the tag doesn't exist or isn't attached.

$user->detag('developer');

Tag Model

Tag::name(string $name): Tag

Get or create a tag by name. Creates with description => 'Automatically generated' when new.

$tag = Tag::name('laravel');

Tag::setTaggableModel(string $class): void

Sets which model class is taggable. Called automatically by HasTags::bootHasTags(). Only needed if you use multiple taggable models or customize behavior.

Tag::setTaggableModel(User::class);

$tag->tagged(): BelongsToMany

Returns the relation to models that have this tag.

$tag->tagged;           // Collection of tagged models (e.g. Users)
$tag->tagged()->get();  // Query builder

Pivot includes created_at.

$tag->category(): BelongsTo

Returns the optional tag category.

$tag->category;  // TagCategory or null

TagCategory Model

TagCategory::name(string $name): TagCategory

Get or create a category by name. Creates with description => 'Automatically generated' when new.

$category = TagCategory::name('programming');

$category->tags(): HasMany

Returns tags in this category.

$category->tags;  // Collection of Tag models

Example

// Tag a user
$user->tag('developer');
$user->tag('admin');

// List tags
$user->tags->pluck('name');  // ['developer', 'admin']

// Remove a tag
$user->detag('admin');

// Sync tags (replace all)
$user->tags()->sync([
    Tag::name('moderator')->id,
    Tag::name('reviewer')->id,
]);

// From a tag: get all tagged models
$tag = Tag::name('developer');
$tag->tagged;  // Users (or your taggable model) with this tag

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Azzarip
• All Contributors

License

The MIT License (MIT). Please see LICENSE for more information.