Support Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer (typically installed as a dependency of other Filament packages):

   composer require filament/support
   

   No standalone configuration is required—it’s a utility package designed to be consumed by other Filament packages (e.g., filament/filament, filament/forms).

2. First Use Case

   • Helper Methods: Leverage utility functions like str()->slug(), str()->headline(), or str()->studly() for string manipulation.
   • Foundation Classes: Extend core classes like Filament\Support\Contracts\HasTable or Filament\Support\Enums\Action for custom logic.
   • Testing: Use Filament\Support\Testing\TestCase as a base for package tests.

   Example:

   use Filament\Support\Facades\Filament;
   
   // Generate a slug from a string
   $slug = str()->slug('Hello World');
   
   // Check if Filament is installed
   if (Filament::isInstalled()) {
       // Proceed with Filament-specific logic
   }
   

3. Where to Look First

   • API Docs: Browse the Filament Support package docs for helper methods and contracts.
   • Source Code: Explore src/ for core utilities (e.g., src/Concerns/HasTable.php, src/Enums/).
   • Filament Packages: Study how other Filament packages (e.g., filament/forms) use this package for patterns.

Implementation Patterns

1. String and Data Utilities

• String Manipulation: Use str() helpers for consistent formatting (slugs, headlines, etc.).

  $title = str()->headline('user_profile'); // "User Profile"
  

• Array/Collection Helpers: Leverage arr() or collect() for nested data transformations.

  $data = arr()->set($request->all(), 'user.name', 'John Doe');
  

2. Contracts and Interfaces

• Extend Core Contracts: Implement HasTable, HasPages, or HasWidgets for custom resources/pages.

  use Filament\Support\Contracts\HasTable;
  
  class CustomResource extends Resource implements HasTable {
      // ...
  }
  

• Action/Notification Enums: Use Action or Notification enums for type-safe operations.

  use Filament\Support\Enums\Action;
  
  if ($action === Action::Create) {
      // Handle create logic
  }
  

3. Testing Utilities

• Base Test Case: Extend Filament\Support\Testing\TestCase for Filament-specific assertions.

  use Filament\Support\Testing\TestCase;
  
  class MyTest extends TestCase {
      public function test_something() {
          $this->assertFilamentRouteExists('/admin');
      }
  }
  

• Mocking: Use Filament::fake() to simulate Filament services in tests.

4. Integration with Filament Packages

• Forms/Tables: Use filament/forms or filament/tables alongside this package for shared utilities.

  use Filament\Support\Facades\Filament;
  
  Filament::registerResource(CustomResource::class);
  

• Widgets: Extend HasWidgets for custom dashboard widgets.

5. Configuration and Facades

• Facades: Access Filament services via Filament, Notifiable, or Action.

  use Filament\Support\Facades\Filament;
  
  $user = Filament::auth()->user();
  

• Configuration: Override defaults via config/filament.php (if used by dependent packages).

Gotchas and Tips

Pitfalls

1. No Standalone Usage

   • This package is not designed for direct use—it’s a dependency for other Filament packages. Attempting to use it independently may lead to errors or undefined behavior.

2. Version Compatibility

   • Ensure compatibility with the Filament version (e.g., filament/support:v3 for Filament 3.x). Mixing versions may break functionality.

3. Overriding Core Classes

   • Avoid overriding Filament\Support\Contracts or Filament\Support\Enums unless extending for custom logic. Changes may conflict with dependent packages.

4. Testing Quirks

   • Filament::fake() must be called before assertions in tests. Forgetting this can cause tests to fail silently.

Debugging Tips

1. Enable Debugging Set FILAMENT_DEBUG=true in .env to log detailed errors from Filament utilities.

2. Check Dependent Packages If a helper method fails, verify it’s not a proxy for another package (e.g., str()->slug() might rely on spatie/array-to-xml).

3. Facades and Service Providers If a facade (e.g., Filament) isn’t available, ensure the service provider is registered in config/app.php:

   Filament\Support\FilamentServiceProvider::class,
   

Extension Points

1. Custom Helpers Extend the str(), arr(), or collect() helpers by publishing the package’s config (if supported) or creating a macro:

   str()->macro('customMethod', fn ($value) => strtolower($value));
   

2. New Contracts/Enums Create custom enums by extending Filament\Support\Enums\Enum:

   use Filament\Support\Enums\Enum;
   
   class CustomStatus extends Enum {
       public const Pending = 'pending';
       public const Approved = 'approved';
   }
   

3. Testing Utilities Extend TestCase for reusable test logic:

   class CustomTestCase extends TestCase {
       protected function setUp(): void {
           parent::setUp();
           $this->withoutExceptionHandling();
       }
   }
   

4. Configuration Overrides Publish the package’s config (if available) to modify defaults:

   php artisan vendor:publish --provider="Filament\Support\FilamentServiceProvider"
   

Performance Notes

• Avoid Overuse of Facades: Directly inject dependencies (e.g., Filament services) where possible to reduce overhead.
• Lazy-Loading: Some helpers (e.g., Filament::auth()) may trigger eager loading—cache results if used frequently.