Review main Abandoned

94946[BUGFIX] Route GifBuilder through a pure-GD canvas

Garvin Hicking CR 0 V -1 Nightmare +3409 −852 updated 08/10/26, 08:08

Commit message

This patch is 100% Claude Opus AI. Just for discussion.

Prompt:

I have created two branches: variant1 and variant2.

These cover a change to the TYPO3 Core graphical functions.

Variant 2 has a patch where specifically @typo3/sysext/core/Classes/Imaging/GraphicsCanvas.php works as a "working document" variation. It combines a stateful object with methods that applies variations (image operations) on it.

Variant 1 implements this with a immutable value object instead. It carries a lot of methods still around that require to instatiate a fresh object everytime when a "transformation" is applied.

Now I want you to do two things in this order:

1. Create a "variant 3" that should do this: Seperate all image operations on the value object into an own service, like a "GraphicalCanvasOperationsService". So that the GrahpicalCanvas itself is pure, only contains initial creation options and serialisation / writing or whatever is contained in current code. The Service then is what should carry the actual operations like "enableBlending", "enableAlpha", remapping colors, ellipses, text rendering and so forth. Each method should uniquely receive the GraphicalCanvas object as the first parameter, and apply the modifications to it.

2. After this variant is successfully implemented, give me an evaluation about the pros and cons of each variant, and give a suggestion based on the TYPO3 heritage, architecture and future maintenance on which variant would be preferred, and why. Properly weigh every pro and con and make a concise and precise list of them as an "executive summary" at the end.

Make no mistakes.

Response:

  - GraphicsCanvas is now a pure container: creation, format detection, file loading, dimensions,
  resource()/replaceResource(), duplicate(), saveToFile(). No drawing logic.

  - GraphicsCanvasOperationsService (new, stateless, DI-registered) holds every operation — alpha/blending, colour
  allocation, drawing primitives, text, compositing, resize/crop, levels, filters, geometric distortions. Each method
  takes the canvas first and mutates in place; size-changing ops swap the backing image via replaceResource().

  - Constructor-injected into GifBuilder (with a new default so new GifBuilder() still works) and EnvironmentController
  (plus its ServiceProvider factory).

Variant 1 — immutable value object (each call returns a new canvas; you must reassign)
$canvas = GraphicsCanvas::load($im)
    ->blur(2)
    ->crop($b, $b, $w, $h)     // each step deep-copies the whole GdImage
    ->inputLevels(0, 153)
    ->outputLevels(0, 128);
$im = $canvas->resource();     // live image — mutating it silently mutates $canvas

Variant 2 — mutable working document (fluent, in place, zero-copy)
$canvas = GraphicsCanvas::load($im);
$canvas->blur(2)
    ->crop($b, $b, $w, $h)
    ->inputLevels(0, 153)
    ->outputLevels(0, 128);

Variant 3 — pure canvas + operations service (explicit, in place, zero-copy)
$canvas = GraphicsCanvas::load($im);
$this->ops->blur($canvas, 2);
$this->ops->crop($canvas, $b, $b, $w, $h);
$this->ops->inputLevels($canvas, 0, 153);
$this->ops->outputLevels($canvas, 0, 128);

Variant 1 — immutable readonly value object

Pros
- Value semantics: a canvas reference never changes under you; easy to reason about in isolation.
- Fluent chaining reads naturally; tracked GD flags (blending/alpha/transparent/interlace) are modelled explicitly rather than as hidden resource state.
- Aligns with the modern TYPO3 DTO style (ImageResource, ImageProcessingInstructions).

Cons
- Performance: every pixel-mutating op runs cloneImage() — a full imagecreatetruecolor + imagecopy of the whole image. A GifBuilder render chains dozens of ops (per-letter outline is 8–16 makeText passes); this multiplies allocations and copies on the hot path.
- The immutability is leaky and unenforceable: resource() returns the live \GdImage, and its own docblock says "treat as frozen." GifBuilder pervasively passes raw \GdImage by reference (imagettftext, imagecopyresized) and mutates it — so the guarantee the whole design pays for doesn't actually hold end-to-end.
- Most ceremony: withMutatedImage/withReplacedImage/applyImageState machinery; largest, most novel class for a maintainer to learn.
- Fights the grain of GD, which is an in-place C API.

Variant 2 — mutable working document

Pros
- Matches GD exactly: in-place, zero-copy, no per-op allocations — best raw performance and lowest memory.
- Fluent $this chaining; minimal ceremony; smallest diff from legacy GifBuilder thinking.
- One import, one object — trivial call sites.

Cons
- God object: ~1,100 lines mixing state, I/O and every algorithm; the class the @internal note explicitly says must "be reshaped once image processing is split into per-processor strategies."
- Operations aren't independently injectable/mockable/extensible; testing an operation drags in the whole canvas.
- Aliasing surprises: load($im) wraps a shared image, so two canvases can mutate each other; mutation-by-reference is easy to misuse.

Variant 3 — pure canvas + operations service

Pros
- Single Responsibility: a small data/IO canvas + a stateless operations service — the exact "split into strategies" direction the code comments promise.
- Idiomatic TYPO3: a stateless, autowired, constructor-injected service; the operations layer is now mockable, decoratable, and extensible (e.g. an alternative/GraphicsMagick backend, or event-driven effects) without touching the data object.
- Keeps variant 2's performance: mutation is still in place and zero-copy.
- Operations are testable in isolation against a trivially-constructed canvas (see GraphicsCanvasOperationsServiceTest).

Cons
- Verbosity: no fluent chaining; $this->ops->op($canvas, …) repeats the canvas argument at every call site.
- The "pure" canvas still needs an @internal replaceResource() seam for size-changing ops — a small, deliberate crack in the purity.
- Two collaborators to hold, and DI wiring at every construction site (a new default and a ServiceProvider edit were needed).

