README

A simple, Laravel-ready tagging package for rapid prototyping and lightweight use cases. Add flexible tagging functionality to any Eloquent model using polymorphic relationships.

Features
Installation
Usage
Testing
Project Structure
Contributing
License

🚀 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.

blamodex / laravel-tags

Maintainers

Details