{"id":18552016,"url":"https://github.com/baraja-core/video-token","last_synced_at":"2026-05-10T16:43:56.760Z","repository":{"id":48560356,"uuid":"385232808","full_name":"baraja-core/video-token","owner":"baraja-core","description":"Parse video token from user string or URL.","archived":false,"fork":false,"pushed_at":"2022-11-03T19:25:25.000Z","size":29,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-16T07:06:00.702Z","etag":null,"topics":["parser","php","token","video","vimeo","youtube"],"latest_commit_sha":null,"homepage":"https://php.baraja.cz","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/baraja-core.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/funding.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":"janbarasek","custom":["https://baraja.cz","https://php.baraja.cz","https://vue.baraja.cz"]}},"created_at":"2021-07-12T12:02:04.000Z","updated_at":"2021-12-22T10:31:38.000Z","dependencies_parsed_at":"2023-01-21T12:17:21.158Z","dependency_job_id":null,"html_url":"https://github.com/baraja-core/video-token","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":"baraja-core/template","purl":"pkg:github/baraja-core/video-token","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/baraja-core%2Fvideo-token","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/baraja-core%2Fvideo-token/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/baraja-core%2Fvideo-token/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/baraja-core%2Fvideo-token/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/baraja-core","download_url":"https://codeload.github.com/baraja-core/video-token/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/baraja-core%2Fvideo-token/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264926332,"owners_count":23684320,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["parser","php","token","video","vimeo","youtube"],"created_at":"2024-11-06T21:11:36.363Z","updated_at":"2026-05-10T16:43:56.752Z","avatar_url":"https://github.com/baraja-core.png","language":"PHP","funding_links":["https://github.com/sponsors/janbarasek","https://baraja.cz","https://php.baraja.cz","https://vue.baraja.cz"],"categories":[],"sub_categories":[],"readme":"# 🎬 Video Token\n\nA lightweight PHP library for parsing and normalizing video tokens from YouTube and Vimeo URLs. Automatically extracts video identifiers from various URL formats and provides a unified interface for generating embed URLs and thumbnail images.\n\n## ✨ Key Features\n\n- **Automatic provider detection** - Identifies YouTube or Vimeo based on URL structure or token format\n- **Multiple URL format support** - Handles standard URLs, short URLs, embed codes, and URL-encoded strings\n- **Token validation** - Validates token format and length for each provider\n- **Embed URL generation** - Creates ready-to-use iframe embed URLs\n- **Thumbnail retrieval** - Fetches video thumbnail URLs (direct for YouTube, via API for Vimeo)\n- **Zero dependencies** - Pure PHP implementation with no external dependencies\n- **Strict typing** - Full PHP 8.0+ strict type declarations\n\n## 🏗️ Architecture\n\nThe library consists of a single immutable value object `VideoToken` that encapsulates:\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                       VideoToken                            │\n├─────────────────────────────────────────────────────────────┤\n│  Input: URL or Token + Provider                             │\n│    │                                                        │\n│    ▼                                                        │\n│  ┌─────────────────────┐                                    │\n│  │  URL Parser         │ ─── Detects domain \u0026 extracts path │\n│  └─────────────────────┘                                    │\n│    │                                                        │\n│    ▼                                                        │\n│  ┌─────────────────────┐                                    │\n│  │  Provider Resolver  │ ─── YouTube: 11-char alphanumeric  │\n│  │                     │ ─── Vimeo: 8-digit numeric         │\n│  └─────────────────────┘                                    │\n│    │                                                        │\n│    ▼                                                        │\n│  ┌─────────────────────┐                                    │\n│  │  Token Validator    │ ─── Max 32 characters              │\n│  └─────────────────────┘                                    │\n│    │                                                        │\n│    ▼                                                        │\n│  Output: Validated token + provider                         │\n│    • getToken()        → Raw video identifier               │\n│    • getProvider()     → 'youtube' | 'vimeo'                │\n│    • getUrl()          → Embed URL                          │\n│    • getThumbnailUrl() → Thumbnail image URL                │\n└─────────────────────────────────────────────────────────────┘\n```\n\n## 🎯 Supported Providers\n\n### YouTube\n\nThe library recognizes YouTube videos from the following domains:\n- `youtube.com`\n- `youtu.be`\n- `youtube-nocookie.com`\n- `yt.be`\n\n**Supported URL formats:**\n- Standard watch URL: `https://www.youtube.com/watch?v=VIDEO_ID`\n- Short URL: `https://youtu.be/VIDEO_ID`\n- Embed URL: `https://www.youtube.com/embed/VIDEO_ID`\n- Various legacy formats: `/v/`, `/vi/`, `/e/`, `ytscreeningroom?v=`\n- URL-encoded formats: `watch%3Fv%3D`\n- Playlist URLs with video: `watchv=VIDEO_ID\u0026list=...`\n\nYouTube tokens are 11 characters long, containing alphanumeric characters, hyphens, and underscores.\n\n### Vimeo\n\nThe library recognizes Vimeo videos from:\n- `vimeo.com`\n- `player.vimeo.com`\n\nVimeo tokens are 8-digit numeric identifiers.\n\n## 📦 Installation\n\nIt's best to use [Composer](https://getcomposer.org) for installation, and you can also find the package on\n[Packagist](https://packagist.org/packages/baraja-core/video-token) and\n[GitHub](https://github.com/baraja-core/video-token).\n\nTo install, simply use the command:\n\n```shell\n$ composer require baraja-core/video-token\n```\n\n**Requirements:**\n- PHP 8.0 or higher\n\n## 🚀 Basic Usage\n\n### Creating a VideoToken from URL\n\n```php\nuse Baraja\\VideoToken\\VideoToken;\n\n// From a YouTube URL\n$token = new VideoToken('https://www.youtube.com/watch?v=dQw4w9WgXcQ');\n\necho $token-\u003egetToken();    // dQw4w9WgXcQ\necho $token-\u003egetProvider(); // youtube\n```\n\n### Creating a VideoToken with explicit provider\n\n```php\nuse Baraja\\VideoToken\\VideoToken;\n\n// When you already have the token and know the provider\n$token = new VideoToken('dQw4w9WgXcQ', 'youtube');\n```\n\n### Getting the embed URL\n\n```php\nuse Baraja\\VideoToken\\VideoToken;\n\n$token = new VideoToken('https://www.youtube.com/watch?v=dQw4w9WgXcQ');\n\necho $token-\u003egetUrl();\n// YouTube: https://www.youtube.com/embed/dQw4w9WgXcQ?rel=0\n// Vimeo:   https://player.vimeo.com/video/12345678\n```\n\n### Getting the thumbnail URL\n\n```php\nuse Baraja\\VideoToken\\VideoToken;\n\n// YouTube - direct URL, no API call needed\n$youtube = new VideoToken('https://www.youtube.com/watch?v=dQw4w9WgXcQ');\necho $youtube-\u003egetThumbnailUrl();\n// https://img.youtube.com/vi/dQw4w9WgXcQ/maxresdefault.jpg\n\n// Vimeo - fetches from Vimeo oEmbed API\n$vimeo = new VideoToken('https://vimeo.com/12345678');\necho $vimeo-\u003egetThumbnailUrl();\n// Returns thumbnail URL from Vimeo API response\n```\n\n### Working with Vimeo\n\n```php\nuse Baraja\\VideoToken\\VideoToken;\n\n$token = new VideoToken('https://vimeo.com/76979871');\n\necho $token-\u003egetToken();    // 76979871\necho $token-\u003egetProvider(); // vimeo\necho $token-\u003egetUrl();      // https://player.vimeo.com/video/76979871\n```\n\n## 🔍 Static URL Parser\n\nFor cases where you only need to extract a YouTube token without creating a full `VideoToken` object:\n\n```php\nuse Baraja\\VideoToken\\VideoToken;\n\n// Parse various YouTube URL formats\n$token = VideoToken::parseYouTubeTokenByUrl('watch?v=dQw4w9WgXcQ');\n// Returns: dQw4w9WgXcQ\n\n$token = VideoToken::parseYouTubeTokenByUrl('embed/dQw4w9WgXcQ');\n// Returns: dQw4w9WgXcQ\n\n$token = VideoToken::parseYouTubeTokenByUrl('dQw4w9WgXcQ');\n// Returns: dQw4w9WgXcQ (exact match)\n\n// User channels return null (no video token)\n$token = VideoToken::parseYouTubeTokenByUrl('user/SomeChannel');\n// Returns: null\n```\n\n## ⚠️ Error Handling\n\nThe library throws `\\InvalidArgumentException` in the following cases:\n\n```php\nuse Baraja\\VideoToken\\VideoToken;\n\n// Token too long (max 32 characters)\ntry {\n    new VideoToken('this_token_is_way_too_long_to_be_valid_video_id');\n} catch (\\InvalidArgumentException $e) {\n    // Video token \"...\" is too long.\n}\n\n// Invalid URL format\ntry {\n    new VideoToken('https://invalid-video-site.com/video/123');\n} catch (\\InvalidArgumentException $e) {\n    // Token or URL \"...\" is invalid.\n}\n\n// Missing provider when token format is ambiguous\ntry {\n    new VideoToken('ambiguous-token');\n} catch (\\InvalidArgumentException $e) {\n    // Provider for token \"...\" is mandatory.\n}\n```\n\nThe `getUrl()` method throws `\\LogicException` if called with an unsupported provider (should not happen with normal usage).\n\n## ⚡ Performance Considerations\n\n### Thumbnail URL Caching\n\n**Important:** The `getThumbnailUrl()` method for Vimeo videos makes an HTTP request to the Vimeo oEmbed API. Always cache the result:\n\n```php\n$token = new VideoToken('https://vimeo.com/76979871');\n\n// Cache this result!\n$thumbnailUrl = $cache-\u003eget('vimeo_thumb_' . $token-\u003egetToken(), function () use ($token) {\n    return $token-\u003egetThumbnailUrl();\n});\n```\n\nYouTube thumbnails are generated using a predictable URL pattern and don't require API calls.\n\n### Immutability\n\nThe `VideoToken` object is immutable. Once created, the token and provider cannot be changed. This makes it safe to pass around and cache without defensive copying.\n\n## 🔧 Provider Constants\n\nThe library provides constants for provider identification:\n\n```php\nuse Baraja\\VideoToken\\VideoToken;\n\nVideoToken::PROVIDER_YOUTUBE; // 'youtube'\nVideoToken::PROVIDER_VIMEO;   // 'vimeo'\n\n// Use in comparisons\nif ($token-\u003egetProvider() === VideoToken::PROVIDER_YOUTUBE) {\n    // YouTube-specific logic\n}\n```\n\n## 🌐 Use Cases\n\n### Embedding videos in HTML\n\n```php\n$token = new VideoToken($_POST['video_url']);\n\n$html = sprintf(\n    '\u003ciframe src=\"%s\" frameborder=\"0\" allowfullscreen\u003e\u003c/iframe\u003e',\n    htmlspecialchars($token-\u003egetUrl(), ENT_QUOTES, 'UTF-8')\n);\n```\n\n### Storing normalized video references\n\n```php\n// User submits various URL formats\n$input = 'https://youtu.be/dQw4w9WgXcQ?t=42';\n\n$token = new VideoToken($input);\n\n// Store only what you need\n$database-\u003einsert('videos', [\n    'token' =\u003e $token-\u003egetToken(),      // dQw4w9WgXcQ\n    'provider' =\u003e $token-\u003egetProvider(), // youtube\n]);\n```\n\n### Video preview cards\n\n```php\n$token = new VideoToken($videoUrl);\n\necho '\u003cdiv class=\"video-card\"\u003e';\necho '  \u003cimg src=\"' . htmlspecialchars($token-\u003egetThumbnailUrl()) . '\" alt=\"Video thumbnail\"\u003e';\necho '  \u003ca href=\"' . htmlspecialchars($token-\u003egetUrl()) . '\"\u003eWatch video\u003c/a\u003e';\necho '\u003c/div\u003e';\n```\n\n## 👤 Author\n\n**Jan Barášek**\nWebsite: [https://baraja.cz](https://baraja.cz)\n\n## 📄 License\n\n`baraja-core/video-token` is licensed under the MIT license. See the [LICENSE](https://github.com/baraja-core/video-token/blob/master/LICENSE) file for more details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbaraja-core%2Fvideo-token","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbaraja-core%2Fvideo-token","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbaraja-core%2Fvideo-token/lists"}