Recommendation — for TYPO3 heritage, architecture and maintenance

Prefer Variant 3, with Variant 2 as the acceptable fallback. Variant 1 is the weakest fit here.

Why:
- Heritage: GifBuilder is procedural code over a mutable \GdImage passed by reference, and GD is an in-place API. Variants 2 and 3 honour that; variant 1 imposes value semantics the underlying library and the surrounding caller actively defeat — and pays a full-image copy per operation to do so.
- Architecture: TYPO3's spine is Symfony DI with small, stateless, injectable services. Variant 3 is that pattern; it turns the "God canvas" into a data object plus a service that can be decorated/replaced — which is precisely what the @internal … will be reshaped into per-processor strategies note anticipates. Variant 1's value-object idiom is reserved in TYPO3 for small immutable DTOs, not multi-megabyte pixel buffers.
- Maintenance: Variant 3 gives the best testability and extensibility (operations isolated, mockable, backend-swappable) at no runtime cost versus variant 2. Its only price is call-site verbosity — cheap and mechanical compared to variant 1's performance overhead and false immutability, or variant 2's un-splittable 1,100-line class.

If absolute minimum verbosity and churn were the only goals, Variant 2 is the pragmatic pick. But for a core subsystem explicitly slated to be split into strategies, Variant 3 is the architecturally correct stepping stone.

Executive summary

┌────────────────────────────────┬────────────────────────┬─────────────────────────┬──────────────────────────────┐
│                                │  V1 Immutable value    │   V2 Mutable working    │   V3 Canvas + operations     │
│                                │         object         │        document         │           service            │
├────────────────────────────────┼────────────────────────┼─────────────────────────┼──────────────────────────────┤
│ Performance                    │ ✗ full image copy per  │ ✓ zero-copy in place    │ ✓ zero-copy in place         │
│                                │ op                     │                         │                              │
├────────────────────────────────┼────────────────────────┼─────────────────────────┼──────────────────────────────┤
│ Memory                         │ ✗ highest              │ ✓ lowest                │ ✓ lowest                     │
├────────────────────────────────┼────────────────────────┼─────────────────────────┼──────────────────────────────┤
│ Immutability guarantee         │ ✗ leaky via resource() │ n/a                     │ n/a                          │
├────────────────────────────────┼────────────────────────┼─────────────────────────┼──────────────────────────────┤
│ Call-site ergonomics           │ ✓ fluent (needs        │ ✓✓ fluent in place      │ ✗ verbose (ops, canvas, …)   │
│                                │ reassign)              │                         │                              │
├────────────────────────────────┼────────────────────────┼─────────────────────────┼──────────────────────────────┤
│ Single Responsibility          │ ✗ ops + state + flags  │ ✗ God object (~1,100    │ ✓ data vs behaviour split    │
│                                │ in one                 │ lines)                  │                              │
├────────────────────────────────┼────────────────────────┼─────────────────────────┼──────────────────────────────┤
│ Testability of ops             │ ~ coupled to canvas    │ ~ coupled to canvas     │ ✓ isolated & mockable        │
├────────────────────────────────┼────────────────────────┼─────────────────────────┼──────────────────────────────┤
│ Extensibility (swap/decorate   │ ✗                      │ ✗                       │ ✓ via DI                     │
│ backend)                       │                        │                         │                              │
├────────────────────────────────┼────────────────────────┼─────────────────────────┼──────────────────────────────┤
│ Fit with GD's in-place API     │ ✗ fights it            │ ✓ matches               │ ✓ matches                    │
├────────────────────────────────┼────────────────────────┼─────────────────────────┼──────────────────────────────┤
│ Fit with TYPO3 DI conventions  │ ~ DTO-like             │ ~ service-like,         │ ✓✓ idiomatic stateless       │
│                                │                        │ monolithic              │ service                      │
├────────────────────────────────┼────────────────────────┼─────────────────────────┼──────────────────────────────┤
│ Wiring cost                    │ low                    │ low                     │ ~ DI at each call site + new │
│                                │                        │                         │  default                     │
└────────────────────────────────┴────────────────────────┴─────────────────────────┴──────────────────────────────┘

Bottom line: V1 buys a clean mental model at a real per-operation copy cost and an immutability promise it cannot keep; V2 is the fast, minimal, legacy-shaped choice but concentrates everything in one class; V3 keeps V2's performance while delivering the SRP/DI/testability profile TYPO3 favours and the code's own roadmap points to — the recommended variant.

Commit message:

Variant 3: separate the GD image container from the operations that
act on it.

GraphicsCanvas becomes a pure image object — it owns creation, format
detection, file loading, dimension access, resource handling and
saving only. Every drawing, colour, text, compositing, level, filter
and geometric operation moves into the new stateless
GraphicsCanvasOperationsService. Each operation takes the canvas it
acts on as its first argument and mutates it in place; size-changing
operations swap the backing \GdImage through
GraphicsCanvas::replaceResource().

The service holds no state, so a single shared instance serves every
caller. It is registered for dependency injection and constructor-
injected into GifBuilder and the install tool EnvironmentController.
GifBuilder keeps a default instance so it can still be constructed
with "new" outside the container. Behaviour is unchanged: all GD unit
tests, the GifBuilder functional suite and the install tool image
tests continue to pass.

Review

  • Code review CR 0
  • Verified V -1
    • core-ci -1 CI

Issues 1

Files 39

Show 19 more files

Review log 23

  1. Garvin Hicking uploaded patch set 1 07/25/26, 19:08

  2. core-ci voted on patch set 1 V -1 07/25/26, 19:17 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/105401

  3. Garvin Hicking abandoned the change 08/10/26, 08:08