Filament Astrotomic Laravel Package

Technical Evaluation

Architecture Fit

• Filament + Laravel Translatable Synergy: The package bridges Filament (admin panel) and Astrotomic’s Laravel Translatable, enabling multi-language model management via a UI. This aligns well with projects requiring localized content (e.g., e-commerce, multilingual CMS, or global SaaS).
• Plugin-Based Design: Leverages Filament’s plugin system, minimizing core framework modifications. Ideal for modular Laravel apps where admin panels are decoupled from business logic.
• ORM Agnostic: Works with Eloquent, making it compatible with most Laravel database setups (MySQL, PostgreSQL, SQLite).

Integration Feasibility

• Low Coupling: Only requires filament/filament and astrotomic/laravel-translatable as dependencies. No forced migrations or schema changes.
• UI-Centric: Adds translation fields to Filament forms/tables without altering existing model logic. Reduces backend complexity for frontend teams.
• Configuration-Driven: Customizable via Filament’s resource configuration (e.g., fields(), tables()), enabling gradual adoption.

Technical Risk

• Dependency Versioning:
  • Filament: Must align with Filament’s supported versions. Risk if using an unsupported Filament major version (e.g., v2 vs. v3).
  • Laravel Translatable: Astrotomic’s package may introduce breaking changes (e.g., v10+ migrations).
• Localization Complexity:
  • Fallback Logic: Translatable’s fallback rules (e.g., fallbackLocales) must be pre-configured to avoid runtime errors.
  • Performance: Heavy translation tables (e.g., json columns) could impact query performance if not optimized (e.g., indexing, caching).
• Testing Gaps:
  • Limited test coverage (no visible CI badges in README). Risk of edge-case bugs (e.g., nested translations, concurrent edits).

Key Questions

1. Filament Version Compatibility:
   • Is the target Filament version (e.g., 3.x) explicitly supported? If not, what’s the upgrade path?
2. Translation Strategy:
   • How are fallback locales defined? Are there plans for dynamic fallbacks (e.g., user-preferred language)?
3. Performance:
   • Will translation fields be loaded eagerly or lazily? Are there plans for caching translated attributes?
4. Customization:
   • Does the package support custom translation keys (e.g., non-standard column names) or only translations JSON?
5. Migration Path:
   • If using Spatie’s translatable, what’s the effort to switch to Astrotomic’s package?
6. Localization Workflow:
   • How will translators (e.g., third-party services) interact with Filament? Are there API endpoints or CLI tools?

Integration Approach

Stack Fit

• Primary Use Case: Laravel apps using Filament for admin panels and needing multi-language support without heavy backend work.
• Alternatives Considered:
  • spatie/laravel-translatable-plugin: More mature but tied to Spatie’s package. This package offers Astrotomic’s features (e.g., custom locales).
  • Manual Implementation: Higher dev effort; this package reduces boilerplate.
• Non-Fit Scenarios:
  • Non-Filament Admin Panels: (e.g., Nova, Backpack). Not applicable.
  • Static Localization: If translations are managed via files (e.g., JSON/YAML), this adds unnecessary DB overhead.

Migration Path

1. Prerequisites:
   • Install astrotomic/laravel-translatable (if not already present).
   • Ensure Filament is installed and configured.
2. Package Installation:

   composer require cactus-galaxy/filament-astrotomic
   

3. Configuration:
   • Publish the package’s config (if any) and update config/filament.php to include the plugin.
   • Example resource integration:

     use CactusGalaxy\FilamentAstrotomic\FilamentAstrotomicPlugin;
     
     FilamentAstrotomicPlugin::make()
         ->locales(['en', 'es', 'fr'])
         ->defaultLocale('en')
         ->registerResources();
     

4. Resource Integration:
   • Add translation fields to Filament resources:

     use CactusGalaxy\FilamentAstrotomic\Fields\TranslatableField;
     
     public static function form(Form $form): Form
     {
         return $form->schema([
             TranslatableField::make('title')
                 ->locales(['en', 'es']),
         ]);
     }
     

5. Testing:
   • Validate translations persist and display correctly in Filament.
   • Test edge cases (e.g., empty translations, unsupported locales).

Compatibility

• Laravel: Tested on Laravel 10/11 (assumed based on Filament/Astrotomic support).
• PHP: Requires PHP 8.1+ (Filament’s minimum).
• Database: Eloquent-compatible. No vendor-specific SQL.
• Filament Plugins: Conflicts unlikely unless another plugin modifies the same translation logic.

Sequencing

1. Phase 1: Install and configure the package in a staging environment.
2. Phase 2: Integrate with a single Filament resource (e.g., Page model).
3. Phase 3: Expand to other resources; monitor performance.
4. Phase 4: Customize (e.g., add validation, change default locales).

Operational Impact

Maintenance

• Dependency Updates:
  • Monitor cactus-galaxy/filament-astrotomic, filament/filament, and astrotomic/laravel-translatable for breaking changes.
  • Upgrade path may require:
    • Database migrations (if Astrotomic’s translatable schema changes).
    • Filament resource field updates (if API signatures change).
• Community Support:
  • Low stars/dependents suggest limited community engagement. Issues may require direct outreach to maintainers.
• Fallback Plan:
  • If the package stagnates, consider forking or migrating to Spatie’s plugin with custom Astrotomic features.

Support

• Debugging:
  • Log translation-related queries to identify performance bottlenecks (e.g., N+1 queries).
  • Use Filament’s debug mode to inspect field rendering issues.
• Common Issues:
  • Missing Translations: Ensure hasTranslations() is called on models.
  • Locale Mismatches: Validate app()->getLocale() vs. TranslatableField locales.
  • Permission Errors: Filament’s policy gates may block translation edits.
• Documentation Gaps:
  • README lacks examples for nested translations or custom storage (e.g., Redis). May need internal docs.

Scaling

• Performance:
  • Database: Large translation tables may slow queries. Mitigate with:
    • Indexes on locale and translatable_id.
    • Caching translated attributes (e.g., remember() in models).
  • Filament: Heavy translation fields in tables/forms could impact UI load time. Use lazy loading or pagination.
• Concurrency:
  • Race conditions possible if multiple users edit translations simultaneously. Consider optimistic locking or queue-based updates.
• Multi-Tenancy:
  • If using tenancy (e.g., Laravel Tenant), ensure locale fallback respects tenant-specific settings.

Failure Modes

Ramp-Up

• Onboarding Time: 2–4 hours for basic integration (assuming familiarity with Filament).
  • Blockers:
    • Unclear Astrotomic/Laravel Translatable setup (e.g., model configuration).
    • Custom translation logic (e.g., non-standard column names).
• Training Needs:
  • Developers: Filament resource customization, Astrotomic’s Translatable trait.
  • Content Editors: Filament UI workflow for translations (e.g., switching locales).
• Documentation:
  • Missing: Examples for:
    • Nested translatable models.
    • Custom storage engines (e.g., Redis).
    • Integration with Filament’s notifications/actions.
  • Workaround: Leverage [GalaxyStore](https://github.com/CactusGalaxy