- How do I install maestroerror/php-heic-to-jpg in a Laravel app?
- Install it with composer require maestroerror/php-heic-to-jpg. Laravel's package auto-discovery registers the service provider and facade, so no manual registration is usually needed, and the config file can be published if you want to customize it. The remaining setup is infrastructure: make sure the heif-converter binary exists on the host, is executable by the PHP process user, and that exec or proc_open is available.
- Does this package need exec or proc_open enabled? Can I use it on shared hosting?
- Yes. The package is a thin PHP wrapper that shell-executes the heif-converter binary, so the PHP process must be allowed to run external commands and the host must not block them via disable_functions. The binary also has to be installed and executable, and temp directories writable. It works well in Docker and Linux environments but is often problematic on restrictive shared hosting or hardened PHP-FPM setups.
- Why do I get a 'converter binary not found' error and how do I fix it?
- Default binary resolution is the most common failure point: version 1.0.8 was itself a patch to the default heif-converter path, which shows automatic detection is environment-fragile. Set the path explicitly with setConverterPath() or through the published config and environment variables instead of trusting the default. Also confirm the binary is executable by the PHP user and matches the version the package expects.
- How do I convert a HEIC file to JPG and save it with this package?
- The API is chainable: call HeicToJpg::convert() with the source HEIC file and then saveAs() with the destination JPEG path. You can control output quality and related options through the configuration and chainable methods. Because it shells out to libheif-based conversion, always validate the result against real iPhone HEIC fixtures, including rotated images.
- Which PHP and Laravel versions does php-heic-to-jpg support?
- Confirm the exact PHP and Laravel version matrix in the package's composer.json on Packagist or GitHub before adopting it, rather than assuming your runtime is covered. The package is Composer-installable with PSR-4 autoloading and integrates with Laravel through a service provider and facade. You should also check which heif-converter binary version it expects versus what your base image ships, since a mismatch is the likeliest integration defect.
- Should I convert HEIC images synchronously in the request or in a queued job?
- For production workloads, run conversions in a queued job rather than in the request path. Shell-based conversion has no guaranteed timeout semantics and opaque error reporting, so you need your own limits on input size, dimensions, and concurrency to avoid CPU and memory exhaustion. A job also gives you a clean place to define the fallback behavior: reject the upload, store the original, or retry asynchronously.
- Does the package preserve EXIF orientation, ICC profiles, and metadata?
- Metadata preservation is not guaranteed, so do not assume EXIF orientation, ICC profiles, or other metadata survive the conversion. Test with real iPhone HEIC fixtures that contain EXIF-rotated images and verify the resulting JPEGs look correct on your target container, not just on a dev laptop. If orientation matters, normalize it explicitly in your ingestion pipeline.
- What are the alternatives to this package for HEIC to JPEG conversion in PHP?
- The main alternative is Imagick compiled with a HEIC delegate via libheif, which removes the shell-exec dependency entirely if your environment supports it. You could also call heif-converter or ImageMagick command-line tools directly, but that means owning the same binary and process concerns yourself. Whichever route you choose, wrap it behind your own ImageNormalizer interface so the dependency stays swappable and testable.
- How do I verify the conversion works inside Docker before going live?
- Add a startup smoke test that asserts the converter binary exists, is executable, and reports a compatible version, then fail fast if it does not. Run contract tests with real HEIC fixtures through both convert() and saveAs() inside the target container image. Also check that exec or proc_open is permitted and that temp directories are writable for the PHP process user.
- Is maestroerror/php-heic-to-jpg actively maintained and is v1.0.8 safe to upgrade to?
- It is a single-maintainer project with a low release cadence; v1.0.8 is a one-line fix contributed by a first-time contributor, which is a healthy community signal but not a governance or longevity guarantee. The release has no semver-breaking surface, but because it changes the default binary resolution, verify behavior immediately after upgrading in every environment. Pin the version, keep an explicit binary path in config, and track libheif and ImageMagick CVEs yourself.