Getting Started

Minimal Steps

Installation:

composer require cloudinary/transformation-builder-sdk

Add Cloudinary credentials to .env:

CLOUDINARY_CLOUD_NAME=your_cloud_name
CLOUDINARY_API_KEY=your_api_key
CLOUDINARY_API_SECRET=your_api_secret

Basic Usage:

use Cloudinary\Transformation;
use Cloudinary\Transformation\Resize;
use Cloudinary\Transformation\Format;

$transformation = new Transformation();
$url = $transformation
    ->resize(Resize::fill()->width(300)->height(200))
    ->format(Format::auto())
    ->buildImageTag('sample.jpg');

First Use Case: Dynamically generate responsive image URLs in Blade:

<img src="{{ Cloudinary::resize(Resize::scale()->width(100))->buildImageTag($product->image) }}" alt="Product">

Where to Look First

Cloudinary PHP SDK Guide for transformation syntax.
Transformation Reference for effect/parameter details.
Laravel Service Provider pattern to centralize SDK configuration (see Implementation Patterns).

Implementation Patterns

Core Workflows

1. Transformation Presets

Define reusable transformations in a config file (config/cloudinary.php):

'presets' => [
    'thumbnail' => fn($t) => $t->resize(Resize::fill()->width(200)->height(200)),
    'social_share' => fn($t) => $t->resize(Resize::crop()->width(1200)->height(630)),
],

Use in controllers:

$transformation = app('cloudinary')->preset('thumbnail');

2. Dynamic Transformations in Blade

Create a Blade directive for concise syntax:

// app/Providers/BladeServiceProvider.php
Blade::directive('cloudinary', function ($expression) {
    return "<?php echo app('cloudinary')->{$expression}; ?>";
});

Usage:

<img src="@cloudinary(resize(Resize::fill()->width(300)->height(300))->buildImageTag($image))">

3. Video Transformations

Leverage Cloudinary’s video-specific effects (e.g., fetchFormat, overlay):

$transformation = new Transformation();
$url = $transformation
    ->video()
    ->fetchFormat(Video::mp4())
    ->overlay(Video::source('logo.mp4')->gravity(Gravity::southEast)->width(100))
    ->buildImageTag('video.mp4');

4. AI-Powered Effects

Use generative or background removal:

$transformation = new Transformation();
$url = $transformation
    ->effect(Effect::backgroundRemoval())
    ->format(Format::webp())
    ->buildImageTag('ugc_image.jpg');

Integration Tips

Laravel Service Container

Bind the SDK as a singleton in AppServiceProvider:

public function register() {
    $this->app->singleton('cloudinary', function () {
        return new Transformation();
    });
}

Artisan Commands

Generate transformation URLs via CLI:

// app/Console/Commands/GenerateTransformations.php
public function handle() {
    $transformation = app('cloudinary');
    $url = $transformation->resize(Resize::scale()->width(800))->buildImageTag('hero.jpg');
    $this->info("Generated URL: {$url}");
}

Eloquent Relationships

Attach transformations to model attributes:

// User.php
public function getAvatarUrlAttribute() {
    return app('cloudinary')
        ->resize(Resize::circle()->radius(100))
        ->gravity(Gravity::face())
        ->buildImageTag($this->avatar);
}

Caching Transformed URLs

Cache transformation URLs in Laravel’s cache:

$cacheKey = "cloudinary_transform_{$image}_{$width}x{$height}";
$url = Cache::remember($cacheKey, now()->addHours(1), function () use ($image, $width, $height) {
    return app('cloudinary')
        ->resize(Resize::scale()->width($width)->height($height))
        ->buildImageTag($image);
});

Signed URLs for Private Assets

Generate signed URLs for secure delivery:

use Cloudinary\Api\ApiResponse;
use Cloudinary\Configuration\Configuration;

$transformation = new Transformation();
$url = $transformation
    ->resize(Resize::fill()->width(500))
    ->buildImageTag('private_image.jpg', [
        'type' => 'authenticated',
        'expiration' => time() + 3600,
    ]);

Gotchas and Tips

Pitfalls

PHP Version Mismatch:
- Issue: SDK 2.x requires PHP 8.0+. Using 1.x with PHP 8.4+ may trigger deprecation warnings.
- Fix: Pin version in composer.json:
```
"require": {
    "cloudinary/transformation-builder-sdk": "^2.1"
}
```
Transformation Order:
- Issue: Effects like gravity must precede resize; otherwise, they’re ignored.
- Fix: Chain methods logically:
```
// Correct: gravity before resize
$transformation->gravity(Gravity::face())->resize(Resize::fill()->width(200));
```
AI Effect Limitations:
- Issue: Generative effects (e.g., generativeFill) require Cloudinary’s AI add-on and may incur additional costs.
- Fix: Check Cloudinary’s pricing and enable the add-on in the dashboard.
Video Transformation Quirks:
- Issue: Not all image effects apply to videos (e.g., blurFaces works only on images).
- Fix: Use video() method explicitly:
```
$transformation->video()->effect(Effect::blurFaces());
```
URL Encoding:
- Issue: Custom parameters (e.g., flags) must be URL-encoded manually.
- Fix: Use Laravel’s Str::of():
```
$transformation->addParam('flags', Str::of('lossless')->replace(' ', '%20'));
```
Deprecated Parameters:
- Issue: Cloudinary may deprecate parameters (e.g., crop in favor of resize).
- Fix: Monitor Cloudinary’s release notes and update SDK usage.

Debugging

Invalid Transformation Strings:
- Debug: Use buildUrl() to inspect the raw transformation string:
```
$url = $transformation->buildUrl('image.jpg');
// Output: https://res.cloudinary.com/demo/image/upload/w_300,h_200/c_fill...
```
- Tool: Validate strings using Cloudinary’s URL API.

Performance Bottlenecks:

Debug: Complex chains (e.g., nested overlays) may slow response times. Test with:

$start = microtime(true);
$url = $transformation->complexChain()->buildUrl('image.jpg');
$time = microtime(true) - $start;

Caching Issues:
- Debug: Clear Laravel’s cache and Cloudinary’s transformation cache:
```
php artisan cache:clear
```
  In Cloudinary dashboard: Settings > Transformation Cache > Clear Cache.

Extension Points

Custom Effects: Extend the SDK by creating a custom effect class:

use Cloudinary\Transformation\Effect;

class CustomEffect extends Effect {
    public function __construct() {
        parent::__construct('custom', 'value');
    }
}