Skip to content
ajendrasPublic

About

Extracts, analyzes and sanitizes EXIF, IPTC & XMP metadata in PHP with built-in privacy scanning and CLI

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

1 watching

Forks

Latest commit

Β 

History

10 Commits

Folders and files

Repository files navigation

MetaProbe

Pull camera, GPS & creator data Β· Scan & strip sensitive leaks Β· Secure automation for PHP apps

License PHP Stars CI Last commit PRs welcome

Extracts, analyzes and sanitizes EXIF, IPTC & XMP metadata in PHP with built-in privacy scanning and CLI

✨ Features β€’ ⚑ Quick start β€’ 🧰 Usage β€’ 🧩 Architecture β€’ πŸ“ Roadmap β€’ 🀝 Contributing

✨ Why MetaProbe?

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

🎬 Demo

MetaProbe demo

πŸš€ Features

πŸ“Έ 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 CLI
probe 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

πŸ“¦ Installation

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/metaprobe

The CLI is automatically available after installation:

php bin/metaprobe probe sample.jpg --format=pretty

⚑ Quick start

<?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";
}

🧰 Usage

Facade usage (recommended)

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";
}

Standalone steganography check

$stego = MetaProbe::detectSteganography('image.jpg');
if (!empty($stego['risks'])) {
    echo "Steganography risks: " . implode(', ', $stego['risks']);
}

PSR-15 Middleware (new)

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.

CLI

# Pretty table output
php bin/metaprobe probe photo.jpg

# JSON output + sanitization
php bin/metaprobe probe photo.jpg --format=json --sanitize

Batch processing

# 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 --sanitize

The 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";

Sanitization

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 replace
Advanced: 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]

🧩 Architecture

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]
Loading

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.

πŸ“ Project structure

.
β”œβ”€β”€ 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)

πŸ§ͺ Testing

composer test
# or
vendor/bin/phpunit

The 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.

πŸ“ Roadmap

  • 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!

🀝 Contributing

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.

πŸ“„ License

This project is licensed under the MIT License.

⭐ Star history

Star history

If MetaProbe saves you time, a ⭐ helps others find it.

Made with ❀️ by Ajendra

About

Extracts, analyzes and sanitizes EXIF, IPTC & XMP metadata in PHP with built-in privacy scanning and CLI

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages