Convert HEIC to JPG, using PHP or JS

Convert HEIC to JPG, using PHP or JS

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

Convert HEIC to JPG, using PHP or JS

Anyone trying to convert a HEIC file to JPG often hits a wall immediately after reading the documentation. The most common stumbling block comes from relying on the official nokiatech/heif repository without understanding its specific requirements. While the examples in that repo work perfectly with their provided test files, scripts frequently refuse to process photos taken on modern iPhones. This discrepancy usually points to a misunderstanding of how the library handles metadata and color profiles, rather than a flaw in the conversion logic itself.

The core issue with the nokiatech/heif approach is that it expects raw or minimally processed data. When you pull an image directly from an iPhone's photo library via PHP or JavaScript, the file often contains specific ICC color profiles or embedded metadata that the basic decoder doesn't handle gracefully out of the box. The official examples likely strip this metadata during their setup, but real-world usage preserves it, causing the script to fail with cryptic errors or simply hang.

To solve this in a PHP environment, you cannot simply rely on getimagesize() or standard GD functions before conversion. You must ensure the HEIC file is fully decoded into a raw stream that the decoder expects. A robust implementation often involves using a library like heif (a fork of the Nokiatech project) alongside intervention/image for the final resize and format conversion. The workflow requires decoding the HEIF container first, extracting the primary image object, and then passing it to a standard image processor.

Here is a practical pattern for handling this in PHP:

use Intervention\Image\Facades\Image;
use Heif\HeifDecoder;

// Initialize the decoder
$decoder = new HeifDecoder();

// Read the file contents
$imageData = file_get_contents('iphone_photo.heic');

try {
    // Decode the HEIF data
    $image = $decoder->decode($imageData);
    
    // Convert to a format Intervention Image can handle (usually BMP or PNG intermediate)
    $bmpContent = $image->getAsBmp();
    
    // Now process with Intervention Image to convert to JPG and optimize
    $jpgImage = Image::make($bmpContent)
        ->optimize()
        ->save('output.jpg');
} catch (\Exception $e) {
    // Handle specific errors related to color profiles or unsupported frames
    error_log("HEIC Decode Error: " . $e->getMessage());
}

The trade-off here is performance and memory usage. Decoding HEIF to an intermediate format like BMP can spike memory consumption for large files before the final JPG compression occurs. For high-throughput applications, this might require stream-based processing or offloading the decoding step to a worker queue rather than blocking the main request thread.

In JavaScript environments, specifically Node.js, the approach shifts toward using heif via native bindings or WASM. The logic remains consistent: decode the container before attempting pixel manipulation. However, browser-based conversion is significantly more complex due to MIME type restrictions and the lack of direct file system access. You generally need a backend service to handle the heavy lifting if you are building a web app that accepts user uploads.

A critical pitfall developers face is ignoring the heif library's dependency on specific build tools. If your environment lacks the necessary C++ libraries or WASM runtimes, the decoder will silently fail or throw generic errors that look like logic bugs rather than environment issues. Always verify that your deployment environment matches the prerequisites listed in the official repository documentation before assuming a conversion failure is code-related.

When evaluating third-party solutions, keep in mind that while open-source libraries like nokiatech/heif offer full control over the decoding process, they demand more setup and debugging time. If your priority is rapid development and you are not building a custom image pipeline, integrating a dedicated API service might be the pragmatic choice to avoid wrestling with low-level decoder configurations and metadata quirks.

Our network