laravel-tags maintained by blamodex
Blamodex Laravel Tags
A simple, Laravel-ready tagging package for rapid prototyping and lightweight use cases. Add flexible tagging functionality to any Eloquent model using polymorphic relationships.
Table of Contents
🚀 Features
- Attach tagging functionality to any model using traits
- Polymorphic support for multiple taggable and tagger models
- Tag groups for categorization and organization
- Automatic slug generation for tags and tag groups
- Soft deletes on all entities
- Clean service layer pattern
- UUID support for distributed systems
📦 Installation
Install the package with Composer:
composer require blamodex/laravel-tags
Run the migrations:
php artisan migrate
🧩 Usage
1. Making Models Taggable
Add the Taggable trait and implement the TaggableInterface to models that can be tagged:
use Blamodex\Tags\Traits\Taggable;
use Blamodex\Tags\Contracts\TaggableInterface;
class Post extends Model implements TaggableInterface
{
use Taggable;
}
2. Making Models Taggers
Add the Tagger trait and implement the TaggerInterface to models that can create and own tags:
use Blamodex\Tags\Traits\Tagger;
use Blamodex\Tags\Contracts\TaggerInterface;
class User extends Model implements TaggerInterface
{
use Tagger;
}
3. Working with Tags
Create a tag
$user = User::find(1);
$tag = $user->createTag('Laravel');
Find a tag
$tag = $user->findTag('Laravel');
Find or create a tag
$tag = $user->findOrCreateTag('Laravel');
Check if user has a tag
if ($user->hasTag('Laravel')) {
// Tag exists
}
Get all tags owned by a user
$tags = $user->ownedTags();
Delete a tag
$user->deleteTag('Laravel');
4. Working with Tag Groups
Tag groups allow you to organize tags into categories.
Create a tag group
$user = User::find(1);
$group = $user->createTagGroup('Programming Languages');
Find a tag group
$group = $user->findTagGroupByName('Programming Languages');
// or by slug
$group = $user->findTagGroupBySlug('programming-languages');
Assign a tag to a group
$tag = $user->findTag('Laravel');
$group = $user->findTagGroupByName('Frameworks');
$user->assignTagToGroup($tag, $group);
Get all tags in a group
$tags = $user->getTagsByGroup($group);
Delete a tag group
$user->deleteTagGroup('Programming Languages');
5. Attaching Tags to Models
Once you have taggable models and tags, you can attach them:
Attach a tag to a model
$post = Post::find(1);
$tag = Tag::findByName('Laravel');
$post->attachTag($tag);
Check if a model has a tag
if ($post->hasTag($tag)) {
// Post is tagged
}
Get all tags on a model
$tags = $post->tags();
Detach a tag from a model
$post->detachTag($tag);
Detach all tags from a model
$post->detachAllTags();
Sync tags (detach all existing and attach new ones)
$tags = [
Tag::findByName('Laravel'),
Tag::findByName('PHP'),
];
$post->syncTags($tags);
🧪 Testing
This package uses Orchestra Testbench and PHPUnit.
Run tests:
composer test
Check code style:
composer lint
Check code style and fix:
composer lint:fix
Run static analysis:
composer analyze
Check coverage (with Xdebug):
composer test:coverage
📁 Project Structure
src/
├── Models/
│ ├── Tag.php
│ ├── TagGroup.php
│ └── TaggablePivot.php
├── Services/
│ ├── TaggerService.php
│ └── TaggableService.php
├── Traits/
│ ├── Taggable.php
│ ├── Tagger.php
│ └── Sluggable.php
├── Contracts/
│ ├── TaggableInterface.php
│ ├── TaggerInterface.php
│ └── SluggableInterface.php
├── Events/
│ ├── TagCreated.php
│ ├── TagUpdated.php
│ ├── TagDeleted.php
│ ├── TaggablePivotCreated.php
│ └── TaggablePivotDeleted.php
├── Validators/
│ └── TagValidator.php
└── database/
└── migrations/
├── create_tag_groups_table.php
├── create_tags_table.php
└── create_taggable_pivots_table.php
tests/
├── Unit/
├── Fixtures/
└── TestCase.php
🤝 Contributing
We welcome contributions! Please see CONTRIBUTING.md for details.
📝 Changelog
Please see CHANGELOG.md for recent changes.
📄 License
MIT © Blamodex
For more information, see the LICENSE file.