Getting Started

Install the package with Composer, then publish any config if the package exposes it (php artisan vendor:publish).
Confirm yt-dlp is available on every runtime host: yt-dlp --version. v1.0.4 adds an installation check, so use it as an early guard in local, staging, queue-worker, and production environments.
Configure the binary path via config/env if yt-dlp is not on PATH (common with Laravel Forge, Docker, and shared hosting).
First use case: resolve the package service/facade in a controller or artisan command, pass a supported URL, and generate a download to a Laravel storage disk. Test locally with a short public video before wiring it into queues or user-facing flows.

Implementation Patterns

Inject the package service or use its facade in controllers, jobs, and commands; keep yt-dlp invocation out of controllers for anything long-running.
Validate and normalize URLs before passing them to the package, and reject unsupported or private URLs early.
Dispatch downloads as queued jobs. Store output on a configured disk (local, s3, etc.) and return/record the relative path rather than exposing raw filesystem paths.
Use the v1.0.4 installation check in a health check, deployment script, or preflight command so missing yt-dlp fails fast instead of during a user request.
Centralize yt-dlp options in config: binary path, temp directory, output template, format selection, timeouts, and proxy settings. Avoid scattering flags across call sites.
Integrate with Laravel events/notifications for job completion or failure, and clean up temp files and partial downloads on failure.
For test suites, mock the package service in feature tests and reserve real yt-dlp calls for a small integration suite.

The installation check only helps if it runs on the same host as the download. Queue workers, cron hosts, and container replicas may not share the same PATH or binary.
Prefer an explicit binary path in config/env rather than relying on PATH; web PHP-FPM and CLI often have different environments.
yt-dlp changes frequently. Pin or document an update strategy, and check yt-dlp --version in deployment diagnostics to avoid silent breakage from extractor changes.
Ensure the temp/output directory is writable by the PHP and queue user, and watch open_basedir, disk space, and max execution time.
Set job and process timeouts for large media; downloads can exceed default Laravel queue worker timeouts.
Treat user-supplied URLs and options as untrusted. Do not allow arbitrary yt-dlp flags from request input, and log stderr/stdout for debugging failed downloads.
Use Laravel’s process/logging facilities or the package’s exception handling to surface yt-dlp errors; generic “download failed” messages make debugging painful.
Extension points to watch: config overrides for binary path and options, custom output naming, events around download lifecycle, and the ability to swap/mock the underlying service in tests.