PHPackages                             tobento/service-picture-generator - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Image & Media](/categories/media)
4. /
5. tobento/service-picture-generator

ActiveLibrary[Image & Media](/categories/media)

tobento/service-picture-generator
=================================

Responsive picture generation workflow for PHP applications, including queueing, storage, and fallback handling.

2.0.1(4mo ago)0131MITPHPPHP >=8.4

Since Feb 19Pushed 4mo agoCompare

[ Source](https://github.com/tobento-ch/service-picture-generator)[ Packagist](https://packagist.org/packages/tobento/service-picture-generator)[ Docs](https://www.tobento.ch)[ RSS](/packages/tobento-service-picture-generator/feed)WikiDiscussions 2.x Synced today

READMEChangelog (2)Dependencies (15)Versions (3)Used By (1)

Picture Generator Service
=========================

[](#picture-generator-service)

The **Picture Generator Service** provides a powerful, framework-agnostic system for generating responsive images and `` 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 `` elements that work in any PHP framework or templating system.

Key Features
------------

[](#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 `` 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
-----------------

[](#table-of-contents)

- [Getting Started](#getting-started)
    - [Requirements](#requirements)
- [Documentation](#documentation)
    - [Workflow](#workflow)
    - [Basic Usage](#basic-usage)
    - [Creating Picture Generator](#creating-picture-generator)
    - [Picture Definitions](#picture-definitions)
    - [Clearing Generated Pictures](#clearing-generated-pictures)
    - [Console](#console)
        - [Picture Clear Command](#picture-clear-command)
    - [Using the App Ecosystem](#using-the-app-ecosystem)
    - [Framework Integration Notes](#framework-integration-notes)
- [Credits](#credits)

---

Getting Started
===============

[](#getting-started)

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

```
composer require tobento/service-picture-generator

```

Requirements
------------

[](#requirements)

- PHP 8.4 or above

Documentation
=============

[](#documentation)

Workflow
--------

[](#workflow)

When you [display a picture](#display-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 `` or `` 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

[](#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
-----------

[](#basic-usage)

Once you have [created the Picture Generator](#creating-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

[](#example-using-a-named-definition)

Named definitions allow you to reuse picture configurations across your application.
See the [Picture Definitions](#picture-definitions) section for how to register them.

```