Filament Studio Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation

   composer require flexpik/filament-studio
   php artisan vendor:publish --tag="filament-studio-migrations"
   php artisan migrate
   

2. Register Plugin Add to your app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel->plugins([
           FilamentStudioPlugin::make(),
       ]);
   }
   

3. First Collection Navigate to Studio > Collections in Filament admin panel. Click "Create Collection" and define:

   • Basic info (name, slug)
   • Fields (e.g., Text, Select, Date)
   • Settings (permissions, versioning)

4. First Record After saving the collection, visit its "Records" tab to create/edit records via the auto-generated CRUD interface.

Where to Look First

• Collections List: /admin/studio/collections
• Field Editor: /admin/studio/collections/{slug}/fields
• Records CRUD: /admin/studio/collections/{slug}/records
• Documentation: docs/field-types.md (for field customization)

First Use Case: Dynamic Product Catalog

1. Create a "Products" collection with fields:
   • name (Text)
   • price (Decimal)
   • sku (Slug)
   • categories (Multi-Select)
   • images (Repeater with Image fields)
2. Use the "List" panel in the dashboard to display products.
3. Leverage the API to integrate with frontend or third-party services.

Implementation Patterns

Core Workflows

1. Schema-First Development

• Pattern: Define all data structures in the Filament UI before writing any application code.
• Example:

  sequenceDiagram
    participant Admin
    participant Studio
    participant App
    Admin->>Studio: Create "Events" collection
    Admin->>Studio: Add fields (title, date, location, attendees)
    Studio->>App: Auto-generates CRUD, API, and Filament resources
    App->>Studio: Extend via hooks (e.g., modify form schema)
  

• When to Use:
  • Rapid prototyping of admin interfaces.
  • Projects where data requirements evolve frequently.
  • Multi-tenant SaaS applications with dynamic schemas.

2. Hook-Based Customization

• Pattern: Extend default behavior via lifecycle hooks.
• Common Hooks:

  // Modify form schema for a specific collection
  FilamentStudioPlugin::modifyFormSchema(
      fn (array $schema, $collection) => {
          if ($collection->slug === 'products') {
              $schema[] = TextInput::make('custom_field')->columnSpanFull();
          }
          return $schema;
      }
  );
  
  // Add custom validation
  FilamentStudioPlugin::afterFieldAdded(
      fn ($field) => {
          if ($field->type === 'email') {
              $field->validationRules = ['email', 'required'];
          }
      }
  );
  

• When to Use:
  • Adding custom fields or logic without creating a new field type.
  • Overriding default UI behavior (e.g., hiding fields conditionally).

3. Dashboard-Driven Analytics

• Pattern: Build dashboards dynamically without hardcoding views.
• Example:
  1. Create a "Sales" collection with amount, date, and product_id fields.
  2. Add a "Time Series" panel to the dashboard:
     • X-axis: date
     • Y-axis: sum(amount)
     • Filter: product_id = "123"
  3. Save the dashboard and assign it to a user role.
• When to Use:
  • Internal tools requiring real-time data visualization.
  • Client-facing dashboards in SaaS applications.

4. API-First Integration

• Pattern: Use the auto-generated REST API for frontend or external services.
• Example:

  # Get API key
  curl -X POST http://your-app.test/api/studio/api-keys \
       -H "Authorization: Bearer {FILAMENT_ADMIN_TOKEN}" \
       -d '{"name":"Frontend App"}'
  
  # Fetch records
  curl -X GET http://your-app.test/api/studio/collections/products/records \
       -H "Authorization: Bearer {API_KEY}"
  

• When to Use:
  • Decoupling frontend from Laravel (e.g., React/Vue apps).
  • Integrating with ERP/CRM systems.

5. Multi-Tenancy Isolation

• Pattern: Scope all data to tenants automatically.
• Example:

  // In a tenant-aware context (e.g., middleware)
  $tenant = Tenant::find($request->tenantId);
  $records = Studio::collection('products')
      ->forTenant($tenant)
      ->getRecords();
  

• When to Use:
  • SaaS applications with shared or isolated tenants.
  • Projects requiring tenant-specific data schemas.

Integration Tips

1. Filament Resource Integration

• Pattern: Embed Studio records in custom Filament resources.
• Example:

  use Flexpik\FilamentStudio\Resources\StudioResource;
  
  public static function getRelations(): array
  {
      return [
          StudioResource::make('products')
              ->query(fn (Builder $query) => $query->where('tenant_id', auth()->user()->tenant_id))
              ->titleColumn('name'),
      ];
  }
  

2. Seeding Initial Collections

• Pattern: Use Laravel seeders to pre-populate collections and fields.
• Example:

  public function run(): void
  {
      $collection = Studio::createCollection([
          'slug' => 'users',
          'name' => 'Users',
          'fields' => [
              [
                  'type' => 'text',
                  'name' => 'name',
                  'settings' => ['max_length' => 255],
              ],
              [
                  'type' => 'email',
                  'name' => 'email',
                  'settings' => ['unique' => true],
              ],
          ],
      ]);
  }
  

3. Custom Field Type Registration

• Pattern: Register reusable field types globally.
• Example:

  FilamentStudioPlugin::make()
      ->fieldTypes([
          'rating' => \App\FieldTypes\RatingFieldType::class,
          'currency' => \App\FieldTypes\CurrencyFieldType::class,
      ]);
  

4. Conditional UI Logic

• Pattern: Dynamically show/hide fields based on conditions.
• Example:

  FilamentStudioPlugin::modifyFormSchema(
      fn (array $schema, $collection) => {
          if ($collection->slug === 'subscriptions') {
              $schema[] = TextInput::make('trial_end_date')
                  ->visible(fn () => auth()->user()->hasRole('admin'));
          }
          return $schema;
      }
  );
  

5. MCP for AI Integration

• Pattern: Enable AI tools to manage your data model via natural language.
• Example:

  # Start MCP server
  php artisan mcp:start studio
  
  # Connect via stdio (e.g., in Cursor or Claude)
  {
    "mcpServers": {
      "studio": {
        "type": "stdio",
        "command": "php",
        "args": ["artisan", "mcp:start", "studio"],
        "env": {
          "STUDIO_API_KEY": "your-secure-key",
          "STUDIO_MCP_ENABLED": "true"
        }
      }
    }
  }
  

• Use Case:
  • AI-assisted schema design (e.g., "Add a 'last_login' field to the Users collection").
  • Automated data entry via AI agents.

Gotchas and Tips

Pitfalls

1. EAV Storage Quirks

• Issue: EAV storage can impact query performance for large datasets due to denormalized structure.

  • Solution:
    • Use with() to eager-load related fields:

      $records = Studio::collection('products')
          ->with(['images', 'categories'])
          ->getRecords();
      

    • Avoid complex joins in filters; use simple conditions where possible.
    • For analytical queries, consider materialized views or caching.

• Tip: Monitor studio_values table size; optimize with indexes on record_id and field_name.

2. Field Type Mismatches

• Issue: Changing a field's eav_cast (e.g., from Integer to Text) may corrupt existing data.
  • Solution:
    • Backup the database before schema changes.
    • Use migrations to transform data:

      Schema::table('studio_values', function (Blueprint $table) {
          $table->text('value_text')->nullable()->after('value');
      });
      

    • Consider using FilamentStudioPlugin::afterFieldUpdated() to handle