Phalcon v5.19.0 / v6.0.0beta7 Released

Phalcon v5.19.0 has been released! v6.0.0beta7 also released.

Bug fixes/changes

Several bugs have been fixed. The one to draw your attention to is the Phalcon\Filter\Validation\Validator\Callback validator. Previously the callback closure was bound to the validator, so $this inside it pointed at the validator rather than at the object where you wrote the closure. That binding is gone - $this now behaves the way PHP does natively. If you were calling $this->setTemplate() inside a callback, declare a second parameter and call $validator->setTemplate() instead. Check the documentation and/or changelog for the details.

Additionally, corrections to the Phalcon\Filter\Validation\Validator\StringLength validators to correctly include the upper/lower limits.

Fixed also some potential type errors in Html\Helper\Input and some not so obvious bugs relating to the Image namespace. Those were primarily undetected because of the particular edge cases that were never tested or tested against incorrect data. We managed to get proper samples of images with specific alpha/frames/animation etc. and with that testing harness we were able to fix the output of specific methods. More in the changelog below.

Worth calling out one of those: watermark() silently did nothing for any opacity below 100, so if your watermarks never showed up, this release fixes it. Animated GIFs also keep all their frames now through reflection(), render() and save().

Additions

Phalcon\DataMapper now is events aware. For those that use the component, you can now attach the events manager and start listening to the events fired. Useful for metrics, additional operations, flows etc.

Alignment and tooling

The final alignment task between cphalcon and phalcon is underway. Every namespace, every file is checked against each other to ensure that they are the same. We even carry the mixed types in certain properties, because v5 has that, even though for v6 and the PHP land one could for argument’s sake use array|string. The goal is to have those two 100% aligned. Our new tool Quill is helping a lot so that task becomes a bit easier. More on Quill on an upcoming blog post.

The remaining task is to get PHPStan to max. Granted, this can only happen in v6, since it is a PHP tool, but we are running it on max for each namespace with two goals:

identify potential misalignments with v5
offer proper shapes to the community on what components expect and produce

For the first one, this exercise alone identified several bugs (example the Image bugs listed in the changelog) which were fixed. For the shapes, we introduced *Types interfaces that live in the Contracts top namespace. Developers can import those shapes in their applications if they need to.

Thanks

As always, thank you to everyone who reported an issue, opened a pull request, or tested a build before it shipped.

Changelog

5.19.0 (2026-08-19)

Tools

Zephir 1.2.0 (a09648c)

Changed

Changed Phalcon\Filter\Validation\Validator\Callback to stop binding the callback closure to the validator; to set the message from inside the callback (#17255), declare a second parameter and call $validator->setTemplate() instead of $this->setTemplate() #17499 [doc]
Changed Phalcon\Filter\Validation\Validator\StringLength, Phalcon\Filter\Validation\Validator\StringLength\Min and Phalcon\Filter\Validation\Validator\StringLength\Max to treat min and max as inclusive when the included option is not set, matching the class documentation and the behavior before 5.7.0; set included to false for exclusive boundaries #17503 [doc]

Added

Added includedMinimum and includedMaximum as aliases of the included option in Phalcon\Filter\Validation\Validator\StringLength\Min and Phalcon\Filter\Validation\Validator\StringLength\Max, so the option names of the StringLength container also work on the two validators directly. included has precedence if you set both #17503 [doc]
Added lifecycle events to the DataMapper connections, fired through Phalcon\Events\Manager and named on the new Phalcon\DataMapper\Pdo\Events class: dm:beforeConnect/dm:afterConnect, dm:beforeDisconnect/dm:afterDisconnect, dm:beforePerform/dm:afterPerform, dm:beforeExec/dm:afterExec, dm:beforeQuery/dm:afterQuery, dm:beforeBeginTransaction/dm:afterBeginTransaction, dm:beforeCommit/dm:afterCommit, dm:beforeRollBack/dm:afterRollBack and dm:connectionLost. prepare() has no events of its own because perform() calls it, which would report one operation twice. The connect, disconnect and connectionLost events report a change of the connection state and fire whichever method causes it, so an automatic reconnect reports the lost connection and the new one. Phalcon\DataMapper\Pdo\Connection\Decorated does not fire the connect and disconnect events because it never connects and cannot disconnect. #17501 [doc]
Added getEventsManager() and setEventsManager() to Phalcon\DataMapper\Pdo\Connection\AbstractConnection, and therefore to Phalcon\DataMapper\Pdo\Connection and Phalcon\DataMapper\Pdo\Connection\Decorated, and to Phalcon\DataMapper\Pdo\ConnectionLocator, which gives its events manager to every connection it returns, including the ones it builds on demand. The two classes now carry the Phalcon\Contracts\Events\EventsAware contract. Phalcon\DataMapper\Pdo\Connection\ConnectionInterface is unchanged, so classes that implement it directly keep working #17501 [doc]
Added Phalcon\DataMapper\Pdo\Exception\OperationCancelled, thrown when a listener cancels one of the before* events. The operation does not run. To cancel, a listener must call $event->stop() and also return false: stop() alone returns the value of the listener, which the connection cannot tell apart from “no listeners”, and false alone is replaced by any later listener that returns a value while the events manager is not in stopOnFalse mode. The after* events are not cancellable #17501 [doc]

Fixed

Fixed Phalcon\Filter\Validation\Validator\Callback rebinding $this in callback closures; the validator is now passed as a second argument to closures that declare one #17499 [doc]
Fixed Phalcon\Filter\Validation\Validator\StringLength\Min and Phalcon\Filter\Validation\Validator\StringLength\Max rejecting a string with a length exactly equal to min or max when the included option was not set, a regression introduced in 5.7.0 #17503 [doc]
Fixed Phalcon\Filter\Validation\Validator\StringLength giving the includedMinimum/includedMaximum and messageMinimum/messageMaximum option of one boundary to the validator of the other boundary #17503 [doc]
Fixed Phalcon\Html\Helper\Input\Generic, Phalcon\Html\Helper\Input\Checkbox and Phalcon\Html\Helper\Input\Radio throwing an error when you build them directly without a Phalcon\Html\Helper\Doctype. #17507 [doc]
Fixed Phalcon\Image\Adapter\Imagick::processReflection() applying the reflection to the first frame only of a multi-frame image, because the first two loops changed the reflection clone but moved the frame cursor of this->image #17510 [doc]
Fixed Phalcon\Image\Adapter\Imagick::background(), reflection(), text() and watermark() discarding any opacity below 100, and sharpen() rounding its amount down, because the division by 100 was stored back in the integer parameter; watermark() left the image unchanged for every opacity except 100 #17510 [doc]
Fixed Phalcon\Image\Adapter\Imagick never coalescing the frames of a GIF, because the constructor compared getImageType(), an Imagick IMGTYPE_* value, against IMAGETYPE_GIF; the width and the height of an animated GIF now describe the canvas instead of whichever sub frame the cursor was on #17510 [doc]
Fixed Phalcon\Image\Adapter\Imagick::render() returning the current frame alone for a GIF, and save() failing with no encode delegate for this image format after an operation that rebuilds the image; both now mark every frame with the format, which setImageFormat() applies to the current frame only #17510 [doc]