ekstremedia / laravel-youtube
A modern Laravel package for YouTube API v3 integration with OAuth2, automatic token refresh, and beautiful admin panel
Installs: 17
Dependents: 0
Suggesters: 0
Security: 0
Stars: 0
Watchers: 0
Forks: 0
Open Issues: 0
pkg:composer/ekstremedia/laravel-youtube
Requires
- php: ^8.2
- google/apiclient: ^2.15
- google/apiclient-services: ^0.350 || ^0.420
- illuminate/database: ^11.0|^12.0
- illuminate/http: ^11.0|^12.0
- illuminate/support: ^11.0|^12.0
- illuminate/view: ^11.0|^12.0
Requires (Dev)
- laravel/pint: ^1.13
- orchestra/testbench: ^9.0|^10.0
- pestphp/pest: ^2.34|^3.0
- pestphp/pest-plugin-laravel: ^2.3|^3.0
- phpstan/phpstan: ^1.10 || ^2.0
This package is auto-updated.
Last update: 2025-11-12 21:04:02 UTC
README
A comprehensive Laravel package for YouTube API v3 integration with OAuth2 authentication, automatic token refresh, upload management, and extensive API coverage. Perfect for content creators, video platforms, and automated video upload systems.
๐ Features
Core Features
- ๐ OAuth2 Authentication - Secure authentication with automatic token refresh
- ๐น Video Management - Complete CRUD operations for videos
- ๐ค Advanced Upload - Chunked uploads with progress tracking & 15+ metadata fields
- ๐บ Channel Management - Designed for single-user/single-channel applications
- ๐จ Thumbnail Management - Custom thumbnail upload support
- ๐ฌ Playlist Operations - Create, manage, and organize video playlists
- ๐ฌ Caption/Subtitle Support - Upload, manage, and download captions in multiple formats
- ๐ Location & Recording Details - Geotag videos with coordinates and recording dates
- ๐ Queue Support - Background video uploads via Laravel jobs
- ๐ฏ Rate Limiting - Built-in rate limiting to respect API quotas
- ๐ Statistics Tracking - View counts, likes, and engagement metrics
- ๐ Webhook Support - Upload completion notifications
- ๐ Scheduled Publishing - Schedule videos for future publication
Special Features
- ๐ฅง Raspberry Pi Integration - Optimized for automated uploads from IoT devices
- ๐ Auto Token Refresh - Never worry about expired tokens
- ๐พ Database Storage - Track all uploads and video metadata
- ๐ Encrypted Token Storage - Secure storage of OAuth tokens
- ๐ Comprehensive Logging - Detailed logging for debugging
- ๐งช Test Coverage - Extensive test suite with Pest
๐ Requirements
- PHP 8.2 or higher
- Laravel 11.0 or 12.0
- Google API credentials (OAuth 2.0 Client ID)
- Composer
- Database (MySQL, PostgreSQL, SQLite)
๐ฆ Installation
Step 1: Install via Composer
composer require ekstremedia/laravel-youtube
Step 2: Publish Configuration and Migrations
# Publish configuration php artisan vendor:publish --provider="EkstreMedia\LaravelYouTube\YouTubeServiceProvider" --tag="youtube-config" # Publish migrations php artisan vendor:publish --provider="EkstreMedia\LaravelYouTube\YouTubeServiceProvider" --tag="youtube-migrations" # Optional: Publish views for authorization page php artisan vendor:publish --provider="EkstreMedia\LaravelYouTube\YouTubeServiceProvider" --tag="youtube-views"
Step 3: Configure Environment Variables
Add the following to your .env file:
# Required: YouTube OAuth2 Credentials YOUTUBE_CLIENT_ID=your-client-id-here YOUTUBE_CLIENT_SECRET=your-client-secret-here YOUTUBE_REDIRECT_URI=https://yourdomain.com/youtube/callback # Optional: Authentication Page YOUTUBE_AUTH_PAGE_PATH=youtube-authorize # Optional: Upload Settings YOUTUBE_UPLOAD_CHUNK_SIZE=10485760 # 10MB chunks YOUTUBE_UPLOAD_TIMEOUT=3600 # 1 hour YOUTUBE_UPLOAD_MAX_SIZE=137438953472 # 128GB (YouTube's max) # Optional: Default Settings YOUTUBE_DEFAULT_PRIVACY=private # private, unlisted, public YOUTUBE_DEFAULT_CATEGORY=22 # People & Blogs YOUTUBE_DEFAULT_LANGUAGE=en # Optional: Rate Limiting YOUTUBE_RATE_LIMIT_ENABLED=true YOUTUBE_RATE_LIMIT_PER_MINUTE=60 YOUTUBE_RATE_LIMIT_PER_HOUR=3000 # Optional: Logging YOUTUBE_LOGGING_ENABLED=true YOUTUBE_LOGGING_CHANNEL=youtube YOUTUBE_LOGGING_LEVEL=info
Step 4: Obtain Google API Credentials
- Go to Google Cloud Console
- Create a new project or select an existing one
- Enable the YouTube Data API v3
- Create OAuth 2.0 credentials:
- Application type: Web application
- Add authorized redirect URI:
https://yourdomain.com/youtube/callback
- Copy the Client ID and Client Secret to your
.envfile
Step 5: Run Migrations
php artisan migrate
๐ฏ Quick Start
Basic Usage
use EkstreMedia\LaravelYouTube\Facades\YouTube; // Authenticate user (redirect to Google) return redirect()->to(YouTube::getAuthUrl()); // After authentication, upload a video $video = YouTube::forUser(auth()->id()) ->uploadVideo( '/path/to/video.mp4', [ 'title' => 'My Amazing Video', 'description' => 'This is a great video!', 'tags' => ['laravel', 'youtube', 'api'], 'category_id' => '22', 'privacy_status' => 'public', ] ); echo "Video uploaded: " . $video->watch_url;
Raspberry Pi Integration
Perfect for automated timelapse or security camera uploads. The package is designed for single-user/single-channel applications.
Using the Service Without User Context
// Method 1: Use the default (most recent) active token YouTube::usingDefault()->uploadVideo($file, $metadata); // Method 2: Use a specific channel by ID YouTube::forChannel('UCxxxxxxxxxx')->uploadVideo($file, $metadata); // Method 3: For legacy support, specify user ID YouTube::forUser($userId)->uploadVideo($file, $metadata);
Complete Raspberry Pi Example
// In your Pi upload endpoint use Ekstremedia\LaravelYouTube\Facades\YouTube; Route::post('/api/pi/upload', function (Request $request) { $request->validate([ 'video' => 'required|file|mimes:mp4,avi,mov|max:5242880', // 5GB 'camera_id' => 'required|string', ]); $file = $request->file('video'); // Upload using default token (single-user mode) $video = YouTube::usingDefault()->uploadVideo($file, [ 'title' => "Pi Camera {$request->camera_id} - " . now()->format('Y-m-d H:i'), 'description' => 'Automated timelapse from Raspberry Pi', 'tags' => ['raspberry-pi', 'timelapse', $request->camera_id], 'privacy_status' => 'unlisted', ]); return response()->json([ 'success' => true, 'video_id' => $video->video_id, 'watch_url' => $video->watch_url, ]); });
From Raspberry Pi (Shell Script)
#!/bin/bash # On your Raspberry Pi VIDEO_FILE="/home/pi/videos/timelapse_$(date +%Y%m%d_%H%M%S).mp4" API_ENDPOINT="https://your-domain.com/api/pi/upload" API_TOKEN="your-api-token" # Upload to your Laravel API curl -X POST $API_ENDPOINT \ -H "Authorization: Bearer $API_TOKEN" \ -F "video=@$VIDEO_FILE" \ -F "camera_id=pi_camera_1"
One-Time Google OAuth Setup
Visit the authorization page to connect your YouTube channel:
https://yourdomain.com/youtube-authorize
The page will:
- Check if credentials are configured
- Show your connected channel (if any)
- Allow you to authorize/re-authorize with Google
- Automatically refresh expired tokens
After authorization, all uploads will use this token automatically.
๐ Comprehensive Documentation
Authentication Page
The package includes a simple authentication page for connecting your YouTube channel:
Access the page: https://yourdomain.com/youtube-authorize (configurable)
Features:
- Check if credentials are configured
- View connected YouTube channel
- One-click authorize/re-authorize
- Automatic token refresh
- Clean, simple interface
- Protected by authentication - Requires logged-in user by default
Security:
By default, the authorization page is protected with the auth middleware. Only logged-in users can access it.
To customize the middleware protection, publish and edit the config file:
// config/youtube.php 'routes' => [ 'auth_page' => [ 'middleware' => ['web', 'auth'], // Default: requires login // Examples: // 'middleware' => ['web', 'auth:admin'], // Admin guard // 'middleware' => ['web', 'can:manage-youtube'], // Laravel Gate // 'middleware' => ['web'], // No authentication ], ],
Configuration:
YOUTUBE_AUTH_PAGE_PATH=youtube-authorize
Usage in your app:
// Link to authentication page <a href="{{ route('youtube.authorize') }}">Connect YouTube</a> // Or use the configured path <a href="/{{ config('youtube.routes.auth_page.path') }}">Authorize YouTube</a>
The page shows:
- Configuration status (credentials check)
- Connected channel information
- Authorization button
- Token expiration and refresh status
Authentication & Token Management
OAuth Flow
use EkstreMedia\LaravelYouTube\Services\AuthService; $authService = app(AuthService::class); // Generate OAuth URL with state for CSRF protection $state = Str::random(40); session(['youtube_oauth_state' => $state]); $authUrl = $authService->getAuthUrl($state); // In callback handler if (request('state') !== session('youtube_oauth_state')) { abort(403, 'Invalid state'); } // Exchange code for tokens $tokens = $authService->exchangeCode(request('code'));
Token Storage & Management
use EkstreMedia\LaravelYouTube\Services\TokenManager; $tokenManager = app(TokenManager::class); // Store tokens after OAuth $token = $tokenManager->storeToken( $tokens, $channelInfo, auth()->id() ); // Get active token for user $token = $tokenManager->getActiveToken(auth()->id()); // Check if refresh needed (within 5 minutes of expiry) if ($tokenManager->needsRefresh($token)) { $newTokens = $authService->refreshAccessToken($token->refresh_token); $tokenManager->updateToken($token, $newTokens); } // Handle multiple channels $tokens = $tokenManager->getUserTokens(auth()->id()); foreach ($tokens as $token) { echo "Channel: {$token->channel_title}\n"; }
Video Management
Upload Videos
use EkstreMedia\LaravelYouTube\Facades\YouTube; // Simple upload $video = YouTube::forUser(auth()->id())->uploadVideo( $request->file('video'), [ 'title' => 'My Video', 'description' => 'Video description', 'tags' => ['tag1', 'tag2'], 'category_id' => '22', // People & Blogs 'privacy_status' => 'private', // private, unlisted, public ] ); // Advanced upload with all metadata options $video = YouTube::forUser(auth()->id())->uploadVideo( '/path/to/large-video.mp4', [ // Basic metadata 'title' => 'Large Video Upload', 'description' => 'Testing chunked upload', 'tags' => ['large', 'chunked'], 'category_id' => '22', // Privacy & Status 'privacy_status' => 'private', 'made_for_kids' => false, 'self_declared_made_for_kids' => false, 'embeddable' => true, 'public_stats_viewable' => true, 'publish_at' => '2024-12-31T12:00:00Z', // Scheduled publishing // License & Language 'license' => 'creativeCommon', 'default_language' => 'en', 'default_audio_language' => 'en-US', // Recording details (great for travel vlogs, security cameras) 'recording_date' => '2024-01-15T10:00:00Z', 'location' => [ 'latitude' => 59.9139, 'longitude' => 10.7522, 'altitude' => 100.0, 'description' => 'Oslo, Norway', ], // Custom thumbnail 'thumbnail' => '/path/to/thumbnail.jpg', ], [ 'chunk_size' => 50 * 1024 * 1024, // 50MB chunks 'notify_url' => 'https://yourapp.com/webhook', 'progress_callback' => function ($uploaded, $total) { $percent = round(($uploaded / $total) * 100); Log::info("Upload progress: {$percent}%"); } ] );
Manage Videos
// Get user's videos $videos = YouTube::forUser(auth()->id())->getVideos([ 'maxResults' => 50, 'order' => 'date', // date, rating, relevance, title, viewCount 'type' => 'video', 'videoDefinition' => 'high', // any, high, standard 'videoDuration' => 'medium', // short (<4min), medium (4-20min), long (>20min) ]); // Get single video details $video = YouTube::forUser(auth()->id())->getVideo('video-id', [ 'snippet', 'contentDetails', 'statistics', 'status', 'processingDetails' ]); // Update video metadata $updated = YouTube::forUser(auth()->id())->updateVideo('video-id', [ 'title' => 'Updated Title', 'description' => 'Updated description', 'tags' => ['new', 'tags'], 'category_id' => '24', 'privacy_status' => 'public', ]); // Delete video YouTube::forUser(auth()->id())->deleteVideo('video-id');
Channel Management
// Get channel info $channel = YouTube::forUser(auth()->id())->getChannel([ 'snippet', 'contentDetails', 'statistics', 'brandingSettings', 'contentOwnerDetails', 'localizations', 'status', 'topicDetails' ]); // Get channel videos $videos = YouTube::forUser(auth()->id())->getChannelVideos('channel-id', [ 'maxResults' => 50, 'order' => 'date', ]); // Switch between multiple channels $tokens = YouTubeToken::where('user_id', auth()->id())->get(); foreach ($tokens as $token) { $youtube = YouTube::withToken($token); $channel = $youtube->getChannel(); echo "Channel: {$channel['title']} ({$channel['subscriberCount']} subscribers)\n"; }
Playlist Management
// Create a new playlist $playlist = YouTube::usingDefault()->createPlaylist('My Playlist', [ 'description' => 'Collection of my favorite videos', 'privacy_status' => 'public', // private, public, unlisted 'tags' => ['favorites', 'collection'], ]); // Get all playlists $result = YouTube::usingDefault()->getPlaylists(); foreach ($result['playlists'] as $playlist) { echo "{$playlist['title']} - {$playlist['item_count']} videos\n"; } // Add video to playlist YouTube::usingDefault()->addVideoToPlaylist( 'video-id', 'playlist-id', 0 // Position (0 = first) ); // Get videos in a playlist $result = YouTube::usingDefault()->getPlaylistVideos('playlist-id'); foreach ($result['videos'] as $video) { echo "{$video['title']} (position: {$video['position']})\n"; } // Update playlist YouTube::usingDefault()->updatePlaylist('playlist-id', [ 'title' => 'Updated Title', 'privacy_status' => 'public', ]); // Delete playlist YouTube::usingDefault()->deletePlaylist('playlist-id');
Caption/Subtitle Management
// Upload captions (supports SRT, VTT, TTML, SBV) $caption = YouTube::usingDefault()->uploadCaption( 'video-id', 'en', // Language code '/path/to/captions.srt', [ 'name' => 'English Subtitles', 'is_draft' => false, ] ); // List all captions for a video $captions = YouTube::usingDefault()->getCaptions('video-id'); foreach ($captions as $caption) { echo "{$caption['name']} ({$caption['language']})\n"; } // Update caption metadata or file YouTube::usingDefault()->updateCaption( 'caption-id', ['name' => 'Updated English'], '/path/to/new-captions.srt' // Optional: new file ); // Download captions in different formats $srt = YouTube::usingDefault()->downloadCaption('caption-id', 'srt'); $vtt = YouTube::usingDefault()->downloadCaption('caption-id', 'vtt'); file_put_contents('captions.srt', $srt); // Delete captions YouTube::usingDefault()->deleteCaption('caption-id');
Background Jobs & Queues
You can implement your own background job processing. Here's an example:
// Create your own job namespace App\Jobs; use Ekstremedia\LaravelYouTube\Facades\YouTube; use Illuminate\Bus\Queueable; use Illuminate\Contracts\Queue\ShouldQueue; use Illuminate\Foundation\Bus\Dispatchable; use Illuminate\Queue\InteractsWithQueue; use Illuminate\Queue\SerializesModels; class UploadYouTubeVideo implements ShouldQueue { use Dispatchable, InteractsWithQueue, Queueable, SerializesModels; public function __construct( public string $videoPath, public array $metadata ) {} public function handle(): void { $video = YouTube::usingDefault()->uploadVideo( $this->videoPath, $this->metadata ); // Clean up temporary file unlink($this->videoPath); } } // Dispatch the job UploadYouTubeVideo::dispatch( videoPath: '/path/to/video.mp4', metadata: [ 'title' => 'Queued Upload', 'description' => 'Uploaded via queue', 'tags' => ['queued', 'background'], 'privacy_status' => 'private', ] )->onQueue('media');
Advanced Features
Live Streaming
// Create live broadcast $broadcast = YouTube::forUser(auth()->id())->createLiveBroadcast([ 'title' => 'Live Stream', 'description' => 'Live streaming event', 'scheduled_start_time' => now()->addHour(), 'scheduled_end_time' => now()->addHours(2), 'privacy_status' => 'public', ]); // Create live stream $stream = YouTube::forUser(auth()->id())->createLiveStream([ 'title' => 'Stream', 'description' => 'Stream description', 'cdn' => [ 'frameRate' => '30fps', 'resolution' => '1080p', 'ingestionType' => 'rtmp', ], ]); // Bind stream to broadcast YouTube::forUser(auth()->id())->bindBroadcastToStream( $broadcast['id'], $stream['id'] );
Comments Management
// Get video comments $comments = YouTube::forUser(auth()->id())->getVideoComments('video-id', [ 'maxResults' => 100, 'order' => 'time', // time, relevance 'textFormat' => 'plainText', // plainText, html ]); // Reply to comment YouTube::forUser(auth()->id())->replyToComment('comment-id', 'Thank you for watching!'); // Moderate comments YouTube::forUser(auth()->id())->setCommentModerationStatus('comment-id', 'published'); // heldForReview, published, rejected
Analytics Integration
// Get video analytics (requires YouTube Analytics API) $analytics = YouTube::forUser(auth()->id())->getVideoAnalytics('video-id', [ 'metrics' => 'views,estimatedMinutesWatched,averageViewDuration', 'dimensions' => 'day', 'startDate' => now()->subDays(30)->format('Y-m-d'), 'endDate' => now()->format('Y-m-d'), ]);
๐งช Testing
The package includes comprehensive test coverage:
# Run all tests composer test # Run specific test suite vendor/bin/pest --filter="Upload" # Run with coverage composer test-coverage
Test categories:
- Unit tests for configuration and models
- Feature tests for services and API endpoints
- Integration tests for OAuth flow
- Upload tests including chunked uploads
- Token management and refresh tests
- Rate limiting and authentication tests
๐ง Configuration
Full configuration options in config/youtube.php:
return [ 'credentials' => [ 'client_id' => env('YOUTUBE_CLIENT_ID'), 'client_secret' => env('YOUTUBE_CLIENT_SECRET'), 'redirect_uri' => env('YOUTUBE_REDIRECT_URI', '/youtube/callback'), ], 'scopes' => [ 'https://www.googleapis.com/auth/youtube', 'https://www.googleapis.com/auth/youtube.upload', 'https://www.googleapis.com/auth/youtube.readonly', 'https://www.googleapis.com/auth/youtube.force-ssl', 'https://www.googleapis.com/auth/youtubepartner', 'https://www.googleapis.com/auth/youtubepartner-channel-audit', ], 'admin' => [ 'enabled' => env('YOUTUBE_ADMIN_ENABLED', true), 'prefix' => env('YOUTUBE_ADMIN_PREFIX', 'youtube-admin'), 'middleware' => ['web'], 'auth_middleware' => ['auth'], ], 'routes' => [ 'api' => [ 'enabled' => env('YOUTUBE_API_ENABLED', true), 'prefix' => env('YOUTUBE_API_PREFIX', 'youtube'), 'middleware' => ['api'], 'api_middleware' => ['auth:sanctum', 'throttle:60,1'], ], ], 'token' => [ 'driver' => 'database', 'table' => 'youtube_tokens', 'cache_key' => 'youtube.token.', 'cache_ttl' => env('YOUTUBE_TOKEN_CACHE_TTL', 3600), ], 'upload' => [ 'chunk_size' => env('YOUTUBE_UPLOAD_CHUNK_SIZE', 1024 * 1024), // 1MB 'timeout' => env('YOUTUBE_UPLOAD_TIMEOUT', 3600), 'max_file_size' => env('YOUTUBE_UPLOAD_MAX_SIZE', 128 * 1024 * 1024 * 1024), // 128GB 'temp_path' => env('YOUTUBE_UPLOAD_TEMP_PATH', storage_path('app/youtube-uploads')), ], 'defaults' => [ 'privacy_status' => env('YOUTUBE_DEFAULT_PRIVACY', 'private'), 'category_id' => env('YOUTUBE_DEFAULT_CATEGORY', '22'), 'language' => env('YOUTUBE_DEFAULT_LANGUAGE', 'en'), ], 'rate_limiting' => [ 'enabled' => env('YOUTUBE_RATE_LIMIT_ENABLED', true), 'max_requests_per_minute' => env('YOUTUBE_RATE_LIMIT_PER_MINUTE', 60), 'max_requests_per_hour' => env('YOUTUBE_RATE_LIMIT_PER_HOUR', 3000), ], 'logging' => [ 'enabled' => env('YOUTUBE_LOGGING_ENABLED', true), 'channel' => env('YOUTUBE_LOGGING_CHANNEL', 'youtube'), 'level' => env('YOUTUBE_LOGGING_LEVEL', 'info'), ], ];
๐ ๏ธ Console Commands
# Refresh expiring tokens php artisan youtube:refresh-tokens php artisan youtube:refresh-tokens --token-id=1 php artisan youtube:refresh-tokens --user-id=1 --force # Clean up expired tokens php artisan youtube:clear-expired-tokens php artisan youtube:clear-expired-tokens --days=30 --dry-run # Sync video statistics php artisan youtube:sync-videos php artisan youtube:sync-videos --user-id=1 php artisan youtube:sync-videos --video-id=abc123
๐ Scheduled Tasks
Add to your app/Console/Kernel.php:
protected function schedule(Schedule $schedule) { // Automatically refresh expiring tokens $schedule->command('youtube:refresh-tokens')->hourly(); // Clean up expired tokens daily $schedule->command('youtube:clear-expired-tokens')->daily(); // Sync video statistics every 6 hours $schedule->command('youtube:sync-videos')->everySixHours(); }
๐จ Error Handling
The package provides specific exception types:
use EkstreMedia\LaravelYouTube\Exceptions\{ YouTubeException, YouTubeAuthException, UploadException, TokenException, QuotaExceededException }; try { $video = YouTube::forUser($userId)->uploadVideo($file, $metadata); } catch (QuotaExceededException $e) { // Handle quota exceeded Log::error("YouTube quota exceeded: " . $e->getMessage()); // Retry after reset } catch (UploadException $e) { // Handle upload failure Log::error("Upload failed: " . $e->getMessage()); } catch (TokenException $e) { // Handle token issues return redirect()->route('youtube.auth'); } catch (YouTubeException $e) { // Handle general YouTube API errors Log::error("YouTube API error: " . $e->getYouTubeError()); }
๐ Security
- OAuth tokens are encrypted using Laravel's encryption
- CSRF protection on OAuth flow
- Rate limiting on API endpoints
- Scoped access control
- Automatic token rotation
- Secure webhook signatures
๐ Events
The package dispatches Laravel events:
// Listen for events in EventServiceProvider protected $listen = [ \EkstreMedia\LaravelYouTube\Events\VideoUploaded::class => [ \App\Listeners\ProcessUploadedVideo::class, ], \EkstreMedia\LaravelYouTube\Events\TokenRefreshed::class => [ \App\Listeners\LogTokenRefresh::class, ], \EkstreMedia\LaravelYouTube\Events\UploadFailed::class => [ \App\Listeners\NotifyUploadFailure::class, ], ];
๐ค Contributing
Please see CONTRIBUTING for details.
๐งช Testing
composer test
composer test-coverage
composer format
composer analyse
๐ Changelog
Please see CHANGELOG for more information on what has changed recently.
๐ Security
If you discover any security-related issues, please email security@ekstremedia.no instead of using the issue tracker.
๐ License
The MIT License (MIT). Please see License File for more information.
๐ฅ Credits
๐ Acknowledgments
- Thanks to Google for the YouTube Data API
- Laravel framework for the excellent foundation
- The open-source community for inspiration
๐ Support
- ๐ง Email: support@ekstremedia.no
- ๐ Issues: GitHub Issues
- ๐ฌ Discussions: GitHub Discussions
- ๐ Documentation: Full Docs
Made with โค๏ธ by Ekstre Media