Extracts, analyzes and sanitizes EXIF, IPTC & XMP metadata in PHP with built-in privacy scanning and CLI
β¨ Features β’ β‘ Quick start β’ π§° Usage β’ π§© Architecture β’ π Roadmap β’ π€ Contributing
PHP web apps regularly process user images yet lack a unified, security-first tool to extract metadata without leaking GPS, device fingerprints or author info. Existing solutions are either outdated, limited to EXIF, or miss sanitization. MetaProbe targets developers building media managers, upload pipelines, forensic tools and AI-augmented image workflows.
- Unified extraction β one call reads EXIF, IPTC and XMP from JPEG, PNG, TIFF, WebP, AVIF and HEIC
- Built-in privacy scanning β flags risky fields and returns a 0-100 safety score
- Smart sanitization β strips PII while preserving quality, copyright and color profiles
- Rich, zero-config API β immutable DTOs, GPS value object, pluggable readers and a beautiful CLI
- PSR-15 middleware β drop-in auto-sanitization for uploaded images in any modern PHP framework
| πΈ Unified Extraction Single API reads EXIF, IPTC and XMP from JPEG, PNG, TIFF, WebP, AVIF and HEIC in one call |
π°οΈ GPS Decoder Converts DMS coordinates to decimal with Google Maps link generator |
π Privacy Scanner Flags risky fields and returns a numeric safety score via SecurityReport |
| π§Ό Smart Sanitizer Rewrites images stripping PII while preserving copyright and profiles (GD + Imagick fallback) |
π Steganography Detector Analyzes LSB patterns in pixel data and flags statistically unusual randomness that may indicate hidden information |
π₯οΈ Rich CLIprobe and sanitize commands with JSON output, pretty tables and verbose reporting |
| π¦ Structured Reports Metadata DTO with toArray(), toJson(), typed getters and getPrivacyScore() |
π Reader Interface Pluggable readers so custom formats can be added by implementing supports() and read() |
π Batch CLI Directory scanning with Symfony ProgressBar, per-image reports and CSV summary export for bulk analysis |
| π PSR-15 Middleware Auto-sanitizes image uploads in any PSR-15 framework (Slim, Laminas, Symfony, etc.) |
βοΈ Zero-config Core Depends only on PHP extensions; optional Symfony Console for the CLI |
Requirements: PHP 8.2+, ext-exif, ext-xml, ext-gd (ext-imagick recommended for WebP, AVIF and HEIC metadata and sanitization). Symfony Console is required only for the CLI. PSR-15 interfaces are required for the middleware.
composer require ajendras/metaprobeThe CLI is automatically available after installation:
php bin/metaprobe probe sample.jpg --format=pretty<?php
require_once 'vendor/autoload.php';
use MetaProbe\MetaProbe;
$metadata = MetaProbe::probe('photo.jpg');
$report = MetaProbe::scan('photo.jpg');
echo $metadata->toJson();
if ($gps = $metadata->getGps()) {
echo "\nGoogle Maps: " . $gps->getGoogleMapsUrl();
}
echo "\nPrivacy Score: " . $report->getScore() . "/100\n";
if ($report->hasSteganographyRisk()) {
echo "\nβ οΈ Potential steganography detected (unusual LSB patterns)\n";
}use MetaProbe\MetaProbe;
$metadata = MetaProbe::probe(__DIR__ . '/uploads/image.jpg');
$report = MetaProbe::scan(__DIR__ . '/uploads/image.jpg');
$exif = $metadata->getExif();
if (!empty($exif['Camera'])) {
echo "Camera: " . $exif['Camera'];
}
if ($gps = $metadata->getGps()) {
echo "GPS: " . (string) $gps; // 51.5125000,-0.1250000
echo "\nMap: " . $gps->getGoogleMapsUrl();
}
echo "\nSafety: " . $report->getScore() . "/100";
if ($report->hasSteganographyRisk()) {
echo "\nβ οΈ Steganography risk: unusual LSB patterns detected";
}$stego = MetaProbe::detectSteganography('image.jpg');
if (!empty($stego['risks'])) {
echo "Steganography risks: " . implode(', ', $stego['risks']);
}use MetaProbe\MetaProbe;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\RequestHandlerInterface;
// Register early in your pipeline (Slim, Laminas Mezzio, etc.)
$app->add(MetaProbe::middleware(throwOnFailure: false));
// The middleware automatically detects image/* uploads via
// getUploadedFiles(), sanitizes their temporary files in-place
// using the built-in Sanitizer, then passes the request onward.
// Sensitive metadata never reaches your handlers or storage.# Pretty table output
php bin/metaprobe probe photo.jpg
# JSON output + sanitization
php bin/metaprobe probe photo.jpg --format=json --sanitize# Process directory with live progress bar and CSV export
php bin/metaprobe batch ./photos --output=summary.csv
# Recursive scan + sanitization
php bin/metaprobe batch ./uploads -r --sanitizeThe batch command discovers supported images, shows a real-time progress bar, extracts metadata/privacy scores for every file, writes a detailed CSV report, and can optionally sanitize images in-place.
use MetaProbe\MetaProbe;
// Batch API returns structured summary (no progress bar)
$summary = MetaProbe::batch(__DIR__ . '/photos', recursive: true);
foreach ($summary as $item) {
echo $item['filename'] . ': ' . $item['privacy_score'] . '/100';
if (!empty($item['gps_coordinates'])) {
echo ' (GPS: ' . $item['gps_coordinates'] . ')';
}
echo "\n";
}
echo "\nProcessed " . count($summary) . " images.\n";use MetaProbe\MetaProbe;
// Overwrite original (use with caution)
MetaProbe::sanitize('original.jpg');
// Safe copy
MetaProbe::sanitize('original.jpg', 'clean.jpg');Advanced: custom reader
use MetaProbe\ReaderInterface;
use MetaProbe\MetaProbe;
class CustomReader implements ReaderInterface
{
public function supports(string $mimeType): bool
{
return $mimeType === 'image/jpeg';
}
public function read(string $path): array
{
// return normalized metadata array
return ['custom' => 'value'];
}
}
$probe = new MetaProbe();
$probe->getReaders(); // inspect or replaceAdvanced: working with Metadata DTO
$metadata = MetaProbe::probe($path);
echo $metadata->toJson(); // pretty-printed
$data = $metadata->toArray(); // structured array
$score = $metadata->getPrivacyScore(); // uses Scanner internally
$gps = $metadata->getGps()?->getDecimal(); // ['lat' => 51.5125, 'lng' => -0.125]flowchart TD
HTTP[HTTP Request] --> Middleware[ImageSanitizationMiddleware<br/>(PSR-15)]
Middleware -->|detects image/* uploads| MetaProbe[MetaProbe Facade]
MetaProbe --> Readers[Readers<br/>ExifReader β’ IptcReader β’ XmpReader β’ ImagickReader]
Readers -->|supports + read| Data[Normalized arrays]
Data --> Metadata[Metadata DTO]
Metadata --> Gps[Gps Value Object<br/>fromExif β decimal + Google Maps URL]
MetaProbe --> Scanner[Scanner<br/>isSensitive + calculateScore + SteganographyDetector]
Scanner --> Report[SecurityReport<br/>score + risks + hasSteganographyRisk()]
MetaProbe --> Sanitizer[Sanitizer<br/>GD imagecopy or Imagick stripImage]
Middleware --> Sanitizer
MetaProbe --> Console[Console Commands<br/>ProbeCommand β’ SanitizeCommand β’ BatchCommand]
Console -->|Symfony Console| CLI[bin/metaprobe]
The MetaProbe facade coordinates pluggable readers, assembles an immutable Metadata object (with embedded Gps when present), then hands it to Scanner for privacy analysis or Sanitizer for cleaning. The new PSR-15 middleware sits in front of your request handlers, automatically sanitizing any uploaded images before they reach application code. The design is intentionally zero-config while remaining easily extensible via ReaderInterface.
.
βββ bin/
β βββ metaprobe # CLI bootstrap: registers ProbeCommand, SanitizeCommand & BatchCommand
βββ src/
β βββ MetaProbe.php # Facade with static probe(), scan(), sanitize(), batch(), middleware() and findImages()
β βββ Metadata.php # Immutable DTO with getters, toArray(), toJson(), getPrivacyScore()
β βββ Gps.php # Value object: fromExif(), getDecimal(), getGoogleMapsUrl()
β βββ ReaderInterface.php # supports() + read() contract
β βββ Middleware/
β β βββ ImageSanitizationMiddleware.php # PSR-15 middleware that auto-sanitizes uploads
β βββ Readers/
β β βββ ExifReader.php # exif_read_data() + normalization (Camera, Lens, Exposure, GPS)
β β βββ IptcReader.php # getimagesize() + iptcparse() mapping
β β βββ XmpReader.php # APP1 XMP packet extraction via SimpleXML + XPath
β β βββ ImagickReader.php # Imagick getImageProperties() for WebP, AVIF, HEIC + normalization
β βββ Security/
β β βββ Scanner.php # getRisks(), calculateScore(), isSensitive() + SteganographyDetector
β β βββ SteganographyDetector.php # LSB randomness analysis on pixel data
β β βββ Sanitizer.php # GD imagecopy or Imagick stripImage (now with WebP/AVIF/HEIC)
β β βββ SecurityReport.php # score + risks + hasSteganographyRisk()
β βββ Console/
β βββ ProbeCommand.php # Symfony command with --format and --sanitize options
β βββ BatchCommand.php # New: directory scanner with ProgressBar, per-file summary and CSV export
βββ tests/
β βββ ProbeTest.php # PHPUnit tests for Gps, Metadata, Scanner, Sanitizer, facade, batch and middleware
βββ examples/
β βββ basic-usage.php # Runnable demo script using the facade
βββ composer.json # PSR-4, bin, scripts (test/probe/sanitize/batch)
βββ vendor/ # (after composer install)
composer test
# or
vendor/bin/phpunitThe suite covers GPS DMS-to-decimal conversion, extraction accuracy on fixture images, Scanner risk detection and scoring, Sanitizer output size and tag removal, full facade integration paths, plus the new batch() / findImages() methods and the PSR-15 middleware.
- v0.1.0 β first release: Unified Extraction, GPS Decoder, Privacy Scanner, Smart Sanitizer
- Add WebP, AVIF and HEIC format support via native or Imagick readers
- Batch directory command with progress bar and summary CSV export
- PSR-15 middleware that auto-sanitizes uploaded images in frameworks
- Steganography detector that flags unusual LSB patterns
- HTML report generator with interactive metadata tree view
- OpenAI integration to generate alt-text from extracted context
- Laravel and Symfony service provider / bundle auto-registration
- Custom reader plugin system with Composer discovery
- GitHub Action that scans repo images for embedded GPS data
- Support for reading embedded JSON-LD and llms.txt sidecar files
- Performance benchmark suite against 500-image corpus
- Interactive web UI (single HTML + Tailwind) for drag-and-drop demo
π€ This roadmap is worked through continuously β ideas and PRs welcome!
Contributions are welcome and appreciated! Please read CONTRIBUTING.md first and follow our CODE_OF_CONDUCT.md. Good-first-issue PRs are especially encouraged β improving test coverage, adding new readers, or polishing CLI output are all great places to start. Open a PR against the main branch of ajendras/metaprobe.
This project is licensed under the MIT License.