Download the PHP package belisoful/php-image without Composer

php-image

Read and write the metadata inside image files — EXIF, XMP, IPTC, ICC profiles and the rest — from plain PHP, without re-encoding the picture. A standalone library with a single runtime dependency: the PSR-7 stream interface (psr/http-message).

If you have ever needed to strip the GPS coordinates out of a photo before publishing it, add a caption to a JPEG without putting it through another lossy generation, or find out which lens took a shot, that is what this is for.

The central promise is that editing metadata leaves your pixels alone. These readers parse the image container and rewrite only the parts you changed; the compressed image data comes through byte-identical. When you do want to change the pixels, getImage() / setImage() / fromImage() are there, and they carry the metadata across for you.

Formats

Every format here is supported in both directions — reading and writing.

• JPEG — parsed segment by segment: JFIF/JFXX, EXIF, XMP, Kodak Meta, Picture Info, Photoshop IRB/IPTC, ICC, and the comment. Edit any of them and the entropy-coded scan is copied through untouched.
• TIFF — a complete TIFF 6.0 engine, both byte orders and all twelve data types. Strip and tile data is relocated with recomputed offsets, so metadata edits are lossless. The raster decodes too: uncompressed, PackBits, LZW and the CCITT fax codings, at 1–16 bits, striped or tiled, across bilevel, grayscale, palette, RGB, CMYK, YCbCr and L*a*b*.
• PNG — chunk-level, with the normative chunk order maintained and CRCs recomputed. Reads and writes every carrier PNG defines, plus the Raw profile type 8bim text chunk that Photoshop, ImageMagick and ExifTool use to exchange IPTC (PNG has no IPTC chunk of its own). APNG animation is first class — frames round-trip byte-faithfully.
• WebP / RIFF — dimensions from VP8, VP8L or VP8X; ICC, EXIF and XMP read and written, with the VP8X header and its feature flags kept in step automatically.
• AVI / RIFF — LIST INFO tags, XMP in _PMX and the IDIT timestamp, read and written without ever decoding the media. The shared RIFF layer also reads and rewrites the two variant headers in the form it found them: RIFX, which stores every size big-endian, and RF64/BW64, which keeps its 64-bit sizes in a leading ds64 chunk.
• GIF 87a and 89a — the whole standard at block level, animation included. Frames are kept exactly as authored rather than coalesced, so sub-rectangles, disposal, interlacing and local palettes survive a round trip unchanged.
• ISO BMFF — HEIF, AVIF, MP4 and QuickTime, told apart by the ftyp brand. Exif and XMP ride meta items on a still and the Adobe uuid box on a movie, the ICC profile rides a colr item property, and movie user data is read and written in both the QuickTime udta text-atom and the iTunes ilst conventions. Nothing in the file moves: new bytes go into a fresh mdat and only the offset that names them is rewritten.
• JPEG XL — Exif, xml (XMP) and jumb boxes over the container's box grammar, with the pixel dimensions read out of the codestream's bit-packed SizeHeader. A bare codestream is promoted to a container on the first write rather than refusing the write.

Five of those formats simply have nowhere to put IPTC — WebP, GIF, AVI, ISO BMFF and JPEG XL — so setIPTC() throws rather than accepting records it would quietly lose. The same rule holds for every other carrier a format lacks: AVI has neither an Exif nor an ICC carrier, and JPEG XL keeps its ICC profile inside the codestream, so those setters throw too.

Metadata

• EXIF — the full model over IFD0/EXIF/GPS/Interoperability/IFD1, with all 220 known tags of Exif 3.1 (CIPA DC-008-2026) and human-readable interpretation of their values. Rewriting pins the maker note at its original byte offset, because maker notes are full of pointers into themselves and moving one corrupts it.
• Maker notes — thirteen manufacturers decoded (Agfa, Canon, Casio, Epson, Fujifilm, Konica/Minolta, Kyocera/Contax, Nikon, Olympus, Panasonic, Pentax, Ricoh, Sony), quirks and all: forced byte orders, note-relative offsets, embedded TIFFs, packed camera settings.
• XMP — a DOM-backed model of the entire ISO 16684-1 grammar: arrays, nested structures, qualifiers and language alternatives. It knows the standard schemas, so writing dc:title gives you a language alternative and dc:subject a Bag without your having to say so. Extended XMP in JPEG is split and rejoined transparently.
• IPTC (IIM 4.1) — the full record set as a map, addressable by tag name or record#dataset.
• Photoshop IRB — every 8BIM resource, with typed decoders and the embedded IPTC bridge.
• ICC profiles — not just swapped whole but genuinely edited: every header field, typed tag reads and writes, and the profile-id digest. ICCTransform converts pixels between matrix/TRC spaces in pure PHP, which gives GD colour management it has no API for.
• And the smaller ones: JFIF/JFXX thumbnails, JUMBF boxes, PrintIM, APP12 Picture Info, the Photoshop File Info 22-field sync layer, and the WAVE audio files cameras record beside photographs.

