Category Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation:

   composer require moox/category
   php artisan mooxcategory:install
   

   This sets up the package with default configurations (e.g., categories table, Category resource).

2. First Use Case:

   • Access the Filament Resource for Category via /admin/categories (default route).
   • Run migrations to create the database table:

     php artisan migrate
     

3. Where to Look First:

   • Config File: config/moox-category.php (adjust table/namespace if needed).
   • Filament Resource: app/Filament/Resources/CategoryResource.php (customize fields, policies, etc.).
   • Migrations: database/migrations/[timestamp]_create_categories_table.php (modify schema as needed).

Implementation Patterns

Core Workflows

1. Customizing the Resource:

   • Extend CategoryResource to add/remove fields, policies, or widgets:

     // app/Filament/Resources/CategoryResource.php
     public static function form(Form $form): Form
     {
         return $form
             ->schema([
                 TextInput::make('name')->required(),
                 // Add custom fields here
             ]);
     }
     

2. Integration with Eloquent:

   • Use the Category model (app/Models/Category.php) in controllers/services:

     use App\Models\Category;
     
     $categories = Category::with('posts')->get(); // Example relation
     

3. API Endpoints:

   • Leverage Filament’s built-in API routes (e.g., GET /api/admin/categories).
   • Override routes in routes/web.php or routes/api.php if needed.

4. Seeding Data:

   • Use Laravel’s seeder to populate initial categories:

     // database/seeders/CategorySeeder.php
     Category::create(['name' => 'Electronics']);
     

5. Package Customization:

   • Rename the entity/table during package generation (via build.php):

     php build.php
     

     (Select options like Post for entity and posts for table name.)

Integration Tips

• Relationships:

  • Define polymorphic/many-to-many relations in the Category model:

    public function posts(): HasMany
    {
        return $this->hasMany(Post::class);
    }
    

  • Use Filament’s RelationManager to display nested resources.

• Validation:

  • Add custom validation rules in the CategoryResource:

    use Illuminate\Validation\Rules\Unique;
    
    TextInput::make('slug')
        ->required()
        ->unique(Category::class, 'slug'),
    

• Localization:

  • Override Filament labels in resources/lang/en/category.php:

    return [
        'resources' => [
            'category' => [
                'singular' => 'Category',
                'plural' => 'Categories',
            ],
        ],
    ];
    

• Events:

  • Listen to model events (e.g., created) in app/Providers/EventServiceProvider.php:

    Category::created(function ($category) {
        // Send notification or log activity
    });
    

Gotchas and Tips

Pitfalls

1. Namespace Conflicts:

   • If using the template to create a new package, ensure the composer namespace in composer.json matches your GitHub repo (e.g., vendor/package-name).
   • Update config/moox-category.php to reflect the correct namespace for models/resources.

2. Migration Issues:

   • After renaming the table/entity via build.php, run:

     php artisan migrate:fresh
     

     to avoid conflicts with default categories table.

3. Filament Permissions:

   • Ensure the CategoryResource is registered in app/Providers/Filament/AdminPanelProvider.php:

     $panel->resources([
         CategoryResource::class,
     ]);
     

4. Caching:

   • Clear Filament’s view cache after customizing resources:

     php artisan filament:cache:clear
     

5. Package Updates:

   • If updating the base moox/category package, manually merge changes from the template repo to avoid overwriting customizations.

Debugging Tips

1. Filament Debugging:

   • Enable Filament’s debug mode in .env:

     FILAMENT_DEBUG=true
     

   • Check logs at storage/logs/filament.log.

2. Database Queries:

   • Use Laravel Debugbar (barryvdh/laravel-debugbar) to inspect SQL queries:

     composer require barryvdh/laravel-debugbar
     

3. Route Conflicts:

   • Dump routes to identify overlaps:

     php artisan route:list
     

4. Model Binding:

   • Verify resource routes bind correctly to the model:

     // app/Filament/Resources/CategoryResource.php
     public static function getModel(): string
     {
         return Category::class;
     }
     

Extension Points

1. Custom Policies:

   • Add policies to app/Policies/CategoryPolicy.php:

     public function delete(User $user, Category $category)
     {
         return $user->isAdmin();
     }
     

   • Attach to the resource:

     protected static ?string $policy = CategoryPolicy::class;
     

2. Widgets:

   • Create Filament widgets for dashboards (e.g., CategoryStatsWidget):

     use Filament\Widgets\StatsOverviewWidget;
     
     StatsOverviewWidget::make()
         ->columns(2)
         ->addCount('Total Categories', Category::query()),
     

3. API Resources:

   • Extend the default API response by overriding toArray() in the model or creating a custom API resource.

4. Commands:

   • Add custom Artisan commands in app/Console/Commands to interact with categories (e.g., bulk import):

     php artisan make:command ImportCategories
     

5. Testing:

   • Use Filament’s testing helpers in phpunit.xml:

     <env name="FILAMENT_TESTING" value="true"/>
     

   • Test resources with:

     $this->actingAs($user)
          ->get('/admin/categories')
          ->assertOk();