Tag Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation:

   composer require moox/tag
   php artisan mooxtag:install
   

   • The mooxtag:install command publishes the migration, config, and views for the Tag system.

2. First Use Case:

   • Register the TagResource in your app/Providers/Filament/AdminPanelProvider.php:

     public function panel(Panel $panel): Panel
     {
         return $panel
             ->id('admin')
             ->resources([
                 \Moox\Tag\Resources\TagResource::class,
             ]);
     }
     

   • Access the Tag management interface at /admin/tags.

3. Where to Look First:

   • Config: config/moox-tag.php – Customize tag behavior (e.g., allowed characters, max tags per item).
   • Resource: app/Filament/Resources/TagResource.php – Extend or override default logic.
   • Migrations: database/migrations/[timestamp]_create_tags_table.php – Modify the tags table schema if needed.

Implementation Patterns

Core Workflows

1. Tagging Models:

   • Use the Taggable trait to attach tags to Eloquent models:

     use Moox\Tag\Traits\Taggable;
     
     class Post extends Model
     {
         use Taggable;
     }
     

   • Sync tags via:

     $post->tags()->sync(['laravel', 'php', 'filament']);
     

2. Filament Integration:

   • Tag Selection Widget: Automatically included in Filament forms via TagsInput:

     use Moox\Tag\Forms\Components\TagsInput;
     
     TagsInput::make('tags')->required(),
     

   • Tag Management: Use the TagResource to CRUD tags globally.

3. Customizing the Tag System:

   • Dynamic Tagging: Override the TagResource to fetch tags dynamically (e.g., from a different table):

     public static function getModel(): string
     {
         return \App\Models\CustomTag::class;
     }
     

   • Tag Scopes: Add query scopes to filter models by tags:

     public function scopeWithTag($query, $tag)
     {
         return $query->whereHas('tags', fn($q) => $q->where('name', $tag));
     }
     

4. Tagging Relationships:

   • Pivot Tables: For many-to-many relationships, ensure the pivot table includes a tag_id column:

     $post->tags()->attach($tagId, ['created_at' => now()]);
     

   • Soft Deletes: Enable soft deletes for tags in the TagResource:

     public static function getEloquentQuery(): Builder
     {
         return parent::getEloquentQuery()->withTrashed();
     }
     

5. API Endpoints:

   • Expose tag management via API by publishing the TagResource API routes:

     Filament::registerApiResources([
         \Moox\Tag\Resources\Api\TagResource::class,
     ]);
     

Gotchas and Tips

Pitfalls and Debugging

1. Migration Conflicts:

   • If you modify the tags table schema after installation, drop and re-run the migration:

     php artisan migrate:fresh --env=testing
     

   • Avoid manual schema changes to the tags table unless absolutely necessary.

2. Tag Sync Issues:

   • Detached Tags: Use syncWithoutDetaching() to avoid removing existing tags:

     $post->tags()->syncWithoutDetaching(['new-tag']);
     

   • Performance: For large datasets, batch sync operations:

     $post->tags()->sync($tagIds, ['detach' => false]);
     

3. Filament Caching:

   • Clear Filament’s cache if UI changes (e.g., new fields) aren’t reflected:

     php artisan filament:cache:clear
     

4. Translation Quirks:

   • Customize translations in resources/lang/[locale]/moox-tag.php:

     return [
         'tags' => [
             'create' => 'Add New Tag',
         ],
     ];
     

   • Ensure the moox-tag language file exists in your locale directory.

5. Permission Denied:

   • Verify the TagResource is included in your Filament panel’s resources() array.
   • Check Filament’s permission policies for the TagResource.

Extension Points

1. Custom Tag Validation:

   • Extend the Tag model’s validation rules in app/Models/Tag.php:

     protected static function booted()
     {
         static::updating(function ($tag) {
             $tag->name = strtolower($tag->name);
         });
     }
     

2. Tag Events:

   • Listen for tag-related events (e.g., TagCreated, TagDeleted) in EventServiceProvider:

     public function boot()
     {
         Tag::created(fn ($tag) => Log::info("New tag: {$tag->name}"));
     }
     

3. Tag Search:

   • Add a searchable scope to the TagResource:

     public static function getSearchResultTitle(Tag $record): string
     {
         return $record->name;
     }
     

4. Tag Auto-Completion:

   • Use the TagsInput component with searchable: true for real-time tag suggestions:

     TagsInput::make('tags')->searchable()->required(),
     

5. Tag Hierarchies:

   • Extend the Tag model to support parent-child relationships:

     public function parent()
     {
         return $this->belongsTo(Tag::class, 'parent_id');
     }
     

   • Update the tags table migration to include parent_id.