Bynder Php Sdk Laravel Package

Getting Started

First Steps

1. Check the PHP requirement first (changed in 2.2.8) Since v2.2.8 the SDK requires PHP 8.2+ (it was 8.1 before) and is CI-tested against PHP 8.5. Before installing, verify your runtime:

   php -v          # must be 8.2.x or higher
   composer check-platform-reqs
   

   Practical impact for Laravel apps:

   • Laravel 11/12 already require PHP 8.2+, so nothing to do.
   • Laravel 9/10 projects still pinned to PHP 8.1 must upgrade PHP (or stay on bynder/bynder-php-sdk:2.2.7).
   • If you run an older platform in CI or Docker, pin it before bumping: "bynder/bynder-php-sdk": "2.2.7" until the image is updated.

2. Installation Add the SDK via Composer:

   composer require bynder/bynder-php-sdk
   

   Confirm the resolved version is 2.2.8 (composer show bynder/bynder-php-sdk) and that the package is autoloaded in composer.json under autoload.psr-4.

3. Configuration Create a .env entry for Bynder credentials:

   BYNDER_CLIENT_ID=your_client_id
   BYNDER_CLIENT_SECRET=your_client_secret
   BYNDER_REDIRECT_URI=http://your-app.dev/bynder/callback
   BYNDER_BASE_URL=https://api.bynder.com/v2
   

4. First Use Case: OAuth Authentication Initialize the client in a Laravel service:

   use Bynder\BynderClient;
   
   $client = new BynderClient(
       config('bynder.client_id'),
       config('bynder.client_secret'),
       config('bynder.redirect_uri'),
       config('bynder.base_url')
   );
   

   Redirect users to Bynder for auth:

   return redirect()->to($client->getAuthorizationUrl());
   

   Handle the callback in a route:

   Route::get('/bynder/callback', function () {
       $client = app(BynderClient::class);
       $token = $client->handleAuthorizationCallback(request()->query('code'));
       session(['bynder_token' => $token]);
   });
   

Implementation Patterns

Common Workflows

1. Asset Management

   • Uploading Assets:

     $asset = $client->assets()->upload(
         file_get_contents('path/to/file.jpg'),
         'image/jpeg',
         ['name' => 'example.jpg', 'description' => 'Test upload']
     );
     

   • Fetching Assets:

     $assets = $client->assets()->getAll(['limit' => 10]);
     foreach ($assets as $asset) {
         $downloadUrl = $client->assets()->getDownloadUrl($asset['id']);
     }
     

2. Collections

   • Create/update collections:

     $collection = $client->collections()->create([
         'name' => 'Project Assets',
         'description' => 'Assets for Project X'
     ]);
     

   • Add assets to collections:

     $client->collections()->addAssets($collection['id'], [$assetId1, $assetId2]);
     

3. Webhooks

   • Register a webhook endpoint in Laravel:

     Route::post('/bynder/webhook', function (Request $request) {
         $client->webhooks()->verifySignature($request->header('X-Bynder-Signature'), $request->getContent());
         // Process payload
     });
     

4. Integration with Laravel Storage

   • Use the SDK to proxy downloads to Laravel’s filesystem:

     $assetData = $client->assets()->download($assetId);
     Storage::disk('bynder')->put($assetId, $assetData);
     

Best Practices

• Token Management: Store tokens in the database (e.g., oauth_tokens table) with TTL handling.
• Rate Limiting: Implement middleware to respect Bynder’s rate limits.
• Error Handling: Wrap SDK calls in try-catch blocks:

  try {
      $asset = $client->assets()->upload(...);
  } catch (BynderException $e) {
      Log::error("Bynder upload failed: " . $e->getMessage());
      throw new \Exception("Failed to upload asset", 0, $e);
  }
  

• Keep the runtime current: the library now tracks PHP 8.5 in CI, so treat your PHP minor version as part of the dependency surface. Run the test suite on the same PHP version your production image uses.

Gotchas and Tips

Pitfalls

1. PHP 8.1 support dropped in 2.2.8

   • Composer will refuse to install on PHP 8.1 (Your requirements could not be resolved ... requires php >=8.2). If you see this on a machine that "used to work", it's the platform, not the package.
   • Common trip-ups: CI matrices still on 8.1, Docker base images (php:8.1-fpm), Laravel Sail/Homestead VMs, and config.platform.php in composer.json pinning 8.1 in production builds. Update all four or pin 2.2.7 deliberately.
   • Because the bump is a minor release, composer update will pick it up without a warning — a routine composer update can break a deploy. Lock step your PHP upgrade and the SDK bump in the same PR.
   • Any dev dependency still requiring <8.2 (old PHPUnit, PHPStan, or a stalled transitive package) will now block the resolver; upgrade tooling alongside.

2. OAuth Flow Quirks

   • Redirect URI Mismatch: Ensure the redirect_uri in the SDK matches the one registered in Bynder’s developer portal. Mismatches result in invalid_redirect_uri errors.
   • State Parameter: Always include a state parameter in the auth URL to prevent CSRF. Use Laravel’s csrf_token():

     $authUrl = $client->getAuthorizationUrl(['state' => csrf_token()]);
     

3. Token Expiry

   • Tokens expire after 30 days (default). Implement a refreshToken() call before expiry or use a job queue to refresh tokens proactively.
   • Store the refresh_token alongside the access token for silent refreshes.

4. API Versioning

   • The SDK defaults to v2 of the Bynder API. If migrating to v3, update the base_url in config and handle breaking changes (e.g., endpoint paths like /assets → /v3/assets).

5. File Size Limits

   • Bynder enforces a 5GB upload limit. For larger files, use chunked uploads or Bynder’s presigned URLs.

Debugging Tips

• Enable Verbose Logging:

  $client = new BynderClient(..., ..., ..., [
      'logger' => function ($message) {
          Log::debug('Bynder SDK: ' . $message);
      }
  ]);
  

• Inspect Raw Responses: The SDK throws BynderException with raw responses. Log the $e->getResponse() property for debugging.
• Version mismatch hunting: when behaviour differs between environments after the 2.2.8 bump, run composer show bynder/bynder-php-sdk on each box — mixed 2.2.7/2.2.8 across app, queue workers, and scheduled jobs is the usual culprit.

Extension Points

1. Custom HTTP Client Override the default Guzzle client for retries or middleware:

   $client = new BynderClient(..., ..., ..., [
       'http_client' => new \GuzzleHttp\Client([
           'timeout' => 30,
           'headers' => ['User-Agent' => 'MyApp/1.0']
       ])
   ]);
   

2. Event Dispatching Trigger Laravel events for SDK actions (e.g., asset.uploaded):

   $client->assets()->upload(..., function ($asset) {
       event(new AssetUploaded($asset));
   });
   

3. Local Testing Use Bynder’s sandbox environment with mock credentials. Override the base_url in config:

   BYNDER_BASE_URL=https://sandbox.bynder.com/v2
   

4. Wrap the client once Bind BynderClient as a singleton in a service provider and inject it everywhere. That gives you a single place to swap in a fake, change the HTTP client, or pin behaviour when the next runtime bump lands.