README

Per-request data persistence lifecycle for PHP microservices. Automatic transaction management when attached to a kislayphp/core App — begin on request start, commit or rollback on request end.

Part of the KislayPHP ecosystem.

✨ What It Does

kislayphp/persistence provides a persistence runtime that integrates with kislayphp/core's request lifecycle hooks. Attach it to your App and every request gets automatic transaction management — begin on start, commit on success, rollback on exception.

<?php
Kislay\Persistence\Runtime::attach($app);  // that's it

Every request now has a clean transaction scope. No manual begin/commit/rollback per handler.

Fixed 2026-08-12: this automatic lifecycle is now genuinely implemented and verified against a real database - previously attach()'s request-start hook never actually called beginTransaction(), and DB::insert()/update()/delete() never participated in any per-request transaction at all (always ran in bare autocommit), so a thrown exception left already-written rows committed regardless. Now: the first write (insert/update/delete, not select) within a request auto-begins a transaction if one isn't already open, and Core's onRequestEnd hook tells the cleanup step whether the request ended in error, so it commits on a clean return and rolls back on an uncaught exception - confirmed with a real sqlite database, not just by reading the code.

pie install kislayphp/persistence

Enable in php.ini:

extension=kislayphp_persistence.so

🚀 Quick Start

Automatic Transaction Per Request

<?php
$app = new Kislay\Core\App();

// Attach persistence — handles begin/commit/rollback per request automatically
Kislay\Persistence\Runtime::attach($app);

$app->post('/api/orders', function($req, $res) {
    $data = $req->getJson();

    // Transaction is already open — just write your business logic
    $orderId = DB::create('orders', $data);
    Inventory::decrement($data['product_id'], $data['qty']);
    Email::queue('order_confirmation', $data['email']);

    $res->json(['order_id' => $orderId], 201);
    // Transaction commits automatically on clean return
    // Transaction rolls back automatically on exception
});

$app->listen('0.0.0.0', 8080);

Manual Usage

<?php
$persistence = new Kislay\Persistence\Runtime();

$persistence->begin();

try {
    $id = DB::insert('users', $data);
    Log::write('user_created', $id);
    $persistence->commit();
} catch (\Throwable $e) {
    $persistence->rollback();
    throw $e;
}

📖 Public API

namespace Kislay\Persistence;

class Runtime {
    public function __construct();
    public static function attach(Kislay\Core\App $app): void;  // per-request auto lifecycle
    public function begin(?string $connectionName = null): bool;
    public function commit(): bool;
    public function rollback(): bool;
    public function isActive(): bool;
}

Fixed 2026-08-12: these four instance methods previously didn't exist on the compiled extension at all (every call in "Manual Usage" above threw "Call to undefined method") - Runtime was static-only. Now real, backed by the same begin/commit/rollback primitives the working DB::transaction()/Runtime::transaction() static API already used correctly. begin()'s optional $connectionName selects a named connection (same default-connection behavior as DB::connection()) - omit it for the default connection, matching the "Manual Usage" example above exactly.

Legacy aliases: KislayPHP\Persistence\Runtime

🔗 Ecosystem

core · gateway · discovery · metrics · queue · eventbus · persistence

📄 License

Apache License 2.0 · Full Docs