Bladeimagecrop Laravel Package

Getting Started

The v4.1 line is a ground-up rewrite of the image pipeline, so treat onboarding as "learn the new path-based API" rather than "learn the package." Start with the release notes and the changelog entry for 4.1.0, then read the config file and the manager/facade class before touching any application code.

1. Install and pin deliberately. This is a pre-release (4.1-dev.0). Require it explicitly and keep minimum-stability scoped so it does not leak into other dependencies:

   composer require vendor/package:4.1.*@dev
   

   For anything shared or production-bound, pin an exact version or commit until a stable 4.1.x ships.

2. Confirm the ImageMagick dependency. The rewrite leans on ImageMagick far more heavily, so verify the extension and binary before debugging application code:

   php -m | grep -i imagick
   convert -version   # or: magick -version
   

   If imagick is missing, the package may fall back to a slower or less capable driver, or fail outright — either way, the first place to look is the configured driver.

3. Publish and read the config. Look for the driver, default disk, output quality, temp directory, and any preset/profile definitions. These are the knobs you will actually touch day to day.

4. First use case: upload → derive → store. The core mental model in v4.1 is files in, files out. Do not base64-encode, do not hold image blobs in variables, and do not pass raw bytes across layers:

   $path = $request->file('photo')->store('uploads', 'local');
   
   $image = ImageManager::open(Storage::disk('local')->path($path))
       ->resize(width: 1200)
       ->convert('webp')
       ->quality(82);
   
   $image->save(Storage::disk('public')->path('photos/hero.webp'));
   

   Confirm the exact method names against the package docs — the important part is the shape: open(path) → transform → save(path). Once that works end to end, everything else is composition.

Implementation Patterns

Treat paths as the currency of the application. The single biggest change in v4.1 is that image strings are gone as an interchange format. Structure your code so controllers, jobs, and services pass paths, UploadedFile instances, or filesystem handles — never encoded image data. If you have a service layer that returns image content, change it to return a path or a Storage reference.

Store originals, derive variants on demand. Keep uploaded files immutable and generate derivatives lazily or via a queue. A pattern that scales well:

• Upload endpoint stores the original and records its path.
• A GenerateDerivative job (or an on-demand controller) opens the original by path, applies a named preset, and writes to a deterministic destination.
• A derivatives table or a path convention (photos/{id}/{preset}.webp) lets you check existence before regenerating.

Use presets rather than inline chains. Anything you call from more than one place — thumbnails, social cards, avatars — belongs in config as a named profile. This keeps dimensions, format, and quality consistent and makes a future driver swap far less painful.

Process off the request cycle. ImageMagick is CPU- and memory-hungry. Resizing a 20 MP upload synchronously in an FPM worker is how you get 504s. Dispatch a job, return a placeholder or the original, and let the client poll or use a signed derivative URL.

Handle remote disks explicitly. Local paths are the happy path. For S3 and other remote disks, the package cannot address the file directly, so the pattern is: download to a temp file, process by path, upload the result, and clean up in a finally block. Wrap that in a small helper so it is not repeated in every job.

Test with a real driver where it matters. Storage::fake() is fine for path and disk assertions, but it will not exercise ImageMagick. Keep a small set of integration tests that assert output dimensions, format, and file existence against a real temp disk; mock the manager only for pure orchestration tests.

Use dependency injection, not facades, in jobs and services. The rewrite likely changes constructor signatures and internals between dev releases. Injecting the manager interface keeps your call sites stable and your tests simple.

Gotchas and Tips

This is a dev release — assume breakage. 4.1-dev.0 is a rewrite, not a patch. Expect method signatures, config keys, and driver behaviour to shift before 4.1.0 stable. Do not ship it to production without a pinned version and a rollback path.

The breaking change to audit for first: string inputs. Any code that did base64_encode(...), passed data: URIs, file_get_contents() results, or raw binary strings into the package will likely fail or silently misbehave. Grep your codebase for:

grep -rn "base64_encode\|data:image\|file_get_contents" app/

Replace those call sites with a temp file written to disk and the path passed through. This is the most common upgrade trap in this release.

ImageMagick will still exhaust memory. The rewrite reduces the package's own memory footprint, but a 50 MP TIFF can still blow past memory_limit. Set sane memory_limit and max_execution_time on queue workers, and check ImageMagick's policy.xml — many distros ship restrictive defaults on width, height, area, and PDF/PS handling. A policy.xml denial often surfaces as a generic "unable to read image" error, so check ImageMagick logs and policy first when a valid file fails.

Watch temp file hygiene. Path-based processing means temp files. Always unlink in finally, and be aware of the system temp directory filling up on failed jobs. Configure a dedicated temp directory if the package supports it, and monitor it.

Remote disk round-trips are a common source of bugs. Forgetting to delete the downloaded temp file, or writing the derivative to a local path and assuming it landed on S3, are the two classic mistakes. Assert the final Storage::disk(...)->exists($path) in tests.

Handle EXIF orientation and metadata explicitly. Auto-orientation is often not the default, and stripping metadata is a deliberate choice (privacy vs. colour profile fidelity). Decide per preset and document it — portrait photos appearing sideways is the most frequent "the package is broken" report.

Animated formats need separate handling. GIF and animated WebP have frame semantics that a naive resize will flatten. If you accept these uploads, test them explicitly rather than assuming the static-image path covers them.

Race conditions on derivatives. Two requests for the same missing thumbnail can both generate and write. Write to a unique temp path and atomically rename into place, or use a lock keyed on the derivative path.

Debug by logging paths, not bytes. When a job fails, log the source path, the preset name, and the target path. Logging image content is both useless and a good way to fill your log disk.

Know the extension points before you need them. Check whether the package exposes custom drivers, macros, or events around processing. If you need non-standard behaviour (watermarking, custom crop logic), hooking a driver or macro is usually cleaner than forking the pipeline — and far easier to carry across the inevitable dev-release churn.