Getting Started

Minimal Setup

Installation

composer require eur-rsm/laravel-bynder

Publish the config file:

php artisan vendor:publish --provider="EurRsm\LaravelBynder\BynderServiceProvider"

Configuration Edit .env with Bynder API credentials:

BYNDER_CLIENT_ID=your_client_id
BYNDER_CLIENT_SECRET=your_client_secret
BYNDER_REDIRECT_URI=http://your-app.test/callback
BYNDER_BASE_URL=https://your-bynder-instance.bynder.net

First Use Case: Authentication Redirect users to Bynder for OAuth:

use EurRsm\LaravelBynder\Facades\Bynder;

// Redirect to Bynder auth
return Bynder::auth()->redirect();

// Handle callback (in a route)
$token = Bynder::auth()->handleCallback();

Verify Installation Check if the package is connected:

if (Bynder::auth()->check()) {
    $user = Bynder::auth()->user();
    dd($user); // Should return Bynder user data
}

Implementation Patterns

Common Workflows

1. Asset Management

Uploading Assets

$asset = Bynder::assets()->create([
    'name' => 'Project Logo',
    'file' => fopen('logo.png', 'r'),
    'folder_id' => 123,
]);

Fetching Assets

$assets = Bynder::assets()->all(['folder_id' => 123]);
$asset = Bynder::assets()->find(456);

Downloading Assets

$file = Bynder::assets()->download(456, 'local_path/logo.png');

2. Folder Structure

Create/Update Folders

$folder = Bynder::folders()->create([
    'name' => 'Marketing Assets',
    'parent_id' => 123,
]);

Recursive Folder Listing

$folders = Bynder::folders()->all(['recursive' => true]);

3. Searching Assets

Basic Search

$results = Bynder::search()->assets([
    'q' => 'logo',
    'limit' => 10,
]);

Advanced Filters

$results = Bynder::search()->assets([
    'q' => 'brochure',
    'folder_id' => 123,
    'sort' => '-modified',
]);

4. Integration with Laravel Models

Attach Assets to Eloquent Models

// In a model
public function assets()
{
    return $this->morphToMany(Asset::class, 'model');
}

// Sync assets
$post->assets()->sync([123, 456]);

Policy-Based Access

// In a policy
public function viewAny(User $user)
{
    return Bynder::auth()->check() && $user->can('view_bynder_assets');
}

5. Webhooks (Advanced)

Register a Webhook Listener

// In EventServiceProvider
Bynder::webhooks()->listen('asset.created', function ($payload) {
    // Handle new asset creation
});

Integration Tips

Caching Responses Use Laravel’s cache to reduce API calls:

$assets = Cache::remember('bynder_assets_123', now()->addHours(1), function () {
    return Bynder::assets()->all(['folder_id' => 123]);
});

Queue Long-Running Tasks Offload heavy operations (e.g., bulk uploads) to queues:
```
UploadAssetJob::dispatch($file, $folderId)->onQueue('bynder');
```
Laravel Mix/Valet/Forge For local development, use .env overrides:
```
BYNDER_BASE_URL=http://bynder.test
```

Testing Use mocks in PHPUnit:

Bynder::shouldReceive('assets()->all')->andReturn([$mockAsset]);

Gotchas and Tips

Pitfalls

OAuth Flow Issues
- Problem: Redirect URI mismatch or invalid credentials.
- Fix: Double-check BYNDER_REDIRECT_URI in .env and Bynder’s app settings.
- Debug: Enable logging in config/bynder.php:
```
'debug' => env('BYNDER_DEBUG', false),
```
Rate Limiting
- Problem: Bynder may throttle requests (e.g., 60 calls/minute).
- Fix: Implement exponential backoff or cache aggressively.
- Tip: Use Bynder::throttle() middleware for routes:
```
Route::middleware(['throttle:bynder'])->group(function () {
    // Bynder-heavy routes
});
```
File Size Limits
- Problem: Large files may fail silently.
- Fix: Validate file sizes before upload:
```
$request->validate([
    'file' => 'max:10240', // 10MB
]);
```
Folder Permissions
- Problem: 403 Forbidden when accessing folders.
- Fix: Ensure the authenticated user has permissions in Bynder’s UI.
Webhook Delays
- Problem: Webhooks may arrive out of order or be delayed.
- Fix: Use idempotency_keys in payloads to avoid duplicate processing.

Debugging

Enable Verbose Logging

// In config/bynder.php
'log' => [
    'enabled' => true,
    'path' => storage_path('logs/bynder.log'),
],

Inspect Raw API Responses

$response = Bynder::assets()->all();
dd($response->getRawResponse());

Common HTTP Errors
- 401 Unauthorized: Token expired. Refresh with Bynder::auth()->refresh().
- 404 Not Found: Check IDs/folder paths for typos.
- 500 Server Error: Contact Bynder support or check their status page.

Extension Points

Custom API Endpoints Extend the client for unsupported endpoints:

// In a service provider
Bynder::extend(function ($client) {
    $client->custom = new CustomEndpoint($client);
});

// Usage
Bynder::custom()->fetchData();

Event Dispatching Trigger Laravel events on Bynder actions:

Bynder::assets()->onCreate(function ($asset) {
    event(new AssetUploaded($asset));
});

Middleware for Auth Protect routes requiring Bynder auth:

Route::middleware(['bynder.auth'])->group(function () {
    // Protected routes
});

Service Provider Overrides Bind custom implementations:

$this->app->bind('bynder', function () {
    return new CustomBynderClient();
});

Configuration Quirks

Base URL Handling
- Ensure BYNDER_BASE_URL includes the protocol (https://) and no trailing slash.
- Example: https://company.bynder.net (not /).

Timeouts

Increase timeout for large operations:

'http' => [
    'timeout' => 60, // seconds
],

Default Folder ID
- Set a default folder for uploads in config/bynder.php:
```
'defaults' => [
    'folder_id' => 123,
],
```

Environment-Specific Settings Use Laravel’s config/bynder.php to override per environment:

'environments' => [
    'local' => [
        'base_url' => 'http://bynder.test',
    ],
],

Laravel Bynder Laravel Package