Soundcloudbundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require cekurte/soundcloudbundle
   

   Register the bundle in config/bundles.php (Symfony):

   return [
       // ...
       Cekurte\SoundCloudBundle\CekurteSoundCloudBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php artisan vendor:publish --provider="Cekurte\SoundCloudBundle\CekurteSoundCloudBundle" --tag=config
   

   Update config/soundcloud.php with your client ID and client secret (register an app at SoundCloud Developer).

3. First Use Case: Fetch Tracks Inject the SoundCloudService into a controller or service:

   use Cekurte\SoundCloudBundle\Service\SoundCloudService;
   
   public function __construct(private SoundCloudService $soundcloud)
   {
   }
   
   public function searchTracks()
   {
       $tracks = $this->soundcloud->search('radiohead', 'track');
       return view('tracks', ['tracks' => $tracks]);
   }
   

Implementation Patterns

Core Workflows

1. Searching Content Use the search() method for tracks, playlists, or users:

   $this->soundcloud->search('artist_name', 'track', ['limit' => 10]);
   

   • Parameters: Pass an associative array for advanced queries (e.g., filter, duration, genre).

2. User Management Authenticate users via OAuth2 (if needed) and fetch profiles:

   $user = $this->soundcloud->getUserById(12345);
   $user->getTracks(); // Assuming a method exists for related data.
   

3. Uploading Tracks For uploads, use the upload() method (if supported):

   $track = $this->soundcloud->upload(
       '/path/to/file.mp3',
       ['title' => 'My Track', 'description' => 'Demo']
   );
   

4. Event Listeners Subscribe to SoundCloud webhooks (e.g., track uploads) via the WebhookManager:

   $this->soundcloud->webhook()->subscribe(
       'https://your-app.com/soundcloud/webhook',
       ['track:upload']
   );
   

Integration Tips

• Caching: Cache API responses (e.g., search() results) using Laravel’s cache:

  $cacheKey = "soundcloud:tracks:{$query}";
  return Cache::remember($cacheKey, now()->addHours(1), function () use ($query) {
      return $this->soundcloud->search($query, 'track');
  });
  

• Rate Limiting: SoundCloud enforces rate limits. Implement exponential backoff for retries:

  try {
      $result = $this->soundcloud->search(...);
  } catch (\Cekurte\SoundCloudBundle\Exception\RateLimitException $e) {
      sleep($e->getRetryAfter());
      return $this->searchTracks();
  }
  

• Laravel Scout: Index SoundCloud tracks in Laravel Scout for full-text search:

  Scout::search('radiohead')->get();
  

Gotchas and Tips

Pitfalls

1. Deprecated Methods The bundle may not support SoundCloud’s latest API endpoints (e.g., /resolve for track IDs). Check the SoundCloud API docs for breaking changes.

   • Workaround: Extend the SoundCloudService to override deprecated methods:

     class CustomSoundCloudService extends \Cekurte\SoundCloudBundle\Service\SoundCloudService
     {
         public function resolve($id)
         {
             return $this->client->get("/resolve?url={$id}");
         }
     }
     

2. OAuth2 Flow The bundle lacks built-in OAuth2 flow handling. Manually implement authorization:

   $authUrl = $this->soundcloud->getAuthUrl(['scope' => 'non-expiring']);
   // Redirect user to $authUrl, then exchange code for token.
   

3. Error Handling The bundle may not throw specific exceptions for all API errors. Wrap calls in try-catch:

   try {
       $this->soundcloud->search('invalid_query');
   } catch (\GuzzleHttp\Exception\RequestException $e) {
       $response = json_decode($e->getResponse()->getBody(), true);
       // Handle SoundCloud errors (e.g., $response['error']).
   }
   

4. Configuration Overrides The soundcloud.php config may not support all API options. Extend the config publisher:

   // config/soundcloud.php
   return [
       'api_version' => '2.0', // Explicitly set if needed.
       'default_params' => [
           'client_id' => env('SOUNDCLOUD_CLIENT_ID'),
           'format' => 'json',
       ],
   ];
   

Debugging Tips

• Enable Guzzle Middleware: Add a logging middleware to inspect API requests:

  $this->soundcloud->getClient()->getEmitter()->attach(
      new \GuzzleHttp\Middleware::tap(function ($request) {
          \Log::debug('SoundCloud Request:', [
              'url' => (string) $request->getUri(),
              'method' => $request->getMethod(),
              'body' => $request->getBody() ? $request->getBody()->getContents() : null,
          ]);
      })
  );
  

• API Explorer: Use SoundCloud’s API Console to test endpoints before integrating.

Extension Points

1. Custom Endpoints Extend SoundCloudService to add unsupported endpoints:

   public function getChart($period = '7day')
   {
       return $this->client->get("/charts?period={$period}");
   }
   

2. Model Bindings Create Eloquent models to bind SoundCloud responses:

   class SoundCloudTrack extends Model
   {
       protected $fillable = ['id', 'title', 'duration', 'created_at'];
   
       public static function fromSoundCloud(array $data)
       {
           return self::create([
               'id' => $data['id'],
               'title' => $data['title'],
               // ...
           ]);
       }
   }
   

3. Service Container Bind a custom service to override the default:

   $this->app->bind(SoundCloudService::class, function ($app) {
       return new CustomSoundCloudService($app['http.client']);
   });