Php Heic To Jpg Laravel Package

Getting Started

1. composer require maestroerror/php-heic-to-jpg — pin ^1.0.8 so you pick up the corrected default heif-converter binary path.
2. There is no service provider or facade to register. The package is framework-agnostic and exposes a static API (Maestroerror\HeicToJpg), so you just use the class in a controller, job, or action. If you want it injectable/mockable, wrap it in your own thin service.
3. Verify the converter works in your runtime before writing feature code: run a conversion against a small fixture HEIC and catch the exception. This is where most environment problems (Docker images, Forge/Envoyer deploys) surface. If the bundled binary isn't where the package expects it, override the path per the README's converter-path configuration.
4. First real use case: an iOS upload endpoint. iPhones shoot HEIC by default, so accept the upload, convert to JPG, and store the derivative.

use Maestroerror\HeicToJpg;

$path = $request->file('photo')->getRealPath();

$jpg = HeicToJpg::convert($path)->saveAs(
    storage_path('app/public/photos/'.Str::uuid().'.jpg')
);

Implementation Patterns

• Always guard with HeicToJpg::isHeic($path). iOS falls back to JPEG when the user has "Most Compatible" enabled, and Android uploads can be anything. Branch on detection rather than on the file extension.
• Bytes vs. disk. ->get() returns the JPEG as a binary string — use it for S3/streamed responses where you don't want an intermediate file. ->saveAs($path) writes to the local filesystem only; for object storage, convert to a temp path (or use get()), then Storage::disk('s3')->put(...).
• Validation. heic/heif are not in Laravel's default mime guessing for mimes: in all versions. Validate with an explicit rule (mimes:heic,heif,jpg,jpeg) plus a getimagesize/signature check, and never trust the client-supplied extension.
• Push conversion to a queue. The package shells out to a native binary; it is CPU-bound and blocking. For anything beyond a thumbnail, dispatch a job from the upload controller and let the record sit in a pending state until the derivative exists. Set generous $timeout — 48MP HEICs are slow.
• Keep the original. Archive the HEIC (it's the source of truth for re-processing later) and store the JPG as a derived asset. A small Photo model with an observer or ProcessPhoto job keeps this tidy.
• Batch/directory work. Wrap each file in its own try/catch; one corrupt HEIC should not abort the whole batch.
• Testing. Convert a tiny committed fixture in a feature test and assert getimagesize($output)['mime'] === 'image/jpeg'. For unit tests of your own code, put the package behind an interface so you can fake it — the static API is otherwise hard to stub.

Gotchas and Tips

• Binary path is the #1 failure mode. v1.0.8 specifically fixes the default heif-converter binary path; on versions below it you can get "converter not found"-style failures out of the box. On Docker/Alpine/Forge, confirm with which heif-converter and, if the default is wrong for your image, override it with the package's converter-path setter.
• Executable bit lost on deploy. Composer-installed binaries frequently arrive without +x after a deploy or a vendor cache restore. Add a chmod +x in your deploy script and re-check after every deploy.
• proc_open/exec disabled on shared hosting kills the package at runtime with a confusing error. Fail fast in a health check.
• Temp directory writability and size. The converter writes intermediates to the system temp dir; small container /tmp (tmpfs with low size limits) will bite you on large uploads.
• EXIF orientation is not preserved. iPhone photos can come out rotated. Either re-apply orientation yourself or normalise with an image library after conversion.
• Don't let conversion break the upload. Catch the package's exception and fall back to storing the raw HEIC (or returning a clear 422) rather than a 500. Log the converter exit status — it distinguishes "bad file" from "bad environment".
• No first-party Laravel integration means no config publishing, no facade alias, no container binding. Wrap it once in App\Support\HeicConverter so the rest of the codebase isn't coupled to a static API, and so a future swap (Imagick with HEIC support, a hosted service) is a one-file change.
• Pin the version. Between the binary-path fix here and the native-binary nature of the package, floating constraints are a deployment risk; ^1.0.8 is the minimum you want.