Imagine Bundle Laravel Package

Getting Started

• Install with Composer and publish the package config (php artisan vendor:publish --provider=...); confirm the service provider is auto-discovered.
• Read first: the package README, the published config file (filter sets, resolvers, loaders), and the package's route/controller registration.
• Define one filter set first — e.g. a thumb set with a 300×300 outbound thumbnail and quality 80 — rather than modelling every image size up front.
• First use case: upload an original to storage/app/public/uploads, serve a cached derivative through the package's filter route, and render the resulting URL in a Blade view.
• Verify the basics before integrating: GD or Imagick is installed, storage is writable/linked, and the cache route responds for a known image.

Implementation Patterns

• Treat filter sets as named design tokens (avatar, card, hero) in config. Reference names in controllers and Blade templates, not dimensions.
• On-demand derivative route: accept image path and filter name, validate both against configured allow-lists, let the package resolve/generate the cached file, and return it with long-lived cache headers.
• URL helper pattern: wrap the cache manager in a small helper/service (image_url($path, 'card')) instead of hard-coding /media/cache/... paths in views.
• Upload pipeline: store the original untouched, validate MIME/size, then either generate derivatives immediately or defer to a queued job that warms expected sizes.
• Deploy pipeline: run the package's cache-warm command for critical filter sets after release, and clear derivatives when source files are replaced in place.
• Integration tips: point the data loader at Laravel's public disk/storage path; point the cache resolver at a separate public cache directory or CDN-backed filesystem; keep originals and derivatives in separate directories.
• For cloud storage, use the package's stream/loader integration and generate absolute URLs through the configured resolver rather than local paths.
• Custom filters: register through config/service provider when built-in thumbnail, crop, or resize filters do not cover art-directed crops or watermarking.

Gotchas and Tips

• Filter set changes are not automatically reflected in already-cached files. Clear/rebuild the image cache after changing dimensions, quality, or filters.
• Never pass a raw user-supplied path or filter name into the generation route. Validate against configured filter sets and normalise paths to prevent traversal and cache poisoning.
• Same filename plus changed contents equals a stale derivative. Version filenames, use content hashes, or explicitly invalidate the derivative.
• GD and Imagick produce different results, especially for CMYK, EXIF orientation, and quality. Pick one driver per environment and test image parity.
• Runtime generation is the usual performance trap: the first request for each size is slow and memory-hungry. Warm common sizes on deploy and cap source image dimensions.
• Permissions and paths are the most common setup failure: the cache directory must be writable by the web user, and the source root must resolve exactly as configured.
• Check driver availability and memory limits first when generation silently fails; then inspect the cache directory for partial files and application logs for resolver/loader errors.
• Extension points worth knowing: custom filters, data loaders (S3/other disks), cache resolvers, and post-processors. Prefer these over patching vendor code, especially on a fork.
• This 3.0.1 release is a fork of LiipImagineBundle 2.3.1. Upstream docs and examples remain useful, but confirm class names, config keys, and console commands against this package's own README — fork-specific Laravel integration may differ.