Filament Astrotomic Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require cactus-galaxy/filament-astrotomic
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="CactusGalaxy\FilamentAstrotomic\FilamentAstrotomicServiceProvider"
   

2. Prerequisites Ensure you have:

   • Filament (≥v3.x)
   • Astrotomic/laravel-translatable (≥v10.x) Configured Translatable trait on your Eloquent models.

3. First Use Case Add the HasTranslations trait to a Filament resource:

   use CactusGalaxy\FilamentAstrotomic\Concerns\HasTranslations;
   
   class PostResource extends Resource
   {
       use HasTranslations;
   
       // ...
   }
   

   This auto-generates translation fields for all translatable attributes.

Implementation Patterns

Core Workflows

1. Basic Translation Fields The package auto-detects translatable attributes and renders them as Filament TextInput/RichEditor fields per locale.

   // No manual field definition needed; handled by `HasTranslations`.
   public static function form(Form $form): Form
   {
       return $form
           ->schema([
               // Translations are auto-injected here.
           ]);
   }
   

2. Customizing Translation Fields Override the default field types per attribute:

   public static function form(Form $form): Form
   {
       return $form
           ->schema([
               TextInput::make('title')
                   ->translatable(), // Explicitly mark as translatable
               RichEditor::make('content')
                   ->translatable()
                   ->columnSpanFull(),
           ]);
   }
   

3. Locale Management

   • Default Locale: Set in config/filament-astrotomic.php (default_locale).
   • Available Locales: Define in config/app.php (locales) or override via:

     public static function getLocales(): array
     {
         return ['en', 'es', 'fr'];
     }
     

4. Bulk Locale Updates Use the updateTranslations method in resource actions:

   public static function getActions(PostResource $resource): array
   {
       return [
           Action::make('update-translations')
               ->action(function (Post $record) {
                   $record->updateTranslations([
                       'en' => ['title' => 'New English Title'],
                       'es' => ['title' => 'Nuevo Título'],
                   ]);
               }),
       ];
   }
   

5. Integration with Filament Tables Display translations in table columns:

   Table::make([
       TextColumn::make('title')
           ->translatable(), // Shows translations for the current locale
       TextColumn::make('title.es') // Force a specific locale
           ->label('Spanish Title'),
   ]);
   

6. Fallback Locales Configure fallback locales in config/filament-astrotomic.php:

   'fallback_locales' => [
       'en' => ['es', 'fr'], // Fallback for English
   ],
   

Gotchas and Tips

Pitfalls

1. Locale Mismatch Errors

   • Issue: Undefined locale errors if config/app.php locales don’t match filament-astrotomic.php.
   • Fix: Ensure locales in app.php include all locales used in translations.

2. Missing Translatable Attributes

   • Issue: Fields not appearing if the model’s translatable array isn’t properly defined.
   • Fix: Verify the model uses Translatable trait and has:

     protected $translatable = ['title', 'content'];
     

3. Caching Conflicts

   • Issue: Translations not updating immediately due to Filament’s resource caching.
   • Fix: Clear Filament cache:

     php artisan filament:cache-reset
     

4. Nested Resource Conflicts

   • Issue: HasTranslations may conflict with nested resources.
   • Fix: Explicitly define fields for nested resources or use ->ignoreTranslations() on specific fields.

Debugging Tips

1. Log Translatable Attributes Add this to your model to debug:

   protected static function booted()
   {
       \Log::info('Translatable attributes:', self::$translatable);
   }
   

2. Check Database Structure Verify the translations table exists and has the correct columns:

   SELECT * FROM information_schema.columns
   WHERE table_name = 'translations';
   

3. Override Default Behavior Disable auto-translation for specific fields:

   public static function form(Form $form): Form
   {
       return $form->schema([
           TextInput::make('non_translatable_field')
               ->ignoreTranslations(),
       ]);
   }
   

Extension Points

1. Custom Field Types Extend the package to support custom translatable fields (e.g., Select, Checkbox):

   use CactusGalaxy\FilamentAstrotomic\Concerns\HasTranslations;
   
   class CustomSelect extends Select
   {
       use HasTranslations;
   }
   

2. Locale-Specific Validation Add locale-aware validation rules:

   public static function getValidationRules(): array
   {
       return [
           'title.en' => 'required|max:255',
           'title.es' => 'required|max:255',
       ];
   }
   

3. Translation History Integrate with Laravel Model Observers to log translation changes:

   class PostObserver
   {
       public function saved(Post $post)
       {
           if ($post->wasChanged('translations')) {
               \Log::info('Translations updated:', $post->getDirty());
           }
       }
   }
   

4. API Resource Support Extend the package to support Filament API Resources for translation endpoints:

   class PostApiResource extends ApiResource
   {
       public static function getTranslations(Post $record): array
       {
           return $record->getTranslations();
       }
   }