Skip to content

The winter_boot Native Extension

Winter Boot ships a small native extension, winter_boot, alongside the framework. It provides native AOP: aspect attributes and #[Async] methods work without any generated proxy classes. The extension is pre-installed and enabled in the Winter Boot runtime image.

Bean methods carrying aspect attributes (caching, transactions, custom aspects) and #[Async] methods are intercepted directly in the runtime — no subclass is generated, so final classes can carry advice too. (final methods are still rejected by attribute validation.) Nothing changes in application code: the same attributes, the same aspects, the same begin/commit/failed sequence. #[Async] calls still run in the background pool and return null to the caller; the queue records the real method name.

Behavior to be aware of:

  • A value supplied through stopExecution() (for example a #[Cacheable] hit) must match the method’s declared return type exactly — a mismatch throws TypeError instead of being coerced. Every return-type form is checked like the engine does: nullable and union types (?Dto, array|ResponseEntity, string|false), intersection and DNF types, callable, iterable, and static (the called class). An int is still accepted for float.
  • Aspect attributes on static methods are not supported (TypeError).
  • An explicit parent:: call to a method that itself carries advice runs that advice. Advice never fires for methods without attributes.
  • On controllers, the dispatcher runs the advice of request-mapping endpoints directly (see AOP on controllers).

The extension source ships in the framework package (vendor/suvera/winter-boot/php-ext/). See Installation for build steps, and PHP Extensions for known limits (JIT, Xdebug).