frameright / php-image-metadata-parser

PHP image metadata parsing library (XMP, IPTC, Exif)

Image metadata parsing library (PHP 5.5+)

➡️ See this document rendered at docs.frameright.io/php

NOTE: this is based on dchesterton/image. Many thanks to dchesterton!

Supported image types:

• JPEG
• PNG
• WEBP

Supported image meta types:

• XMP
• IPTC
• EXIF

NOTE: a TypeScript equivalent of this library is available here.

Installation

Pull the library in your project via Composer with the following composer.json:

{
  "minimum-stability": "dev",
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/Frameright/php-image-metadata-parser.git"
    }
  ],
  "require": {
    "frameright/image-metadata-parser": "dev-master"
  }
}

Dependencies: php-xml

Usage

  ✨ Getting started

  🔧 Contributing

  📝 Tutorial

  📝 Changelog

Get metadata

$image = Image::fromFile($filename);

$headline = $image->getXmp()->getHeadline();
$camera = $image->getExif()->getCamera();
...

Loading specific image type

When file type is known, you can load the file type directly using the file types' fromFile method.

$jpeg = JPEG::fromFile('image.jpg');
$png = PNG::fromFile('image.png');

Instantiate from bytes

If you don't have a file to work with but you do have the image stored in a string (from database, ImageMagick etc.) you can easily instantiate an object from the string.

$data = ...

$jpeg = JPEG::fromString($data);

Instantiate from GD or a stream

You can also create an object from a GD resource or a stream.

$gd = imagecreate(100, 100);
$jpeg = JPEG::fromResource($gd);

$stream = fopen('...', 'r+');
$jpeg = JPEG::fromStream($stream);

Aggregate metadata

When just want a piece of metadata and don't care whether it's from XMP, IPTC or EXIF, you can use the aggregate meta object.

$image = Image::fromFile($filename);
$headline = $image->getAggregate()->getHeadline();

By default it checks XMP first, then IPTC, then EXIF but you can change the priority:

$aggregate = $image->getAggregate();
$aggregate->setPriority(['exif', 'iptc', 'xmp']);

$aggregate->getHeadline(); // will now check EXIF first, then IPTC, then XMP

You can also exclude a metadata type if you do not want to use it:

$aggregate->setPriority(['iptc', 'xmp']);
$aggregate->getHeadline(); // will only check IPTC and XMP

Get GPS data

$image = ...
$gps = $image->getAggregateMeta()->getGPS(); // checks EXIF and XMP
// or $gps = $image->getExif()->getGPS();

$lat = $gps->getLatitude();

php-image-metadata-parser's Issues

Fix unit tests

At the point we forked, many unit tests are already broken:

$ composer test
[...]
ERRORS!
Tests: 439, Assertions: 546, Errors: 78.
Script ./vendor/bin/phpunit handling the test event returned with error code 2

Improve file format detection

For now the library detects the format of a file (JPEG, PNG, ...) based on its extension. What if a file has no extension? The file could even have the wrong extension, for example some CDNs cache and deliver in the WebP format files that are originally JPEG or PNG.

The library should detect the format of a file by looking at its content instead.

Failing to read image regions from image with additional metadata

I'm not able to read image regions from this specific image: [removed]

Seems like a conflict with metadata from other tools.

If I delete all metadata (with exiftool -all= -overwrite_original) and create the regions again with Frameright app everything works fine.
Also reading the original image with your typescript library works fine.

How to reproduce:

$jpeg = JPEG::fromFile(
    __DIR__ . '/../Fixtures/metadata_failing.jpg');

$xmp = $jpeg->getXmp();
var_dump($xmp->getImageRegions());        
// returns empty array instead of image regions

exiftool shows that the regions exists in the metadata:

