hazel/ytdlphp

A typed PHP 8.5+ wrapper for the yt-dlp command-line tool

v1.0.1 2026-06-09 05:38 UTC

Requires

• php: ^8.5
• ext-json: *
• ext-uri: *
• tempest/mapper: ^3.9
• tempest/process: ^3.9

Requires (Dev)

• phpunit/phpunit: ^11.5

MIT

• hazel

• media
• cli
• youtube
• video
• download
• youtube-dl
• yt-dlp

README

A typed PHP 8.5+ library for yt-dlp.

Build command-line arguments with a fluent API, run yt-dlp via Tempest Process, and parse JSON metadata into typed objects. URLs are validated with PHP's built-in URI extension (WHATWG).

Requirements

• PHP 8.5+
• Extensions: json, uri
• yt-dlp installed and available on PATH (or configured explicitly)

Installation

composer require hazel/ytdlphp

Quick start

use Ytdlphp\Options;
use Ytdlphp\YtDlp;

$ytDlp = new YtDlp();

$ytDlp->download(
    'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
    Options::create()
        ->format('bestvideo+bestaudio')
        ->output('%(title)s.%(ext)s'),
);

$info = $ytDlp->extractInfo('https://www.youtube.com/watch?v=dQw4w9WgXcQ');

echo $info->title;
echo $info->url?->toAsciiString();

Configuration

use Ytdlphp\Options;
use Ytdlphp\YtDlp;

$ytDlp = new YtDlp()
    ->withBinary('/usr/local/bin/yt-dlp')
    ->withWorkingDirectory('/tmp/downloads')
    ->withTimeout(300)
    ->withDefaultOptions(Options::create()->noWarnings());

Options builder

Options provides typed methods for common yt-dlp flags, backed by enums where useful:

use Ytdlphp\Option\AudioFormat;
use Ytdlphp\Option\Browser;
use Ytdlphp\Options;

$options = Options::create()
    ->extractAudio()
    ->audioFormat(AudioFormat::Mp3)
    ->cookiesFromBrowser(Browser::Firefox)
    ->noPlaylist()
    ->merge($extraOptions);

Use option() for flags not covered by a dedicated method.

URLs

Pass strings or Uri\WhatWg\Url instances. Strings are validated before yt-dlp runs:

use Uri\WhatWg\Url;
use Ytdlphp\UrlParser;

$url = UrlParser::parse('https://example.com/watch?v=abc');
$ytDlp->extractInfo($url);

$mediaUrls = $ytDlp->getUrls('https://example.com/watch?v=abc');
foreach ($mediaUrls as $mediaUrl) {
    echo $mediaUrl->toAsciiString();
}

Testing

composer test

License

MIT. See LICENSE.