Two things worth knowing about

Privacy scrubbing. clearPrivateData() removes identifying information — location, authorship, camera identity, serial numbers, timestamps, software, maker notes, thumbnails — from every carrier a file holds, in a single call, by category. It leaves everything that describes the picture itself, so what you get back is still a useful photo.

Private spaces. The maker notes an EXIF rewrite must not disturb are exposed as byte ranges and bridged to the framework's reserved-space streams, so a consumer can edit around them with the same protection the writer itself applies.

Streams

Everything works with PSR-7 streams and PHP stream resources as well as strings and files — fromStream() and writeTo() throughout, partial writes honoured.

The library consumes PSR-7 streams rather than implementing one, so any implementation (Guzzle, Nyholm, your own) works, as does a plain PHP stream resource.

Very large TIFFs get a lazy scan: EXIF::scanFile() seeks through the header, IFD chains and thumbnail without ever reading the pixel data, so the metadata of a multi-gigabyte scan loads in kilobytes.

Requirements

Installation

What it provides

Failures raise PHP's own SPL exceptions: \InvalidArgumentException when a caller passes a bad argument or type, \UnexpectedValueException when data parses but is not what the format requires, and \RuntimeException for IO and environment failures. Since \UnexpectedValueException extends \RuntimeException, a single catch (\RuntimeException $e) covers every malformed-file and IO case.

Usage

Reading dimensions and metadata

Editing IPTC and saving without re-encoding

JFIF density and thumbnails

EXIF: read, interpret, edit, rewrite

GPS travels as decimal degrees, metres, and UTC instants — the helpers read and write the reference-letter and degrees/minutes/seconds tag pairs (seeding the mandatory GPSVersionID on first write):

TIFF files read through the same model — TIFFImage::fromFile('scan.tif')->getEXIF() — and the Kodak APP3 Meta block through $jpeg->getMeta().

Privacy: clearing identifying information

A photo leaving a user's control carries where, when, by whom, and with what it was taken — and it says so in several places at once: EXIF, XMP, IPTC, the Photoshop IRB, and format-specific fields such as the JPEG comment or PNG text chunks. Every carrier and every container implements PrivacyScrubbableInterface, so clearPrivateData() removes that by category — every category by default — while leaving the fields that describe the picture (exposure, colour, dimensions), and the result is still a well-formed, useful photo.

The categories are one bit each: Location (the GPS IFD, XMP GPS and place names, IPTC city/state/country), Author (artist, copyright, credit, contact, xmpRights, IRB URLs), Description (titles, captions, keywords, comments, JPEG/GIF comments, PNG text), CameraModel, SerialNumber (body/lens serials, XMP document/instance ids, IPTC job and document ids), Timestamp, Software, MakerNote (a proprietary blob that routinely embeds serials and owner names), Thumbnail (a copy of the image that survives cropping — a classic redaction leak: IFD1, XMP thumbnails, IRB and IPTC previews, JFIF/JFXX), and Interoperability; Identity and Provenance are presets, and All is -1. The return value is the number of items removed, and a second call removes nothing. IIM makes the IPTC envelope's date and number mandatory, so the scrub replaces an existing envelope date with a fixed synthetic sentinel (IPTC::ScrubbedDate) and re-derives the number from it, instead of letting the next write stamp today's date back in.

Private spaces: editing around the maker notes

A maker note carries pointers relative to its own position, so it must stay put when its EXIF is rewritten — the writer pins it. EXIF and TIFFImage report where those pinned ranges land in the composed bytes, and the editable ranges around them, so a consumer can rewrite the free regions and leave the private ones byte-identical.

Only a parsed maker note has an on-disk offset to pin, so a freshly built one reserves nothing. TIFFImage offers the same two methods for a TIFF file.

XMP

File Info: one edit, three stores

GIF animation, frame by frame

Frames are the ones the file actually stores — sub-rectangles, disposal methods and all — so editing metadata or one frame's pixels leaves every other byte untouched.

Frames convert to and from images through the graphics seam, quantizing on the way in:

Because unknown blocks round-trip raw with their identity intact, a GIF's XMP DataXMP and ICCRGBG1012 application extensions survive an edit — which is not true of every GIF library.