xifTool Version Number         : 11.88
File Name                       : metadata_failing.jpg
Directory                       : tests/Fixtures
File Size                       : 5.0 MB
File Modification Date/Time     : 2024:04:11 08:37:27+03:00
File Access Date/Time           : 2024:04:11 09:59:47+03:00
File Inode Change Date/Time     : 2024:04:11 09:59:30+03:00
File Permissions                : rw-rw-r--
File Type                       : JPEG
File Type Extension             : jpg
MIME Type                       : image/jpeg
JFIF Version                    : 1.01
Comment                         : PARIS, FRANCE - MARCH 05: Christine Centenera wears a blue with white embroidered pattern cap from Balenciaga, black sunglasses, a white t-shirt, a beige long / belted with shoulder-pads coat, black shiny leather pointed / heels knees boots / high boots, a gold ring, outside Vivienne Westwood , during Paris Fashion Week - Womenswear F/W 2022-2023, on March 05, 2022 in Paris, France. (Photo by Edward Berthelot/Getty Images)
X Resolution                    : 300
Displayed Units X               : inches
Y Resolution                    : 300
Displayed Units Y               : inches
Current IPTC Digest             : 427f4f1de07eaf1ec0da65d7181c8707
Coded Character Set             : UTF8
Envelope Record Version         : 4
By-line                         : Edward Berthelot
By-line Title                   : Contributor
Caption-Abstract                : PARIS, FRANCE - MARCH 05: Christine Centenera wears a blue with white embroidered pattern cap from Balenciaga, black sunglasses, a white t-shirt, a beige long / belted with shoulder-pads coat, black shiny leather pointed / heels knees boots / high boots, a gold ring, outside Vivienne Westwood , during Paris Fashion Week - Womenswear F/W 2022-2023, on March 05, 2022 in Paris, France. (Photo by Edward Berthelot/Getty Images)
Writer-Editor                   : XX / XX
Copyright Notice                : 2022 Edward Berthelot
Country-Primary Location Name   : France
Country-Primary Location Code   : FRA
Special Instructions            : Not Released (NR)
Keywords                        : apple, burgundy lipstick, elegant, fashion blogger, fashion outfit, ginger hair, long hiar, outfit, paris, ready-to-wear, rtw, smartphone, spring outfit, style, woman
Original Transmission Reference : 775778623
Object Name                     : 1381031758
Application Record Version      : 4
Exif Byte Order                 : Little-endian (Intel, II)
Image Description               : PARIS, FRANCE - MARCH 05: Christine Centenera wears a blue with white embroidered pattern cap from Balenciaga, black sunglasses, a white t-shirt, a beige long / belted with shoulder-pads coat, black shiny leather pointed / heels knees boots / high boots, a gold ring, outside Vivienne Westwood , during Paris Fashion Week - Womenswear F/W 2022-2023, on March 05, 2022 in Paris, France. (Photo by Edward Berthelot/Getty Images)
Resolution Unit                 : inches
Software                        : Adobe Photoshop Lightroom Classic 11.2 (Macintosh)
Modify Date                     : 2022:03:06 02:00:17
Exif Version                    : 0232
Date/Time Original              : 2022:03:05 12:53:47
Create Date                     : 2022:03:05 12:53:47
Offset Time                     : +01:00
Offset Time Original            : +01:00
Offset Time Digitized           : +01:00
Sub Sec Time Original           : 864
Sub Sec Time Digitized          : 864
Color Space                     : Uncalibrated
Profile CMM Type                : Linotronic
Profile Version                 : 2.1.0
Profile Class                   : Display Device Profile
Color Space Data                : RGB
Profile Connection Space        : XYZ
Profile Date Time               : 1998:02:09 06:49:00
Profile File Signature          : acsp
Primary Platform                : Microsoft Corporation
CMM Flags                       : Not Embedded, Independent
Device Manufacturer             : Hewlett-Packard
Device Model                    : sRGB
Device Attributes               : Reflective, Glossy, Positive, Color
Rendering Intent                : Perceptual
Connection Space Illuminant     : 0.9642 1 0.82491
Profile Creator                 : Hewlett-Packard
Profile ID                      : 0
Profile Copyright               : Copyright (c) 1998 Hewlett-Packard Company
Profile Description             : sRGB IEC61966-2.1
Media White Point               : 0.95045 1 1.08905
Media Black Point               : 0 0 0
Red Matrix Column               : 0.43607 0.22249 0.01392
Green Matrix Column             : 0.38515 0.71687 0.09708
Blue Matrix Column              : 0.14307 0.06061 0.7141
Device Mfg Desc                 : IEC http://www.iec.ch
Device Model Desc               : IEC 61966-2.1 Default RGB colour space - sRGB
Viewing Cond Desc               : Reference Viewing Condition in IEC61966-2.1
Viewing Cond Illuminant         : 19.6445 20.3718 16.8089
Viewing Cond Surround           : 3.92889 4.07439 3.36179
Viewing Cond Illuminant Type    : D50
Luminance                       : 76.03647 80 87.12462
Measurement Observer            : CIE 1931
Measurement Backing             : 0 0 0
Measurement Geometry            : Unknown
Measurement Flare               : 0.999%
Measurement Illuminant          : D65
Technology                      : Cathode Ray Tube Display
Red Tone Reproduction Curve     : (Binary data 2060 bytes, use -b option to extract)
Green Tone Reproduction Curve   : (Binary data 2060 bytes, use -b option to extract)
Blue Tone Reproduction Curve    : (Binary data 2060 bytes, use -b option to extract)
XMP Toolkit                     : Frameright XMP Toolkit 2.0.0
Asset ID                        : 1381031758
Dlref                           : 95yWeO3K9FRUOZUV93Ok9g==
Image Rank                      : 2
Metadata Date Xmlns             : http://ns.adobe.com/xap/1.0/
Metadata Date                   : 2024:04:09 10:47:51.852Z
Modify Date Xmlns               : http://ns.adobe.com/xap/1.0/
Country Code                    : FRA
Person In Image                 : Christine Centenera
Google Vision                   : 
Creator                         : Edward Berthelot
Description                     : PARIS, FRANCE - MARCH 05: Christine Centenera wears a blue with white embroidered pattern cap from Balenciaga, black sunglasses, a white t-shirt, a beige long / belted with shoulder-pads coat, black shiny leather pointed / heels knees boots / high boots, a gold ring, outside Vivienne Westwood , during Paris Fashion Week - Womenswear F/W 2022-2023, on March 05, 2022 in Paris, France. (Photo by Edward Berthelot/Getty Images)
Format                          : image/jpeg
Rights                          : 2022 Edward Berthelot
Subject                         : apple, burgundy lipstick, elegant, fashion blogger, fashion outfit, ginger hair, long hiar, outfit, paris, ready-to-wear, rtw, smartphone, spring outfit, style, woman
Title                           : 1381031758
Elvis ID                        : 8Mw0Nija4T38Sf6nY6lt-a
Author                          : Edward Berthelot
Copyright                       : 2022 Edward Berthelot
Authors Position                : Contributor
Caption Writer                  : XX / XX
Category                        : E
City                            : Paris
Copyright Flag                  : true
Country                         : France
Credit                          : Getty Images
Date Created                    : 2022:03:05 00:00:00+00:00
Headline                        : Street Style : Day Six - Paris Fashion Week - Womenswear F/W 2022-2023
Instructions                    : Not Released (NR)
Source                          : Getty Images Europe
Supplemental Categories         : CEL
Supplemental Category           : CEL
Transmission Reference          : 775778623
Url                             : https://www.gettyimages.com
Urgency                         : 2
Licensor URL                    : https://www.gettyimages.com/eula?utm_medium=organic&utm_source=google&utm_campaign=iptcurl
Terms And Conditions URL        : https://www.gettyimages.com/eula?utm_medium=organic&utm_source=google&utm_campaign=iptcurl
Keyword                         : apple, burgundy lipstick, elegant, fashion blogger, fashion outfit, ginger hair, long hiar, outfit, paris, ready-to-wear, rtw, smartphone, spring outfit, style, woman
Credit Line                     : Getty Images
Creator Tool                    : Edward Berthelot
Rating                          : 0
Document ID                     : xmp.did:e1c022c1-dfca-47cf-8c93-1f80457ddb53
Instance ID                     : xmp.iid:e1c022c1-dfca-47cf-8c93-1f80457ddb53
Original Document ID            : xmp.did:e1c022c1-dfca-47cf-8c93-1f80457ddb53
Web Statement                   : https://www.gettyimages.com/eula?utm_medium=organic&utm_source=google&utm_campaign=iptcurl
Image Region Boundary Shape     : Rectangle, Rectangle, Rectangle, Rectangle, Rectangle, Rectangle
Image Region Boundary Unit      : Relative, Relative, Relative, Relative, Relative, Relative
Image Region Boundary W         : 0.7179294823705926, 0.8162040510127532, 0.8447111777944486, 0.6882970742685671, 0.9167291822955739, 0.822205551387847
Image Region Boundary H         : 0.4785, 0.306, 0.42225, 0.81575, 0.8145, 0.287
Image Region Boundary X         : 0.11890472618154539, 0.0967741935483871, 0.08289572393098274, 0.1436609152288072, 0.041635408852213056, 0.09152288072018004
Image Region Boundary Y         : 0.13225, 0.16025, 0.1405, 0.11375, 0.11375, 0.15675
Image Region ID                 : crop-0fd40a5b-ad5f-4b29-9ab2-43afc21b44a6, crop-4c732f66-2884-4fb2-86ae-2fcc332349ae, crop-96109636-028d-455c-ac90-c0c9d1287965, crop-6198987b-009b-499d-97fb-8cbad064a4e4, crop-7802d940-6da5-424a-909b-148421ebaf40, crop-b9385090-7c1e-4125-81d0-7837af4eb4cd
Image Region Role Identifier    : http://cv.iptc.org/newscodes/imageregionrole/cropping, http://cv.iptc.org/newscodes/imageregionrole/cropping, http://cv.iptc.org/newscodes/imageregionrole/cropping, http://cv.iptc.org/newscodes/imageregionrole/cropping, http://cv.iptc.org/newscodes/imageregionrole/cropping, http://cv.iptc.org/newscodes/imageregionrole/cropping
Image Region Region Definition Id: definition-0dae7c70-f936-49ad-80d2-a9f0f6c0fcdb
Image Region Region Name        : 1:1 Square (Common sizes)
Image Width                     : 2666
Image Height                    : 4000
Encoding Process                : Baseline DCT, Huffman coding
Bits Per Sample                 : 8
Color Components                : 3
Y Cb Cr Sub Sampling            : YCbCr4:2:0 (2 2)
Image Size                      : 2666x4000
Megapixels                      : 10.7
Create Date                     : 2022:03:05 12:53:47.864+01:00
Date/Time Original              : 2022:03:05 12:53:47.864+01:00
Modify Date                     : 2022:03:06 02:00:17+01:00

