Statamic Mux Id Laravel Package

Getting Started

1. Install the package with Composer and publish its config:

   composer require <vendor>/<package>
   php artisan vendor:publish --tag=mux-config
   

2. Add Mux credentials to .env:

   MUX_TOKEN_ID=
   MUX_TOKEN_SECRET=
   

3. Add the Mux field to the Statamic asset container blueprint where videos should live, e.g. resources/blueprints/assets/videos.yaml.
4. Upload a video through the Statamic Control Panel. The package creates a Mux asset and writes Mux metadata back onto the Statamic asset.

Where to look first:

• config/mux.php for credentials, queue, and API settings.
• The asset container blueprint YAML for the Mux field.
• The uploaded asset’s metadata after the upload completes. In v0.1.1, permanent Mux API failures appear there as status: errored with error details rather than breaking the upload.

First use case: upload one video, confirm a Mux asset is created, then render the asset in a template only when its metadata status indicates success.

Implementation Patterns

• Blueprint setup: Keep the Mux field in the asset blueprint but rely on the v0.1.1 revealer behavior. The metadata field is collapsed by default, so the asset edit screen stays focused on normal Statamic fields.
• Upload flow: Let Statamic handle the asset upload and let the package create the Mux asset. Avoid wrapping the upload in custom logic that catches all exceptions; v0.1.1 intentionally rethrows non-4xx errors so queue retries can work.
• Status-aware rendering: Read the asset metadata status before using playback IDs or thumbnails. Treat errored as a terminal state and render a fallback or admin-facing warning.
• Queue-backed processing: Run a real queue worker in production. Transient Mux/server failures are retryable through the queue; configure tries and backoff on the queue worker/job rather than adding package-level retry logic.
• Operational visibility: Periodically query assets with status: errored and surface the stored Mux error details in the Control Panel or an internal dashboard. This is the intended v0.1.1 failure path.
• Programmatic uploads: When attaching videos outside the Control Panel, use Statamic’s asset APIs against a container whose blueprint includes the Mux field. Verify metadata after save; do not assume the Mux asset exists immediately.
• Local development: Test with QUEUE_CONNECTION=sync as well as a real queue. v0.1.1 specifically fixes synchronous queue runs so permanent Mux errors do not abort the Statamic upload.

Gotchas and Tips

• Permanent vs. transient errors: v0.1.1 treats 4xx Mux API failures as permanent and stores status: errored on asset metadata. Non-4xx failures are rethrown so the queue can retry. Do not catch and swallow those rethrown errors in custom jobs.
• Sync queues: Before v0.1.1, a permanent Mux error during a synchronous queue run could break the Statamic upload. After upgrading, uploads should complete and the asset metadata should show the error. Still verify this path locally.
• Hidden metadata field: The Mux field is behind a revealer button in the asset blueprint. If you expect to see status immediately after upload, click the revealer or inspect the asset’s metadata directly.
• Check status before playback: Do not assume every uploaded asset has a playable Mux asset. Gate playback, poster images, and API responses on metadata status.
• Most 4xx errors are configuration or input issues: Bad token, missing permissions, unsupported file type, or invalid Mux settings. Fix credentials/config or the source file before retrying; retrying a permanent error will not help.
• Queue configuration matters: Transient failures rely on your queue retry policy. Ensure workers are running and inspect failed_jobs when uploads remain in a non-final state.
• Blueprint/cache quirks: After changing the asset blueprint or field configuration, clear Statamic’s Stache/cache if the Control Panel does not reflect the change:

  php artisan statamic:stache:clear
  php artisan cache:clear
  

• Debugging errored assets: Inspect the asset metadata for the stored Mux error details first. If the metadata is empty, check application logs and the queue worker output for rethrown non-4xx errors.
• Extension point: Keep custom notification or fallback logic outside the field itself. Hook into Statamic asset save/upload events or read metadata status after processing rather than modifying package internals.