Download the PHP package blackpig-creatif/chambre-noir without Composer

ChambreNoir

Automatic image conversion, responsive images, attribution, and gallery management for FilamentPHP v5.

ChambreNoir extends Filament's FileUpload with automatic image conversions on upload, responsive image rendering via <picture> and srcset, and built-in photographer attribution. The core upload feature stores JSON in any column with no additional tables. The optional Gallery system adds first-class entities for managing curated image collections.

Requirements

• PHP 8.2+
• Laravel 11+ / 12+
• FilamentPHP 4+ / 5+
• Imagick PHP extension
• Intervention Image 3.x

Installation

Publish the config (optional):

Quick Start

1. Create a Conversion Preset

This generates app/BlackpigCreatif/ChambreNoir/Conversions/HeroConversion.php:

2. Use in a Filament Form

3. Add the Trait to Your Model

4. Render in Blade

How It Works

When an image is uploaded through RetouchMediaUpload:

1. Filament's FileUpload saves the original to disk
2. ChambreNoir creates conversions based on the preset
3. A JSON structure is stored in the database column

Old images are automatically cleaned up when replaced or removed.

RetouchMediaUpload

Drop-in replacement for Filament's FileUpload. Image-only by default.

Conversions via Preset (Recommended)

Inline Conversions

Config-based Presets (Legacy)

String keys reference config/chambre-noir.php presets. BaseConversion classes are preferred for new projects.

Disable Conversions

All standard FileUpload methods (disk(), directory(), imageEditor(), maxSize(), etc.) work as expected.

Conversion Presets

Presets define the image sizes generated on upload. Extend BaseConversion and implement define():

Each conversion accepts width, height, fit, and quality. Missing values inherit from class defaults.

Fit Methods

Composition

Presets can include other presets via includes():

Included conversions are merged first; the defining class can override them.

Responsive Configuration

Override getResponsiveConfig() to control <picture> and srcset behaviour:

See Conversion Presets for the full reference.

Built-in Preset

SocialImageConversion ships with ChambreNoir, producing og (1200x630) and twitter (1200x600) crops at 90% quality.

HasRetouchMedia Trait

Add to any Eloquent model (or Atelier block) to access rendering helpers. Ensure the field is cast to array.

Rendering Methods

URL Access

Srcset Attributes (Manual)

Returns srcset="..." sizes="..." src="..." attributes for manual <img> construction.

Graceful Degradation

All methods handle missing conversions, legacy string paths, and null data without throwing exceptions. getPicture() falls back to a simple <img>, getSrcset() returns an empty string, and getImageWithSrcset() falls back to the original URL.

See Responsive Images for detailed usage.

Attribution

ChambreNoir stores photographer credit and portfolio link alongside image data.

Enable in Form

This adds "Credit" and "Portfolio Link" fields below the upload component.

Requirement Control

Display in Templates

Attribution Methods

Gallery System

ChambreNoir ships a full gallery management system built on top of three additional tables. Galleries are managed through a dedicated Filament resource, attached to any Eloquent model via a polymorphic pivot, and rendered on the frontend via either raw Blade helpers or the included Atelier block.

Migrations

This creates galleries, gallery_images, and galleryables tables.

Add the Relationship to Your Model

GalleryPickerField writes to a polymorphic galleryables pivot. Add the relationship to any model that will hold gallery attachments:

Attach Galleries in a Form

By default only active (published) galleries are shown. Options:

Render in Blade

Atelier Block

If Atelier is installed, a GalleriesBlock is registered automatically. It supports grid and carousel display, combined or tabbed multi-gallery modes, and an optional lightbox — all driven by Alpine.js with no additional dependencies.

See Gallery System for the full reference.

Artisan Commands

Make Conversion

Generates app/BlackpigCreatif/ChambreNoir/Conversions/ProductImageConversion.php extending BaseConversion with a scaffolded define() method and responsive config.

Regenerate Conversions

Regenerate image conversions across models, Atelier blocks, and Sceau SEO data:

Configuration

Published to config/chambre-noir.php.

Environment variables:

File Storage Structure

Integration with Atelier

ChambreNoir is designed as a companion to Atelier. Use RetouchMediaUpload in block schemas and HasRetouchMedia on blocks:

In block templates:

Image cleanup for block attributes is handled automatically by Atelier's BlockManager via ImageCleanupService.

Integration with Sceau

ChambreNoir's regeneration command supports Sceau SEO images. Use --seo to regenerate Open Graph and social sharing images managed by Sceau.

License

MIT. See LICENSE.md.

Credits

• Blackpig Creatif