PNG: every carrier, and the pixels

PNG reads and writes each carrier the format defines. There is no IPTC chunk, so the records travel inside the Photoshop image-resource block of the Raw profile type 8bim text chunk — the form ImageMagick, Photoshop, and ExifTool exchange.

Animated PNG frames are authored, decoded, and edited like GIF frames:

WebP: metadata in an extended-format container

WebP carries ICCP, EXIF, and XMP chunks; setting any of them promotes a simple file to the extended VP8X form and sets the matching feature flag. It defines no IPTC carrier, so setIPTC() refuses rather than dropping the records.

GD or ImageMagick

Every method that takes or returns a raster accepts \GdImage and \Imagick alike, and builds whichever is asked for. GD is the default when both are loaded; ImageGraphics::setDefaultMode() changes that.

The backends are not interchangeable for every job, so ask before assuming: supports() answers per library, and never throws for one that is not installed.

Carrying a profile on the image object needs ImageMagick — GD has nowhere to keep one and drops any profile on decode, so its getICCProfile() answers null and setICCProfile() false rather than pretending. Converting pixels between two spaces works in both: ImageMagick uses its color-management library (and handles lookup-table profiles), GD uses ICCTransform. When an ability matters more than the library, ask for the library that has it:

Image codecs

Each codec also has an incremental engine — LZWCompressor::encoder()/decoder() (and the same on PackBitsCompressor and HorizontalPredictor) return a StreamCodec you feed with add() and flush with finish(), like PHP's own deflate_init/inflate_init. The whole-string compress()/decompress() are thin drivers of that engine, so each algorithm exists once; the engine is self-contained enough to drive a native php_user_filter (the library ships none of its own).

RIFF containers directly

Development

Coverage is gated rather than merely reported, at two depths. Lines (99.91%) are checked on every push; every source file must be complete except a handful whose remaining lines no test can reach, each justified in AGENTS.md:

Branches (99.70%) are checked on pull requests and on main rather than on every push, because instrumenting every branch takes far longer than the suite itself. It is the stronger measure: a covered line still hides a decision that only ever goes one way. The nineteen branches that remain are unreachable by construction — mostly edges PHP emits itself, such as the implicit UnhandledMatchError of a match whose subject is already range-checked:

Tests cover the format readers (dimensions and invalid-input rejection for JPEG/PNG/WebP, all three WebP variants, PNG ICC inflation); the read-write-every-carrier matrix across JPEG/PNG/WebP/TIFF/GIF (each container round-trips or explicitly refuses every metadata carrier its format defines, including the raster getImage()/setImage() paths); the GIF container (byte-faithful round trips of an animation exercising the whole standard, frame and extension editing, interlace, loop count, application-identity case, quantized import, and malformed-block rejection — cross-checked by decoding the composed files with GD and ImageMagick); the TIFF raster forms (tiles, planar, every bit depth, and the CMYK/YCbCr/Lab photometrics); the private-spaces bridge (reserved/free-space stream views that keep the maker notes byte-identical under Clip/Fail/Skip writes); the ICC profile coder and its pure-PHP color transform; the full XMP value grammar and schema registry; every makernote maker variant; the tag-interpretation decoders; the Photoshop resource decoders; the IPTC record set (parsing, tag-name and id access, validation/coercion, re-encode round trips); the Photoshop 8BIM codec (string and stream detection, IPTC decode/encode); the graphics seam (RGB and CMYK round trips, JPEG/PNG/WebP encode/decode, resampling, mono reduction, palette quantization, and the capability query in both libraries); and the compression codecs (LZW, GIF LZW, PackBits, CCITT fax, and predictor round trips plus their incremental StreamCodec engines across chunk sizes, including a native php_user_filter driving one). Test images and ICC profiles are generated in memory, so the repository carries no binary fixtures; the Imagick-path tests skip cleanly where ext-imagick is absent, and one CI job runs the whole suite without it to keep that promise honest. Test data is deterministic — PseudoRandomBytes stands in for random_bytes() — because random input makes both assertions and coverage vary from run to run.

Note: the library consumes PSR-7 streams but ships no implementation of its own. Belisoful\Image\Stream\StreamIO holds static helpers that read from, write to, and rewind either a StreamInterface or a raw PHP stream resource, and BinaryReader is a small offset-driven typed reader (not a stream) for the lazy metadata scan. The BitReader/BitWriter bit-level IO works on strings, and each compression codec pairs a whole-string CompressorInterface with an incremental StreamCodec engine.

License

BSD-3-Clause. See LICENSE.