GET = great , now for SET !?

Even though the basic tech for 'regions' has been around for some time, searching for good working implementations is a challenge..

Thank you for this!

But (there is almost always one, isn't there ;)

With your tool I can read XMP-regions via PHP, that's nice, but I'dd like to be able to store (and update?) regions also!

Could you make that happen?

Publish to Packagist

https://packagist.org/

Documentation/warnings around writing metadata

Writing XMP image regions, for example, isn't supported yet. Indeed we have implemented a getImageRegions() but no setImageRegions(). This should be documented.

We should also in general document the fact that we might drop support for writing metadata altogether some day.

Add unit tests for XMP image region parsing

Unit tests for https://github.com/Frameright/image/tree/master/src/Metadata/Xmp

Add getters for Image Region

https://iptc.org/std/photometadata/specification/IPTC-PhotoMetadata#image-region
https://www.iptc.org/std/photometadata/documentation/userguide/#_image_regions

Add WEBP support

See XMP Specification Part 3

Document how image region names, types and roles are extracted

Document which ones get extracted and how they are put together

See https://github.com/Frameright/image/blob/master/src/Metadata/Xmp/ImageRegion.php#L98

Add support for JPEG ExtendedXMP

The parser currently assumes that the entire XML is contained in one segment, however a segment is limited to 64KB, see XMP Specification part 3. In rare instances, the XML may be longer than 64KB and require to be splitted according to the ExtendedXMP definition.