[RFC] [DISCUSSION] ext/gd 2.4 — codec sync, Gd\* OOP API, 2D vector/canvas

Hi internals,

I'd like to open discussion on the ext/gd 2.4/php 8.6 RFC:

https://wiki.php.net/rfc/ext-gd-2.4

1. Codec sync and correctness. libgd has drifted a long way from
   what's bundled in php-src. This brings it back in line: every codec
   run against its upstream compliance corpus, with real correctness
   fixes landing as a result (color matching, FreeType bounding
   box/baseline for angled text). New codecs: QOI, JPEG XL, UltraHDR.
   Existing ones gain what they were missing: GIF animation read/write,
   multi-page TIFF, full WebP animation, PNG option exposure, JPEG
   reader/writer options, raw metadata (EXIF/XMP/ICC/IPTC) read/write.

2. A new Gd* OOP surface, additive alongside the existing procedural
   API. New methods land directly on GdImage (scale(), rotate(),
   transform(), composeFrom(), saveTo(), etc.), but every existing
   procedural function (imagecreatetruecolor(), imagejpeg(), ...) keeps
   its current signature and behavior unchanged, so legacy code isn't
   affected and can be freely mixed with the new methods since both
   operate on the same GdImage object. Each codec follows the same shape:
   Codec::fromFile/fromString/fromStream and toFile/toString/toStream, an
   immutable Info object, and ReadOptions/WriteOptions value objects
   designed to accept new options without breaking BC. Anim/multi-page
   formats get a streaming Reader/Writer instead of loading everything
   into memory.

3. A new 2D vector/canvas API on top of FreeType's rasterizer:
   gradients, the full Cairo compositing operator set (correct unbounded
   operator and premultiplied alpha semantics), save/restore state stack.
   Draws directly into an existing truecolor GdImage's buffer, no copy
   in/copy out, so it interleaves with legacy drawing calls on the same
   image.

The facade across codecs (fromFile/fromString/fromStream,
toFile/toString/toStream) and the value object options aren't just a
style choice, they're what makes the rest of the roadmap possible
without redesigning the API surface later. New internal image formats
(planned for 2.5/3.x: true 32bit ARGB, floating point buffers for HDR)
slot into the same facade instead of forcing a parallel API
(imagecreatetruecolor/palette now f.e.). New codecs follow the
identical pattern by construction (all the imagecreatefrom*/or
image<codec> with different options etc).

And the fluent, chainable method style on GdImage (or/and Gd\Image
later) is built so a future streaming/pipeline mode drops in as a
single new entry method feeding the same chain, not a separate API to
learn. This is a deliberate design constraint of the RFC, not an open
question.

Implementation: https://github.com/pierrejoye/php-src-syncgd
libgd only sync already merged in php-src as a separate PR:
https://github.com/php/php-src/pull/22532

This is a discussion thread, not yet a vote. Feedback on scope and
anything in the stubs is very welcome.

Discussions open for 14 days, until 2026/08/01.

Implementation is almost fully complete. I was thinking of adding and
exposing a quantization method as well so users can more easily select
which quantization mode to use (nnquant, legacy f.e.).

I added links to the stubs, I tried to have them in the RFC but it
became not very readable and too lengthy without bringing necessarily
more value in the RFC itself. Happy to add them back if desired (maybe
at the end).

Doing some cleaning and I will create the PR as well before Monday. A
first PR, which took a long time to get approved. I merged myself a
few days ago. Most of the ext/gd/libgd sync is in place already (full
BC but 2 fixes, see the link to the PR in the rfc).

Thanks,

Pierre

@pierrejoye