Getting Started

Minimal Setup

Install the package:
```
composer require axn/laravel-glide
```

Publish configuration and generate signing key:

php artisan vendor:publish --tag="glide-config"
php artisan glide:key-generate

Configure config/glide.php: Define at least one server (e.g., images) with source (disk for originals) and cache (disk for processed images). Example:

'servers' => [
    'images' => [
        'source' => 'public',
        'cache' => 'public/glide-cache',
        'driver' => env('GLIDE_IMAGE_DRIVER', 'gd'),
        'signatures' => true,
        'sign_key' => env('GLIDE_SIGN_KEY'),
        'base_url' => env('APP_URL'),
    ],
],

First use case: Generate a signed URL for an image in a controller:

use Axn\LaravelGlide\Facades\Glide;

return Glide::url('path/to/image.jpg', ['w' => 300, 'h' => 200]);

Or return an image response directly:

return Glide::imageResponse('path/to/image.jpg', ['w' => 300]);

Where to Look First

Configuration: config/glide.php and config/glide_servers/*.php for server-specific settings.
Facade: Axn\LaravelGlide\Facades\Glide for quick usage in controllers/blade.
Presets: Define reusable transformations in the server config (e.g., presets.small = ['w' => 100, 'h' => 100]).
Artisan Commands: glide:key-generate for managing signing keys.

Implementation Patterns

Core Workflows

1. Dynamic Image URLs

Use the facade to generate URLs with transformations:

// Basic resize
$url = Glide::url('product.jpg', ['w' => 400]);

// Crop to fit
$url = Glide::url('avatar.png', ['w' => 150, 'h' => 150, 'fit' => 'crop']);

// Use a preset
$url = Glide::url('banner.jpg', ['p' => 'large']);

Blade Integration:

<img src="{{ Glide::url('image.jpg', ['w' => 200]) }}">

2. Multi-Server Routing

Switch between servers (e.g., images vs. avatars) for isolated configurations:

// Default server
Glide::url('photo.jpg', ['w' => 300]);

// Specific server
Glide::server('avatars')->url('user.jpg', ['w' => 100, 'fit' => 'crop']);

3. Image Responses

Return processed images directly in API/controllers:

// Return as image response (e.g., for API endpoints)
return Glide::imageResponse('document.pdf', ['w' => 800]);

// Return as Base64 (e.g., for email attachments)
$base64 = Glide::imageAsBase64('logo.png', ['w' => 200]);

4. Watermarking

Configure watermarks in glide_servers/*.php:

'watermarks' => [
    'disk' => 'watermarks',
    'images' => ['logo.png'],
    'position' => 'bottom-right',
    'opacity' => 50,
],

Apply in URLs:

$url = Glide::url('background.jpg', ['w' => 1024, 'watermark' => 'logo.png']);

5. Signed URLs

Enable signatures: true in server config and set GLIDE_SIGN_KEY in .env. URLs will include a signature query parameter:

/glide/abc123.jpg?w=300&sig=abc123...

Integration Tips

Storage Optimization

Use fast disks for cache (e.g., s3, local with SSD) to avoid bottlenecks.
For high traffic, consider CDN caching (e.g., Cloudflare) in front of Glide URLs.

Presets for Reusability

Define presets in glide_servers/*.php to avoid repeating transformations:

'presets' => [
    'small' => ['w' => 100, 'h' => 100, 'fit' => 'crop'],
    'thumbnail' => ['w' => 150, 'h' => 150, 'fit' => 'inside'],
    'watermarked' => ['w' => 800, 'watermark' => 'logo.png'],
],

Use in URLs:

Glide::url('image.jpg', ['p' => 'small']);

Middleware for Conditional Processing

Create middleware to enable/disable Glide based on routes or user roles:

public function handle(Request $request, Closure $next) {
    if (auth()->check() && auth()->user()->is_premium) {
        $request->merge(['watermark' => null]); // Disable watermark for premium users
    }
    return $next($request);
}

Testing

Unit Tests: Mock the GlideServer to test URL generation:

$server = $this->app->make('glide.server.images');
$url = $server->getUrl('test.jpg', ['w' => 100]);
$this->assertStringContainsString('w=100', $url);

Feature Tests: Test image responses with Http::fake() or browser tests:

$response = $this->get('/glide/image.jpg?w=200');
$response->assertHeader('Content-Type', 'image/jpeg');

Performance Tuning

Driver Choice: Benchmark gd vs. imagick for your workload. Imagick is faster but requires installation.
Max Image Size: Set max_image_size in server config to avoid processing overly large images:
```
'max_image_size' => [2000, 2000], // Width x Height
```
Cache Invalidation: Clear Glide cache when original images change:
```
php artisan storage:link  # Ensure symlinks are up-to-date
```

Gotchas and Tips

Pitfalls

Missing PHP Extensions:
- Error: Class 'GdImage' not found or ImagickException.
- Fix: Install gd or imagick via pecl or package manager (e.g., sudo apt-get install php8.4-imagick).
Incorrect Disk Configuration:
- Error: League\Flysystem\FileNotFoundException or empty responses.
- Fix: Verify source and cache disks exist and are accessible. Use php artisan storage:link for local disks.
Signed URL Mismatches:
- Error: InvalidSignatureException when accessing signed URLs.
- Fix:
  - Ensure GLIDE_SIGN_KEY matches the key in glide_servers/*.php.
  - Regenerate the key if compromised: php artisan glide:key-generate.
  - Check URL encoding (e.g., spaces in paths may break signatures).
Watermark Path Issues:
- Error: Watermark not applied or FileNotFoundException.
- Fix: Ensure watermark files are stored in the configured watermarks.disk and paths are correct (e.g., watermarks/logo.png).
Facade Not Found:
- Error: Class 'Glide' not found after installation.
- Fix: Register the service provider in config/app.php:
```
'providers' => [
    Axn\LaravelGlide\GlideServiceProvider::class,
],
```
Preset Not Found:
- Error: InvalidArgumentException for undefined presets.
- Fix: Define presets in glide_servers/*.php and use the correct name (case-sensitive).
CORS Issues:
- Error: Images blocked by CORS when accessed from a different domain.
- Fix: Configure CORS headers for your Glide server (e.g., Nginx/Apache) or use a CDN.

Debugging Tips

Enable Glide Logging: Add to config/glide.php:
```
'
```

Laravel Glide Laravel Package