Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Release Notes

Support Policy

Sukarix is currently supported for PHP 8.4+.

Released versions

v0.4.0

🚀 Features & Improvements

  • Version Number: 0.4.0
  • Release Date: 2026-08-16
  • General Overview: Adds a Redis-backed queue service for pipeline workloads, a HasQueue behaviour to consume it, and optional coloured console logging. The release is additive — no existing API changed, so upgrading from v0.3.2 requires no application changes.

Changes

  • Queue Service (sukarix): New Sukarix\Queue namespace providing QueueService, a Redis-backed FIFO queue for passing work between pipeline stages. It adds membership-based deduplication (pushing an already-queued payload is a no-op) and per-item attempt counters on top of a Redis list. Enqueue and dequeue are executed as Redis Lua scripts, so a worker terminated mid-operation can never leave the list and the membership set disagreeing — an item is either fully queued and tracked, or neither. The queue counts attempts but intentionally owns no retry policy: deciding when a failing item is retried or parked stays with the application. See Queues.
  • Queue Logging (sukarix): New QueueProgressLogger emitting structured queue events (start, progress, completion, throughput, batch progress, per-item add/remove, warnings and errors) with a machine-parsable context array. Item previews are generic by design — an array is reported as array[3], never with its values — so payload contents never leak into logs. Applications can route queue telemetry elsewhere by registering a subclass under the queue.progress_logger Injector alias; a service that does not extend QueueProgressLogger is rejected with an \UnexpectedValueException.
  • HasQueue Behaviour (sukarix): New behaviour trait exposing the resolved queue service as a typed $queueService property. Resolution is strict by design: constructing a consumer without a registered queue service throws a \LogicException naming the class, and a service that does not extend QueueService is rejected with an \UnexpectedValueException. This surfaces a misconfiguration at boot rather than at the first queue call, where a null member access would point at the wrong place.
  • Console Logging (sukarix): LogWriter gained an optional standard-output handler enabled with log.console = true, intended for CLI applications. When bramus/monolog-colored-line-formatter is installed the output is coloured per level, otherwise a plain stream is used. The file handler remains active, so console output is added rather than substituted. See Logging.
  • Redis Connection Timeout (sukarix): The queue honours redis.timeout (default 2 seconds) and throws \RedisException when the connection cannot be established, so a misconfigured worker fails immediately instead of part-way through a run.
  • Documentation: Added a Queues page. Rewrote the Behaviours page to list every available trait with the property it injects and its visibility, documenting that HasAccess and HasEvents expose a private property that subclasses cannot read. Corrected its example, which called a non-existent $this->log->write() instead of the $this->logger Monolog instance the LogWriter trait actually provides. Expanded Logging with the logger API, log.level and the new log.console setting. Added Queues to the feature list.

v0.3.2

🐛 Bug Fixes

  • Version Number: 0.3.2
  • Release Date: 2026-08-04
  • General Overview: Bug-fix release addressing cache, JSON encoding, and documentation accuracy issues found via static analysis.

Changes

  • HasCache::remember() (sukarix): Cache::get() returns false both on a cache miss and when the stored value is legitimately false, so remember() could never recognise a cached falsy value as a hit and recomputed it on every call. Switched to Cache::exists() to distinguish a real hit from a miss. The accompanying ResponseTest was rewritten to exercise the trait directly (the previous test asserted hardcoded literals against themselves) and a regression test for the falsy-value case was added.
  • Model::__construct() PHPDoc (sukarix): Corrected the @param tags, which inaccurately claimed $db, $table and $fluid must always be null. They mirror Cortex’s constructor and accept object, string and bool respectively; the wrong annotations caused PHPStan to flag the subsequent null-check as dead code.
  • TestScenario::postJsonData() (statera): The method declared a string return type but json_encode() can return false on failure, which under strict_types would throw a TypeError instead of a clear JSON error. Now passes JSON_THROW_ON_ERROR, matching the convention already used elsewhere in the class.
  • TestScenario::run() cleanup (statera): Removed an orphaned @var CodeCoverage $coverage docblock and its accompanying use statement left over from a prior refactor; they no longer corresponded to any variable in the method.

v0.3.1

🚀 Features & Improvements

  • Version Number: 0.3.1
  • Release Date: 2026-07-18
  • General Overview: Statera migration, trait initialization refactor, cursor-based pagination, cache helpers, and open-source readiness.

Changes

  • PHPUnit Removal: Dropped phpunit/phpunit and phpunit/php-code-coverage from require-dev and removed phpunit.xml.dist. The framework’s InjectorTest was converted from a PHPUnit TestCase to a Statera TestScenario using expect() assertions. Code coverage is now provided transitively by Statera’s own phpunit/php-code-coverage dependency.
  • Statera Dependency: Added sukarix/statera to require-dev so the framework uses its own testing kit for its test suite. Statera remains an optional, standalone package for applications.
  • Test Runner: Added tools/statera.php and test infrastructure (tests/src/Test/, tests/src/Suite/) to run the framework’s tests via Statera.
  • Statera Package: Declared the previously-undeclared sukarix/sukarix runtime dependency in sukarix/statera’s composer.json (Statera uses Sukarix\Utils\CliUtils and Sukarix\Utils\Time).
  • Trait Initialization: Moved Processor::initialize() from Tailored::instance() to class constructors. Each Tailored subclass must now call Processor::instance()->initialize($this) in its constructor. The Helper base class does this automatically.
  • LogWriter: Added initLogger() backward-compatible alias for initLogWriter().
  • TestCase: Removed final keyword to allow subclassing in application test suites.
  • Action: Added Processor import. Made $view, $argv, $headerAuthorization, and $templatesDir nullable to prevent uninitialized typed property errors.
  • MailSender: smtpSend() and generateId() changed from private to protected for extensibility.
  • Assets: Constructor now calls parent::__construct() for proper trait initialization.
  • TestScenario: loadResult() handles missing template files gracefully.
  • Cursor Pagination: Added Response::cursor() for cursor-based API pagination — stable under concurrent inserts, efficient on large datasets. Returns { field, limit, has_more, next } structure.
  • Cache Remember: Added HasCache::remember() for get-or-set cache pattern and HasCache::forget() for invalidation.
  • Paginate Fix: Response::paginate() now casts pages to int (was float from ceil()).
  • Open Source: Added AGENTS.md with contribution guidelines and AI usage transparency across all repositories.

v0.2.0

🚀 Features

  • Version Number: 0.2.0
  • Release Date: 2025-01-20
  • General Overview: Added CSRF protection, enhanced session management, and improved validation.

v0.1.0

🚀 Introduction

  • Version Number: 0.1.0
  • Release Date: 2024-06-14
  • General Overview: First version of the Sukarix Framework.