Stream Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require darkanakin41/stream-bundle darkanakin41/core-bundle
   

   (Note: The core-bundle dependency must also be installed as it’s required.)

2. Configuration:

   • Publish the bundle’s config:

     php bin/console darkanakin41:core:install
     

   • Configure enabled platforms (e.g., Twitch) in config/packages/darkanakin41_stream.yaml:

     darkanakin41_stream:
         platforms:
             twitch:
                 enabled: true
                 api_key: '%env(TWITCH_API_KEY)%'
     

3. First Use Case:

   • Enable Twitch in the database via a migration or seed:

     // Example: Create a migration to seed enabled platforms
     Schema::create('stream_platforms', function (Blueprint $table) {
         $table->id();
         $table->string('name'); // e.g., 'twitch'
         $table->boolean('enabled')->default(true);
         $table->timestamps();
     });
     

   • Run the retrieval command to fetch initial streams:

     php bin/console darkanakin41:stream:retrieve
     

Implementation Patterns

Core Workflows

1. Stream Retrieval:

   • Use the retrieve command to fetch streams from enabled platforms (e.g., Twitch) based on configured categories.
   • Schedule this command via Laravel’s scheduler (e.g., * * * * * cd /path-to-project && php artisan darkanakin41:stream:retrieve).
   • Example: Fetch streams every 15 minutes for live updates.

2. Stream Refresh:

   • Run darkanakin41:stream:refresh to update existing streams (e.g., check if a stream is still live).
   • Integrate this into a cron job or Laravel task scheduler for periodic checks.

3. Platform-Specific Logic:

   • Extend the bundle for new platforms (e.g., YouTube) by creating a service implementing StreamPlatformInterface and registering it in the bundle’s configuration.
   • Example Twitch integration:

     // src/Service/TwitchStreamService.php
     class TwitchStreamService implements StreamPlatformInterface {
         public function fetchStreams(): array {
             // Use Twitch API to fetch live streams
             return $this->twitchClient->getLiveStreams();
         }
     }
     

4. Database Integration:

   • Query streams via Eloquent:

     $liveStreams = Stream::where('is_live', true)->get();
     

   • Use the bundle’s events (e.g., StreamCreated, StreamEnded) to trigger actions (e.g., notifications).

5. Event Handling:

   • Listen for StreamEnded events to clean up dead streams automatically:

     // Event subscriber
     public function onStreamEnded(StreamEnded $event) {
         $event->getStream()->delete(); // Or mark as inactive
     }
     

Gotchas and Tips

Pitfalls

1. Dependency on Core Bundle:

   • Forgetting to install darkanakin41/core-bundle will cause runtime errors. Always install both packages together.

2. API Key Management:

   • Hardcoding API keys in config files violates security best practices. Use Laravel’s .env:

     TWITCH_API_KEY=your_api_key_here
     

   • Reference the key in config/packages/darkanakin41_stream.yaml:

     api_key: '%env(TWITCH_API_KEY)%'
     

3. Rate Limiting:

   • The bundle lacks built-in rate-limiting for API calls. Implement middleware or use a library like GuzzleHttp with retry logic:

     $client = new Client([
         'timeout' => 10,
         'delay' => 200, // 200ms delay between requests
     ]);
     

4. Database Schema Assumptions:

   • The bundle assumes a stream_platforms table exists. If migrating an existing project, ensure compatibility or extend the schema:

     // Example: Custom migration for platform-specific fields
     Schema::table('stream_platforms', function (Blueprint $table) {
         $table->string('category')->nullable();
     });
     

5. Event Dispatching:

   • Events like StreamEnded may not fire if the refresh command fails silently. Add logging:

     try {
         $this->refreshStreams();
     } catch (\Exception $e) {
         \Log::error("Stream refresh failed: " . $e->getMessage());
     }
     

Tips

1. Custom Platforms:

   • To add YouTube support, create a YouTubeStreamService and register it in the bundle’s config:

     darkanakin41_stream:
         platforms:
             youtube:
                 enabled: true
                 service: App\Service\YouTubeStreamService
     

2. Testing:

   • Mock API responses in tests to avoid hitting rate limits:

     $this->mock(TwitchClient::class, function ($mock) {
         $mock->shouldReceive('getLiveStreams')->andReturn([/* mock data */]);
     });
     

3. Debugging:

   • Enable verbose output for commands:

     php bin/console darkanakin41:stream:retrieve --verbose
     

   • Check logs for API errors or missing configurations.

4. Performance:

   • Batch stream refreshes to reduce database load:

     Stream::chunk(100, function ($streams) {
         foreach ($streams as $stream) {
             $stream->refresh();
         }
     });
     

5. Extension Points:

   • Override the default stream model by binding your own implementation in services.yaml:

     services:
         App\Model\Stream:
             tags: ['darkanakin41.stream.model']