Laramedias Laravel Package

Getting Started

Install with Composer and publish the config:

composer require escapework/laramedias
php artisan vendor:publish --provider="Escapework\Laramedias\LaramediasServiceProvider"

The first file to read is config/laramedias.php. It defines the disks/adapters this package hands to Glide:

• source — the filesystem disk where the original images live (usually public or a media disk you create).
• cache — the disk where Glide writes derived/processed images. Use a separate disk so you can purge it safely.
• driver — gd (ships with PHP, safe default) or imagick (better quality/format support but must be installed).
• route / path_prefix — the URI prefix used to serve processed images.

The second thing to look at is the Mediable trait (usually Escapework\Laramedias\Mediable or similar) that you add to an Eloquent model representing your media. A typical first model looks like:

use Escapework\Laramedias\Mediable;

class Photo extends Model
{
    use Mediable;
}

Run migrations if the package publishes any, then verify your storage symlink exists (php artisan storage:link) and that your source disk is publicly reachable. Upload a single image to that disk, build a URL that passes Glide parameters through the trait’s URL helper / the route, and confirm two things: the original renders and a resized variant (?w=300&filt=greyscale) renders and caches.

Your first real use case: serve responsive product/thumbnail images from a single original — w, h, fit=crop, q, and fm=webp query params, letting Glide handle the resizing on first request.

Implementation Patterns

Per-model media definitions. Keep the media columns (or accessor) on the model rather than in a service. Use the trait so URL generation lives next to the record. Expose a small method:

public function thumbUrl(int $w = 300): string
{
    return $this->mediaUrl(['w' => $w, 'h' => $w, 'fit' => 'crop']);
}

Views then call $photo->thumbUrl() — no controller needed for each variant.

URL as the API. Glide is parameter-driven (w, h, fit, fm, q, filt, bg, mark, etc.). Treat query strings as your transformation contract. If you have repeated variants (thumbnail, hero, og-image), centralize them in a config array or a small ImageVariants class so view code never guesses. This also lets you pre-warm or invalidate by variant.

Signed URLs for anything non-public. Glide ships an HTTP signature feature. Configure a signing key in config/laramedias.php and generate signed links for private media. Serve unsigned URLs only for content you actually want world-readable. Signing prevents users from forcing arbitrary crop/size combinations (an easy DoS via cache flooding).

Driver selection. Use gd in CI and local dev for consistency; switch to imagick in production if you need WebP/AVIF quality or CMYK handling. Set the driver per-environment via env var so behavior matches.

Cache disk as a first-class citizen. Point cache at a disk with a lifecycle policy (S3 lifecycle rule, or a scheduled cache:clear). Do not co-locate the Glide cache with originals — you want to purge derived files independently. For S3 origins, Glide can often stream directly from S3 using its Flysystem adapter, so you never copy originals to the web server.

Upload workflow. Handle uploads with a StoreMedia action that validates MIME, normalizes the extension, generates a content-hashed filename (so URLs are immutable and cache-friendly), and writes to the source disk. Then the model row just stores the path/filename. Immutable filenames mean you rarely need to purge the cache.

Integration tips.

• Serve variants through a route middleware group that adds cache headers (Cache-Control: public, max-age=31536000, immutable).
• Behind a load balancer, ensure the Glide cache directory/disk is shared across instances — otherwise each node caches separately.
• For Blade, wrap variants in a component (<x-image :src="..." variant="thumb" />) so the URL logic is in one place.
• Eager-load media relations if you list many records to avoid N+1 when generating URLs.

Gotchas and Tips

Cache invalidation is manual. If you overwrite an original at the same path, stale derivatives stay cached. The fix is content-hashed filenames (preferred) or explicitly deleting the derivative on update. Plan for this from the start.

Filesystem paths vs URLs. The trait/disk config expects paths relative to the disk root; passing an absolute URL or a leading slash is a common silent-failure source. Store paths like photos/abc123.jpg, not https://.../photos/abc123.jpg, and not /storage/photos/abc123.jpg.

Permissions. Both the source and cache disks need to be writable by the PHP user. If Glide cannot write the cache, you’ll get 500s on first request only (the original will look fine). Set storage/logs and cache ownership explicitly in container images.

GD ≠ Imagick. Some Glide parameters behave differently or silently no-op depending on driver (e.g., certain filt filters, AVIF). Test the exact transformation matrix you rely on in the target driver. If you switch drivers in production, purge the cache — derivatives are driver-specific.

Security: don’t trust user params. Allowing arbitrary w/h on public URLs lets clients spawn millions of derivatives. Either restrict params server-side (whitelist width/height buckets) or sign every URL. Also cap w/h and reject w=99999.

Memory. Large originals + Imagick can blow past memory_limit on big uploads. Consider downscaling on upload to a "max original" (e.g., 4000px) so Glide never processes enormous files.

Route ordering. The package registers a route for its path prefix. If you have a catch-all or your own /{any} route, it may shadow Glide’s route — verify with php artisan route:list that the media route resolves before your fallbacks.

Debugging. Enable Laravel’s debug and check the laramedias log channel; most failures are disk misconfiguration or missing driver extensions. Use php artisan tinker to call the URL helper directly — that separates routing problems from transformation problems. Hit a URL with a single minimal param (?w=100) first, then add params one at a time to isolate the culprit.

Extension points. The package is small (few stars/maintainers) — treat it as a thin wrapper. If you need custom adapters, response modification, or middleware, wrap Glide’s ServerFactory yourself rather than fighting the package. Fork or bind a custom implementation in a service provider if you need signed URLs or S3 streaming; the underlying league/glide API is what you’ll be learning, not the package.

Staying current. With a low star count, don’t assume active maintenance. Pin the version and, when Laravel majors change, verify the service provider binding and config structure still load. Keeping your transformation logic in application code (not in package internals) makes an eventual swap to league/glide directly, or to spatie/laravel-medialibrary, a low-cost operation.