Getting Started

Minimal Steps

Installation:

composer require tomatophp/filament-helpers

Publish the package config (if needed) with:

php artisan vendor:publish --provider="TomatoPHP\FilamentHelpers\FilamentHelpersServiceProvider"

First Command Execution: Run the generator command:
```
php artisan filament:helpers
```
- Select "Form" or "Table" as the type.
- Choose a resource (or specify a custom path).
- Name your helper class (e.g., UserForm or UserTable).

First Use Case:

For Forms: Replace the default form() method in your Filament resource with:

use App\Filament\Resources\AccountResource\Forms\UserForm;

public function form(Form $form): Form
{
    return UserForm::make($form);
}

For Tables: Replace the default table() method with:

use App\Filament\Resources\AccountResource\Tables\UserTable;

public function table(Table $table): Table
{
    return UserTable::make($table);
}

Implementation Patterns

Usage Patterns

Modular Organization:
- Generate helpers inside modules (if using Spatie Laravel Modules) by selecting the module path during generation.
- Example structure:
```
/Modules/Account/Resources/AccountResource/
├── Forms/
│   └── UserForm.php
└── Tables/
    └── UserTable.php
```

Reusable Components:

Extend generated classes to share logic across resources:

namespace App\Filament\Resources\Shared;

use TomatoPHP\FilamentHelpers\Helpers\FormHelper;

class BaseUserForm extends FormHelper
{
    protected function configure(): void
    {
        $this->schema([
            TextInput::make('name')->required(),
        ]);
    }
}

Inherit in resource-specific helpers:

use App\Filament\Resources\Shared\BaseUserForm;

class UserForm extends BaseUserForm { ... }

Dynamic Configuration:

Use closure-based methods for dynamic fields/tables:

protected function getFormSchema(): array
{
    return [
        TextInput::make('email')
            ->required()
            ->email(),
        Select::make('role')
            ->options(fn () => Role::all()->pluck('name', 'id')),
    ];
}

Action Integration:

Generate action helpers (if supported in future updates) to centralize action logic:

use TomatoPHP\FilamentHelpers\Helpers\ActionHelper;

class ExportUsersAction extends ActionHelper
{
    protected function handle(): void
    {
        // Custom export logic
    }
}

Testing:

Mock helpers in tests:

$formHelper = Mockery::mock(UserForm::class);
$formHelper->shouldReceive('make')
    ->andReturn($form);

Workflows

Rapid Prototyping:
- Generate a helper, then refine incrementally by editing the generated file.
- Example workflow:
```
php artisan filament:helpers --type=Form --name=UserForm --resource=AccountResource
```
  Edit app/Filament/Resources/AccountResource/Forms/UserForm.php.
Team Collaboration:
- Use shared helper templates (via Laravel Mixins or custom scripts) to enforce consistency.
- Example: Override configure() in a base helper class.

Migration from Default Forms/Tables:

Replace one resource at a time to minimize risk:

- public function form(Form $form): Form { return $form; }
+ public function form(Form $form): Form { return UserForm::make($form); }

Gotchas and Tips

Pitfalls

Namespace Conflicts:
- Ensure generated classes do not collide with existing files.
- Tip: Use --path flag to specify a custom directory:
```
php artisan filament:helpers --path=app/Filament/Helpers
```
Caching Issues:
- Clear Filament’s view cache after generating new helpers:
```
php artisan filament:cache-clear
```
- Or disable caching in config/filament.php temporarily during development.
Overwriting Files:
- The generator appends to existing files if they exist (check the --force flag in future updates).
- Tip: Backup critical files before running the command.

Dynamic Dependencies:

Avoid circular dependencies when extending helpers. Example:

// ❌ Avoid
class UserForm extends BaseForm { ... }
class BaseForm extends UserForm { ... }

Filament Version Compatibility:
- Test with specific Filament versions (e.g., filament/filament:^3.0). The package may not support all minor versions.

Debugging

Generated Class Not Loading:
- Verify the autoload includes the generated directory:
```
composer dump-autoload
```
- Check for typos in the use statement (e.g., UserForm vs. userForm).
Blank/Unrendered Forms/Tables:
- Ensure the helper’s configure() or make() method is not empty.
- Check for missing schema or invalid column definitions.
CSRF or Validation Errors:
- Regenerate the helper if hidden fields (e.g., _method, _token) are missing.
- Tip: Extend the base class to add defaults:
```
protected function configure(): void
{
    $this->schema([...])->columns([...]);
    $this->extraAttributes(['_method' => 'PUT']);
}
```

Tips

Customize the Generator:
- Override the default template by publishing and modifying:
```
php artisan vendor:publish --tag=filament-helpers-templates
```
- Edit files in resources/views/vendor/filament-helpers/.
Partial Generation:
- Generate only the schema first, then manually add logic:
```
php artisan filament:helpers --type=Form --name=UserForm --schema-only
```
IDE Support:
- Add the generated directory to your IDE’s include path to avoid "Class not found" warnings.

Performance:

For large tables, lazy-load columns:

protected function getTableColumns(): array
{
    return fn () => [
        TextColumn::make('name'),
        // Dynamically load other columns
    ];
}

Extending Functionality:

Use traits to add reusable methods:

trait HasSoftDeletes
{
    public static function make(Form $form): Form
    {
        return parent::make($form)
            ->schema([
                Toggle::make('is_active')
                    ->default(true),
            ]);
    }
}

Attach to helpers:

use HasSoftDeletes;

class UserForm extends FormHelper
{
    use HasSoftDeletes;
}

Documentation:

Add PHPDoc blocks to generated helpers for better IDE hints:

/**
 * @return array<int, Column>
 */
protected function getTableColumns(): array { ... }

Filament Helpers Laravel Package