Statamic Ytlistr Laravel Package

Getting Started

1. Install the package with Composer and publish its config/assets/migrations as documented:

   composer require <vendor>/<package>
   php artisan vendor:publish --provider="<Vendor>\<Package>\<PackageServiceProvider>"
   

2. Choose a storage driver. For most apps, start with the default database-backed storage unless you specifically want file-based, version-controlled content. If using YAML storage, ensure the configured directory is writable and excluded or committed intentionally.
3. Configure YouTube integration: add the required API key / OAuth credentials to config/services.php or the package config, then clear config cache:

   php artisan config:clear
   

4. Run migrations if the default storage uses the database:

   php artisan migrate
   

5. First use case: create a video record, let the package resolve its YouTube metadata/URL, and render it in a Blade view:

   @php($youtubeUrl = data_get($video, 'youtube_url'))
   @if($youtubeUrl)
       <iframe src="{{ $youtubeUrl }}" allowfullscreen></iframe>
   @endif
   

6. Look first at the published config file, the package README’s Blade and Antler examples, and the bundled Pest tests. The tests are the fastest way to understand expected model attributes, storage behavior, and sync assumptions.

Implementation Patterns

• Automatic sync on model events: If the package auto-syncs with YouTube on create/update, keep YouTube API calls out of request-critical paths where possible. Dispatch sync work to the queue if the package exposes a job or if you wrap the sync call in your own job.
• Scheduled sync: Register the package’s sync command/job in app/Console/Kernel.php or routes/console.php depending on your Laravel version. For hourly syncs:

  $schedule->job(new SyncVideosWithYouTube)->hourly()->withoutOverlapping();
  

  For daily syncs:

  $schedule->job(new SyncVideosWithYouTube)->dailyAt('02:00')->withoutOverlapping();
  

  Ensure php artisan schedule:run is configured in cron and that queue workers are running if the sync job is queued.
• YAML storage workflows: Use YAML storage when video metadata should live in version control, e.g. marketing sites, documentation sites, or content-managed video galleries. Keep a clear convention for file names and directory structure, and validate YAML in CI if content editors can change it.
• Blade rendering: Prefer data_get($video, 'youtube_url') over direct property access when the object may be an array, Eloquent model, or DTO. This is especially useful when switching between database and YAML storage.
• Antler/Blade component integration: Follow the package’s updated examples for component props and slots. Normalize video data before passing it to components so your templates do not depend on storage-specific shapes.
• Testing: Use the package’s Pest tests as a reference. In your app tests, fake YouTube HTTP calls and assert that sync jobs are dispatched rather than hitting the real API. For YAML storage, use a temporary filesystem disk in tests.
• Operational observability: Log sync results, including video ID, YouTube ID, success/failure, and API error messages. This matters more once sync runs hourly or daily.

Gotchas and Tips

• YAML storage concurrency: File-based storage can suffer from race conditions if multiple processes write the same file. Avoid parallel writes to the same YAML file, use atomic writes if supported, and consider database storage for high-write environments.
• YouTube API quotas: Automatic and scheduled syncs can consume quota quickly. Sync only changed records where possible, stagger jobs, and monitor quota usage in Google Cloud Console.
• Scheduler assumptions: Adding a scheduled job does nothing unless the Laravel scheduler is actually running. Verify with php artisan schedule:list and check cron on production.
• Queue workers: If sync is queued, failed jobs will not retry unless workers and retry settings are configured. Use withoutOverlapping() and appropriate tries/backoff values.
• data_get() null safety: data_get($video, 'youtube_url') returns null if missing, so always guard before rendering an iframe or link. Do not assume every video has a YouTube URL.
• Config cache: After changing storage driver, YouTube credentials, or sync settings, run php artisan config:clear locally and redeploy with php artisan config:cache in production.
• Switching storage drivers: Moving from database to YAML, or vice versa, is not automatically a data migration. Plan an export/import step and verify IDs, relationships, and cached metadata.
• File permissions: YAML storage requires the configured path to be writable by PHP and your queue workers. Containerized deployments need persistent volumes or build-time content generation.
• Extension points: Prefer publishing and overriding config, views, and jobs rather than editing vendor files. If the package dispatches events around sync, hook into those for cache invalidation, search indexing, or notifications rather than duplicating sync logic.
• Pest tests are a feature, not a guarantee: The new test suite improves confidence, but your app still needs integration tests for your storage driver, queue configuration, and Blade/Antler rendering.