Matinee Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require awcodes/matinee
   

   Ensure you have a custom Filament theme configured.

2. Add CSS: In your theme’s CSS file (e.g., resources/css/filament/app.css):

   @source '../../../../vendor/awcodes/matinee/resources/**/*.blade.php';
   

3. First Use Case: Add the field to a Filament resource or form:

   use Awcodes\Matinée\Fields\OEmbedField;
   
   OEmbedField::make('video')
       ->label('Embed Video')
       ->required(),
   

Key Files to Review

• Package README (for Filament version compatibility).
• Filament Docs (for field customization).
• config/matinee.php (if generated; check for default settings).

Implementation Patterns

Common Workflows

1. Basic Embed Field:

   OEmbedField::make('youtube_url')
       ->label('YouTube Video')
       ->columnSpanFull(),
   

   • Supports YouTube, Vimeo, Twitter, and other OEmbed providers by default.

2. Customizing Providers:

   OEmbedField::make('custom_embed')
       ->providers([
           'soundcloud' => 'https://soundcloud.com/oembed',
       ]),
   

3. Integration with Resources:

   // In a Filament Resource
   public static function form(Form $form): Form
   {
       return $form
           ->schema([
               OEmbedField::make('hero_video')
                   ->required()
                   ->maxLength(255),
           ]);
   }
   

4. Validation & Sanitization:

   OEmbedField::make('trailer')
       ->rules(['url' => 'active_url|max:255'])
       ->sanitizeUrl(),
   

5. Displaying Embeds in Views:

   @if($record->video_url)
       <div class="matinee-embed">
           {!! $record->video_url->embed !!}
       </div>
   @endif
   

Advanced Patterns

• Dynamic Provider Loading: Use ->dynamicProviders() to fetch providers from an API or config.
• Custom Styling: Override the embed container class in your CSS:

  .matinee-embed iframe {
      max-width: 100%;
      aspect-ratio: 16/9;
  }
  

• Localization: Translate labels/placeholders via Filament’s localization system.

Gotchas and Tips

Pitfalls

1. Theme Dependency:

   • Issue: Embeds may not render without the @source CSS directive.
   • Fix: Double-check your theme’s CSS file includes the package’s Blade views.

2. Provider Limitations:

   • Issue: Some OEmbed endpoints (e.g., private SoundCloud tracks) may fail silently.
   • Fix: Use ->fallbackUrl() to provide a default embed or handle errors in ->mutate().

3. JSON Storage:

   • Issue: The field stores data as JSON in the DB (e.g., {"url":"https://youtube.com/..."}).
   • Fix: Use $record->video_url->url to access the raw URL; avoid direct JSON parsing.

4. CORS Restrictions:

   • Issue: Embeds from restricted domains (e.g., internal videos) may fail to load.
   • Fix: Proxy the embed URL via a Laravel route or use a CDN.

Debugging Tips

• Log Provider Responses:

  OEmbedField::make('debug_embed')
      ->logResponses(), // Logs provider API calls to Laravel logs
  

• Test with Known URLs: Use hardcoded URLs (e.g., https://www.youtube.com/watch?v=dQw4w9WgXcQ) to isolate issues.
• Check Network Tab: Verify OEmbed requests (e.g., https://www.youtube.com/oembed?url=...) return valid JSON.

Extension Points

1. Custom Providers: Extend the OEmbedProvider class to support niche platforms:

   class CustomProvider extends OEmbedProvider {
       public function getEndpoint(): string {
           return 'https://custom-site.com/oembed';
       }
   }
   

   Register via:

   OEmbedField::make('custom')
       ->providers(['custom' => CustomProvider::class]),
   

2. Post-Processing: Modify embed HTML after fetching:

   OEmbedField::make('poster')
       ->mutate(function ($state) {
           $state['embed'] = str_replace('width="560"', 'width="100%"', $state['embed']);
           return $state;
       }),
   

3. Livewire Integration: Use ->livewire() to update embeds dynamically without full page reloads:

   OEmbedField::make('live_embed')
       ->livewire(),
   

Configuration Quirks

• Default Providers: The package includes a default list (YouTube, Vimeo, etc.), but you can override them entirely:

  config(['matinee.providers' => []]);
  

• Caching: Enable caching for provider responses to reduce API calls:

  OEmbedField::make('cached_embed')
      ->cacheProviderResponses(minutes: 60),