Stabilizing Filament Integration in Platform Projects

Introduction

When integrating libraries like Filament into larger platform projects, version incompatibilities can cause widespread issues. A recent update to the Reimpact/platform project highlighted how crucial it is to maintain API compatibility to prevent application crashes.

The Problem: API Version Mismatch

The Ecodesign module within the platform project was developed against a different version of the Filament API than the one installed in the main application. This resulted in fatal errors that disrupted key development processes like running Artisan commands and static analysis with PHPStan. The impact was significant, causing crashes across the board.

The Solution: API Compatibility Fixes

To resolve the incompatibility issues, several adjustments were made across the Ecodesign module. Here's a breakdown of the key changes:

1. Form Schema Updates: The Filament\Schemas\Schema class was replaced with Filament\Forms\Form in the form() methods of Filament resources. This reflects a change in the Filament API for defining form structures.

use Filament\Forms\Form;

public function form(Form $form): Form
{
    return $form
        ->schema([
            // Form fields here
        ]);
}

2. Navigation Icon Type: The $navigationIcon property was updated to accept a nullable string (?string) instead of a union type that included BackedEnum. This ensures compatibility with Filament's expected type for navigation icons.

protected ?string $navigationIcon = 'heroicon-o-rectangle-stack';

3. Static Properties: The $heading and $view properties were made static to align with the parent class declarations, preventing inheritance-related errors.

protected static string $heading = 'Page Heading';
protected static string $view = 'filament.pages.custom-page';

4. PHPStan Exclusions: The Ecodesign/Filament directory was excluded from PHPStan analysis to temporarily bypass remaining class.notFound errors related to Filament action classes that were not available in the installed Filament version. This allows PHPStan to run without crashing while further investigation is conducted.

Results

By addressing these API incompatibilities, the platform project was stabilized, allowing developers to resume their work without encountering fatal errors during common development tasks. The changes ensured that the Ecodesign module integrates seamlessly with the existing Filament installation.

Next Steps

When integrating external libraries, especially UI frameworks like Filament, it's crucial to carefully manage dependencies and test for API compatibility. Consider using dependency management tools to lock library versions and implementing automated tests to catch potential issues early. Also, regularly review library update changelogs and deprecation notices to stay ahead of breaking changes.