Download the PHP package tobento/service-picture-generator without Composer

Picture Generator Service

The Picture Generator Service provides a powerful, framework-agnostic system for generating responsive images and <picture> elements in PHP applications.
It enables developers to define reusable picture configurations, generate optimized image variants, and store metadata for fast retrieval - all without relying on URL-based transformations.

The service is designed to be secure, predictable, and fully decoupled from HTTP.
It supports synchronous and queued generation, integrates with any file-storage backend, and outputs standard HTML <picture> elements that work in any PHP framework or templating system.

Key Features

• Definition-based picture generation Create named picture definitions that describe breakpoints, formats, crops, and responsive strategies - reusable across your entire application.
• Secure, URL-free architecture No query parameters, no runtime transformations, and no exposure of private storage. All images are generated server-side using controlled definitions.
• Pre-generation & regeneration Generate images on upload, on demand, or via CLI commands. Regenerate all images when definitions change.
• Queue support Offload heavy image processing to background workers using a PictureQueueHandlerInterface.
• Metadata repository Store and retrieve picture metadata (JSON) for fast rendering of <picture> tags.
• Storage-agnostic Works with any StoragesInterface implementation (local, cloud, Flysystem, etc.).
• SEO-friendly static URLs All generated images use clean, human-readable paths without query strings or signatures. This results in stable, shareable URLs that search engines can index reliably and that remain consistent over time.
• PSR-compliant Uses PSR-7 streams and PSR-3 logging for maximum interoperability.

Table of Contents

• Getting Started
  • Requirements
• Documentation
  • Workflow
  • Basic Usage
  • Creating Picture Generator
  • Picture Definitions
  • Clearing Generated Pictures
  • Console
    • Picture Clear Command
  • Using the App Ecosystem
  • Framework Integration Notes
• Credits

  ---

Getting Started

Add the latest version of the picture generator project running this command.

Requirements

• PHP 8.4 or above

Documentation

Workflow

When you display a picture, the service checks whether the required images for the given path and definition already exist.

• If the images are not yet generated and queueing is enabled (default),
  a picture job is dispatched to the configured queue.
  The view immediately receives a lightweight fallback picture based on the original resource.

• If queueing is disabled (queue: false),
  the images are generated synchronously during the request and the final <picture> or <img> tag is returned immediately.

• Once the queued job finishes, all defined image variants are created and stored.
  Subsequent requests automatically render the fully generated picture.

This workflow ensures fast responses when using background processing, while still allowing on-demand synchronous generation when needed.

Fallback Images

If a picture cannot be generated immediately (for example, when queueing is enabled), a fallback image is returned:

• If the file has a public URL, the fallback uses that URL.
• If no public URL is available, a base64-encoded data URI is returned.
• If fallback creation fails (e.g., the file is not a valid image), a NullPictureTag is returned and a warning is logged.

Basic Usage

Once you have created the Picture Generator, you can use it to display responsive pictures based on a path, resource, and definition.

Within your view file, call the generate method and render the returned picture tag:

Example Using a Named Definition

Named definitions allow you to reuse picture configurations across your application.
See the Picture Definitions section for how to register them.

About allowPrivateStorage

Use this option when the image source is a private storage.
(For most cases, using a public storage as the image source is recommended.)

• false (default): private storages are not read and a NullPictureTag is returned.
• true: allow reading from private storage (useful for backend-only sources such as uploads or protected files).

Depending on your definition, the output may look like:

Using named definitions provides several advantages:

• You can crop images based on the definition
• You can define different picture sets per view theme

Example Using a Definition Instance

See the Picture Definition section for more details on defining picture configurations.

Example Using an Imager Resource

See Picture Creating - Create Picture From Resource for more information.

Creating Picture Generator

To use the picture generator, you first need to create the required components:
a PictureRepository, an optional PictureQueueHandler, and finally the PictureGenerator itself.

Private Storage Behavior

When generating pictures from private file storage, the behavior depends on the allowPrivateStorage and queue parameters:

Related Documentation

• Picture Service - Definitions
  Learn how to register and manage picture definitions

• Queue Service
  For configuring queues used for background image generation

• File Storage Service
  For configuring storages used for original and generated images

Queue Worker

If you use background image generation via the queue handler,
you may install the Console Service to run the queue worker:

See the Queue Service - Console for details on running the worker.

Unique Jobs

The queue handler uses unique jobs by default.
To enable unique job locking, the Queue Service requires a PSR-16 CacheInterface implementation.

You may use any PSR-16 compatible cache. For example, if you use a container and want a simple drop-in implementation:

See the Queue Service - Unique Parameter
for details on how unique job locking works and how to provide your own cache.

Warning:
If unique jobs are disabled or no cache is available, duplicate picture generation jobs may be queued and processed. This can lead to redundant work, increased queue load, and multiple workers generating the same images.

Logging

If a LoggerInterface is provided, the picture generator may log useful information such as picture generation steps, queue dispatching, or errors that occur during processing. Logging is optional and depends on the logger implementation you supply.

Picture Definitions

Picture definitions can be stored wherever you prefer.
You are free to organize them in any directory structure that fits your application.

A common convention is to place JSON definition files inside a dedicated folder, for example:

For a detailed explanation of how JSON-based definitions work, how they are structured, and how to load them, see the
Json Files Definitions section of the Picture Service documentation.

Clearing Generated Pictures

You can clear (delete) generated pictures either via the console command or directly through the PictureGenerator.

Using Console Command

See Picture Clear Command section.

Using Picture Generator

Console

Picture Clear Command

This package integrates with the Console Service to provide a command for clearing generated pictures.

Requirements

Example

To clear all generated pictures, run:

To clear generated pictures for specific definitions only:

Using the App Ecosystem

If you are building on the Tobento App Ecosystem, you may use the app-media package, which automatically configures the picture generator, queue worker, cache, and storages. In that case, no manual setup is required.

Framework Integration Notes

This package is framework-agnostic.
If you integrate it into a framework that provides its own queue or filesystem (e.g. Laravel, Symfony, etc.), you may need to implement small adapters:

• Queue Adapter Queue Service
  Implement Tobento\Service\Queue\QueueInterface to forward jobs to your framework's queue system.

• File Storage Adapter File Storage Service
  Implement Tobento\Service\FileStorage\StorageInterface to map your framework's filesystem to the storage abstraction used by this package.

These adapters are typically thin wrappers, as both interfaces are intentionally minimal.

Credits

• Tobias Strub
• All Contributors