README

Overview

Media adds rich media processing to your Glueful application: transform images (resize, crop, fit, format conversion, watermarking), generate thumbnails on upload, serve on-demand image variants from the blob endpoint, and extract media metadata (dimensions, duration, codecs).

It plugs into the framework's upload pipeline through the Glueful\Uploader\Contracts\MediaProcessorInterface seam: once installed, file uploads gain thumbnails and full metadata and the blob endpoint serves resized/converted images. The framework keeps working without it — see Behavior Without the Extension.

Features

Fluent image processing: resize, fit, crop, quality, format conversion, and watermarking via Intervention Image v4
On-demand variants: serve resized/converted images straight from the blob endpoint (?width=&height=&quality=&format=)
Thumbnail generation: automatic thumbnails on uploadMedia(), written to the upload's own storage disk
Media metadata: dimensions, duration, and codec details via getID3
image() helper: a fluent global helper for ad-hoc image work
Seam-based: binds the core MediaProcessorInterface; the framework degrades gracefully when the extension is absent
Configurable: driver (GD/Imagick), processing limits, quality, security, and caching via the image config + IMAGE_* env

Installation

Installation (Recommended)

Install via Composer

composer require glueful/media

# Rebuild the extensions cache after adding new packages
php glueful extensions:cache

Composer discovers packages of type glueful-extension, but installing does not auto-enable them — the provider must be added to config/extensions.php's enabled allow-list. The CLI does that for you:

# Enable (adds the provider FQCN to config/extensions.php + recompiles the cache)
php glueful extensions:enable media

# Disable (removes it)
php glueful extensions:disable media

In production, manage the enabled list in config and run php glueful extensions:cache in your deploy step. The extension ships no migrations.

Local Development Installation

To develop the extension locally, register it as a Composer path repository in your app's composer.json, then require and enable it:

// composer.json
"repositories": [
    { "type": "path", "url": "extensions/media", "options": { "symlink": true } }
]

composer require glueful/media:@dev
php glueful extensions:enable media

Entries in config/extensions.php are plain string FQCNs (no ::class) — prefer extensions:enable over editing by hand.

Verify Installation

php glueful extensions:list
php glueful extensions:info media
php glueful extensions:diagnose

Post-install checklist:

Ensure a PHP image driver is available: GD (default) or ImageMagick (IMAGE_DRIVER=imagick)
Rebuild cache after Composer operations: php glueful extensions:cache
Confirm the seam is bound: resolving Glueful\Uploader\Contracts\MediaProcessorInterface yields Glueful\Extensions\Media\MediaProcessor

Configuration

Configuration is loaded from the extension's config/image.php and merged under the image key by the service provider. It reads the standard IMAGE_* environment variables:

# Driver selection (gd|imagick)
IMAGE_DRIVER=gd

# Processing limits
IMAGE_MAX_WIDTH=2048
IMAGE_MAX_HEIGHT=2048
IMAGE_MAX_FILESIZE=10M

# Quality
IMAGE_JPEG_QUALITY=85
IMAGE_WEBP_QUALITY=80

# Security
IMAGE_DISABLE_EXTERNAL_URLS=false
IMAGE_VALIDATE_MIME=true

# Caching
IMAGE_CACHE_ENABLED=true
IMAGE_CACHE_TTL=86400

The framework's own upload keys — UPLOADS_IMAGE_PROCESSING / UPLOADS_THUMBNAILS / THUMBNAIL_* (in the app's config/uploads.php / config/filesystem.php) — gate the upload pipeline and take effect once this extension binds the seam.

Usage

Fluent image processing

// Resize and re-encode to disk
image($context, '/path/to/image.jpg')
    ->resize(800, 600)
    ->quality(85)
    ->save('/path/to/output.jpg');

// Convert format and get the encoded bytes (e.g. to stream a response)
$webp = image($context, '/path/to/image.png')
    ->resize(1200, null)   // width 1200, height auto (aspect preserved)
    ->format('webp')
    ->getImageData();

// Apply a watermark, then save
image($context, '/path/to/photo.jpg')
    ->watermark('/path/to/logo.png', 'bottom-right')
    ->save('/path/to/watermarked.jpg');

Thumbnails + full metadata on upload

FileUploader::uploadMedia() writes a thumbnail onto the upload's own storage disk and returns full metadata:

$result = $uploader->uploadMedia($file, 'media/images');
$result['thumb_url'];                   // thumbnail URL
$result['width'];  $result['height'];   // populated dimensions

On-demand variants

The core blob endpoint routes through this extension's renderVariant():

GET /blobs/{uuid}?width=300&height=200&quality=80&format=webp

Behavior Without the Extension

The framework degrades gracefully when no media processor is bound:

image() is undefined (function-not-found, not a stub);
uploadMedia() succeeds but returns thumb_url: null and type-only metadata (MIME classification, no dimensions/duration);
the blob-resize endpoint serves the original image (415 only on an explicit format conversion).

Requirements

PHP 8.3 or higher
Glueful 1.52.0 or higher
GD or ImageMagick PHP extension (for image processing)
intervention/image ^4.1 and james-heinrich/getid3 ^1.9 (installed automatically)

License

MIT — licensed consistently with the Glueful framework.

Support

For issues, feature requests, or questions, please create an issue in the repository.

glueful / media

Maintainers

Package info

Statistics

Security