Laravel Imageforge Laravel Package

Getting Started

laravel-imageforge is a Blade-friendly image manipulation package: you point it at a source image, describe the transform (resize/crop/format), and it returns a URL to a cached, generated derivative.

1. Install and publish:

   composer require replworks/laravel-imageforge
   php artisan vendor:publish --tag="imageforge-config"
   

2. Check the generated config/imageforge.php first — it defines the source disk, the cache/output disk, the default driver (GD vs Imagick) and the URL prefix used to serve derivatives. Most "it doesn't work" reports are disk/path misconfiguration here.
3. Make sure the public disk is reachable (php artisan storage:link) if derivatives are written to public.
4. First use case — the common one: a list/detail page that needs a thumbnail rather than the multi-megabyte original. Drop the directive into a Blade template with a source path and the transform you want; the first request generates and stores the derivative, later requests hit the cache.

Look at the service provider's Blade directive registration and the config file before reading the transform classes — that tells you the directive signature and the defaults that apply when you omit arguments.

Implementation Patterns

• Blade directive as the default path. The package's headline feature is a Blade directive that resolves to a generated-image URL. Use it directly in src/srcset attributes so templates stay declarative, and keep the transform description inline (width/height/fit/format) so a designer can read intent from the template.
• Facade for programmatic use. When the URL has to be computed outside a view — API resources, sitemaps, queued jobs building a manifest — call the package facade/helper instead of rendering Blade. Same arguments, no view dependency.
• Cache-on-first-request, promote-to-generated. Generate derivatives lazily during development, but for production content (product photos, hero images) pre-generate via an artisan command or a queued job on upload so the first visitor doesn't pay the transform cost. Wire this into your existing upload/observer flow.
• Responsive variants. Because derivatives are cached per transform signature, emitting a small srcset (e.g. 320/640/1280 widths) is cheap after warm-up — one directive call per width.
• Version the source path, not the transform. Cache keys are derived from source + parameters; when an image is replaced, either change the stored filename or clear the derivative directory for that path. Filename-based versioning is the least surprising approach.
• Test against a fake disk. Storage::fake() plus an assertion that the derivative file exists after the first render is a solid smoke test for your integration, and it catches config drift early.

Gotchas and Tips

• Upgrade to ≥ 2.0.2 if you use the directive inline. v2.0.2 fixes a Blade compilation bug where an inline @php(...) in the same template (and, on the evidence of the fix, inline directive usage generally) caused the compiled output to swallow the remainder of the file. The symptom is nasty and non-obvious: the page renders correctly up to the directive and then everything after it disappears — no exception, no log entry. If you're on 2.0.0/2.0.1 and see truncated layouts, this is the cause, not your template.
• Inspect the compiled view when the directive misbehaves. Laravel writes compiled Blade to storage/framework/views; grepping there for the emitted PHP is the fastest way to tell a directive-compilation problem (malformed PHP, missing statement terminator) from a runtime/image problem. Clear with php artisan view:clear after upgrading — stale compiled views survive composer updates.
• Directive placement. Even on 2.0.2, putting the directive on its own line is the least fragile style; mixing it into a crowded attribute line makes any future compilation bug harder to localise.
• Driver mismatch. GD and Imagick support different formats and quality options; a transform that works locally on GD (with WebP support compiled in) can fail in a container without the extension. Assert the driver and format support at boot or in CI rather than discovering it on the first WebP request.
• Filesystem permissions and storage:link. Generated derivatives are written at runtime by the web user. A storage/ directory owned by your deploy user with restrictive umask produces silent 404s on the derivative URL while the page itself renders fine.
• Cache invalidation is manual. There is no automatic invalidation when a source file changes in place — plan for a clear/regenerate command in your deploy or content-publish pipeline.
• Quote and escape the emitted URL. The directive returns a URL containing query-ish transform parameters; emit it inside a properly escaped attribute ({{ }}, not {!! !!}) and avoid hand-concatenating query strings onto it, or you'll break the transform signature and regenerate on every request.