Search by

Standalone modular PHP framework with durable flows, realtime and CVP interoperability

Package info

github.com/corevia-framework/corevia

Type:project

pkg:composer/corevia-framework/corevia

Statistics

Installs: 2

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v4.0.1 2026-11-21 18:48 UTC

README

Corevia logo

Corevia 4.0.1

A modular PHP 8.2+ framework for web applications, APIs, durable workflows, multi-tenant services and optional Python/AI and mobile integrations. Start without a database, Node.js, Python, Redis or Docker; enable only the capabilities your application needs.

V4 adds application composition, staged upgrades, migrations and testing helpers, tenant-aware adapters, account/audit tools, scheduling and outbox delivery, bounded telemetry and AI/offline-client contracts. Bootstrap, Tailwind and React auth starters ship prebuilt assets.

Supported release scope and test limits: read the V4 release notes, 20-workstream review, upgrade guide and unverified integrations and self-tests. Unavailable environments are explicitly deferred, not reported as passed. AI tool callbacks/processes require trusted code; they are not an OS sandbox.

The PHP core has no third-party runtime dependencies. CVP/1 and CVP/2 remain supported. V3 API compatibility and saved-state upgrade fixtures are retained; older tags remain available.

Setup

Requirements: PHP 8.2+ with JSON. The starter needs no database, Node.js, Python, Redis, or Docker.

Once corevia-framework/corevia is published on Packagist, create an application with:

composer create-project corevia-framework/corevia myapp "^4.0"
cd myapp
php corevia doctor
php corevia route:list
php corevia serve

This release prepares Packagist compatibility; registration and publication are separate maintainer actions. Until publication, use the source ZIP or Git installation below. Composer infers stable versions from Git tags; no custom repository is needed after Packagist publication.

Download the V4.0.1 source ZIP after release publication, extract it, and open a terminal in the extracted project directory. Or clone the release:

git clone --branch v4.0.1 https://github.com/corevia-framework/corevia.git myapp
cd myapp
composer install
php corevia serve

Open http://127.0.0.1:8081. Composer is recommended; the included loader also lets you start directly with php corevia serve when Composer is unavailable. Each fresh installation creates its own private signing key and runtime files on first use.

The development server is for local use. In production, point the document root at public/ and give the PHP process write access to private storage/; do not make the whole application world-writable. Configure settings through process environment variables and config/settings/. .env.example documents the variables; copying it to .env does not load them automatically. No database migration, account creation, email delivery or application hook runs during Composer installation.

Build your application in app/, routes/web.php, resources/views/, public/assets/, and config/settings/. The packages/ directory contains the framework and should normally stay unchanged. .gitignore excludes local/generated data; it does not prevent people from modifying files in their own copy.

Read Getting started, the web guide, and the database guide. The root project bundles all modules, SDKs, starter assets, examples and CLI test support. The optional split runtime/application distribution remains available separately; it is not required by the root project's Composer installation.

For a separate task tutorial, use the database-free learning project. Run php test-project/console.php serve and open http://127.0.0.1:8091 to create tasks and inspect each flow step. Its database guide explains how to switch task storage to PDO/MySQL later.

Requirements: PHP 8.2+ with JSON. PDO SQLite is optional for the checkout sample and persistence adapter. Composer is supported; the included PSR-4 loader also allows immediate local use. Node.js 22+ and Python 3.10+ are needed only for SDKs and cross-language tests.

composer install
php corevia doctor
php corevia flow:run checkout --input=examples/checkout.json --key=demo-checkout

The checkout creates a simulated payment and order in SQLite. Notification delivery intentionally fails, so its result is completed_with_warnings. Without a realtime process, event delivery also reports a warning. Corevia does not charge money or send email in this sample.

HTTP and realtime demo

Run these in separate terminals from the project directory:

php corevia realtime:start
php corevia serve

Open http://127.0.0.1:8081/demo.html. Click Run checkout to view step results and receive order.updated over WebSocket. The default listener uses port 8080 and authenticated local IPC on port 8082. Keep the realtime process running independently of PHP-FPM.

curl -X POST http://127.0.0.1:8081/checkout \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: checkout-example-1' \
  --data-binary @examples/checkout.json
php corevia flow:show <run-id>

To recover the notification service in the demo, create storage/notifications.online:

New-Item -ItemType File -Path storage/notifications.online
php corevia flow:retry <run-id> 5

On Unix, use touch storage/notifications.online. Indexes are zero-based: notification is step 5, broadcast is step 6. Retry executes only that failed non-critical step, with the same operation key; payment and order creation are preserved. Recover a broadcast warning after starting realtime with php corevia flow:retry <run-id> 6. Stop realtime gracefully with php corevia realtime:stop or SIGINT/SIGTERM on Unix.

Python integration

The sample uses a local fraud threshold by default to keep PHP-only setup simple. For the complete PHP → Python → WebSocket demo, set the worker settings in both the Python and PHP terminals before starting the servers:

$env:COREVIA_WORKER_TOKEN = 'choose-a-development-shared-secret'
$env:COREVIA_FRAUD_URL = 'http://127.0.0.1:8090/cvp'
python examples/python_worker.py

In another terminal with the same environment settings:

php corevia realtime:start

In a third terminal with the same settings:

php corevia serve

On Unix, export COREVIA_WORKER_TOKEN and COREVIA_FRAUD_URL instead. Use your installed Python executable if the python alias is unavailable. php examples/remote.php calls the Python ai.analyze action. Remote fraud calls report fraud_runtime: python in checkout state and preserve the flow trace ID. The worker's analysis action counts words and characters; it does not call an AI provider.

Architecture

HTTP / CLI / event / scheduled invocation
                 ↓
Module registry → Flow engine → Action runner → explicit result
                     ↓               ↓
                  RunStore       EventBus contract
                     ↓               ↓
                 PDO SQLite      realtime broadcaster → WebSocket clients

PHP RemoteAction ← JSON CVP/1 over HTTP → Python Worker
JavaScript / React Native ← HTTP + CVP/1 WebSocket → Corevia
Directory Responsibility
packages/core Container, module registry, actions, flows, state, events, validation, result/store/logging contracts
packages/http Routing, JSON, middleware, CORS, flow adapter, explicitly enabled action gateway
packages/protocol CVP/1 validation/serialization and timeout-bounded remote action calls
packages/persistence-pdo SQLite PDO run store, step logs, atomic idempotency reservations and retry locks
packages/realtime WebSocket frames/server, rooms, private authorization, heartbeat, authenticated local IPC
packages/cli Commands, diagnostics and generators
sdk/js, sdk/python Independent public protocol clients and external worker
app Orders, Payments, Notifications demo modules and idempotent demo ledger
protocol Shared schema and valid/invalid fixtures

Core never imports HTTP, PDO or realtime implementations. Modules register explicitly; registration is isolated and transactional in memory. Dependencies are booted first. A flow can only use actions owned by its module or explicitly declared dependencies. Duplicate IDs/public names, missing dependencies, disabled dependencies and cycles are reported per module. Unrelated healthy modules continue booting.

Runtime API

use Corevia\Core\{Corevia, Action, ExecutionContext, State, Flow, Module, ModuleContext};

final class Increment implements Action
{
    public function handle(State $state, ExecutionContext $context): State
    {
        $state->data['count'] = ($state->data['count'] ?? 0) + 1;
        return $state;
    }
}

final class CounterModule implements Module
{
    public function name(): string { return 'counter'; }
    public function dependencies(): array { return []; }
    public function register(ModuleContext $context): void
    {
        $context->actions(['counter.increment' => Increment::class]);
        $context->flows([
            Flow::define('count')->step('counter.increment')->critical(),
        ]);
    }
}

$app = Corevia::create(basePath: __DIR__);
$app->modules([CounterModule::class]);
$app->boot();
$result = $app->run('count', ['count' => 0], key: 'operation-1');

Steps accept a registered action name or registered action class. Class-based actions must still belong to the module/dependencies. State stores JSON-compatible data; subclass it for typed domain accessors, as in CheckoutState. Actions have a uniform State signature and may return the same state subtype or an ActionResult. Container bindings supply explicit dependencies; class constructors support recursive object autowiring.

Flow::define('example')
    ->step('cart.validate')->critical()
    ->step('payment.charge')->critical()->retry(2, delayMs: 100, exponential: true)
    ->step('email.send')->nonCritical()->retry(5)
    ->step('audit.write')->when(fn (State $s) => $s->data['audit'] ?? false);

retry(2) means one initial attempt plus two retries. Only failures explicitly marked retryable are retried. Delay doubles when requested, bounded to 30 seconds. Unexpected exceptions become ACTION_EXCEPTION, are logged without exception messages, and are not retried automatically. Failed attempts discard state mutations; actions must separately protect side effects with $context->operationKey('action.name'). External providers must honor those keys.

Critical failures stop the flow; non-critical failures allow later steps. Every run contains state snapshots, per-step status/timing/attempts, errors, trace/request IDs and timestamps. Final status is completed, completed_with_warnings or failed. Conditions may skip steps; condition exceptions fail the flow. running is an intermediate persisted status returned for a concurrent duplicate request.

Idempotency keys are scoped to flow name. Identical input returns the existing run; changed input yields IDEMPOTENCY_CONFLICT. The hash uses PHP's JSON representation of the input, including key ordering. Use the same payload representation for repeated calls. Persisted idempotency lasts until explicitly removed from storage. Failed critical runs are not rerun under the same key.

See API examples, protocol, deployment and limitations, and contribution guidance.

SDK examples

JavaScript package is provided locally under sdk/js and has not been published to npm:

import { CoreviaClient } from './sdk/js/index.js';
const client = new CoreviaClient({
  baseUrl: 'http://127.0.0.1:8081',
  realtimeUrl: 'ws://127.0.0.1:8080/realtime',
  token: () => yourSessionToken,
});
client.onError(error => console.error(error.code));
const unsubscribeHandler = client.channel('orders').on('order.updated', (data, envelope) => {
  console.log(data, envelope.meta.trace_id);
});
// The demo gateway exposes only orders.get, and only when COREVIA_API_TOKEN is set.
const { data, requestId, traceId } = await client.call('orders.get', { run_id: 'run_...' });
client.disconnect();

Reconnect restores subscriptions. Event delivery is live; missed events are not replayed. React is optional: sdk/js/react.js exports CoreviaContext and useCoreviaAction. Standard fetch, AbortController and WebSocket implementations support React Native; no DOM, TextEncoder or Node Buffer is required by the client. Native push/background execution is outside V1.

from corevia import Worker
worker = Worker('http://127.0.0.1:8090', token='development-shared-secret')

@worker.action('ai.analyze')
def analyze(payload):
    return {'characters': len(payload['text'])}

worker.run()

Use PYTHONPATH=sdk/python or install with pip install ./sdk/python. The Python package has no third-party runtime dependencies.

Tests

composer validate --strict
composer lint
composer test
node --test sdk/js/test/*.test.js
PYTHONPATH=sdk/python python -m unittest discover -s sdk/python/tests -v
PYTHON=python node tests/integration.mjs

PowerShell:

$env:PYTHONPATH = "$PWD\sdk\python"
$env:PYTHON = 'python' # Or the absolute path to your installed executable
python -m unittest discover -s sdk/python/tests -v
node tests/integration.mjs

Integration tests use dynamic loopback ports and isolated temporary storage. They start and stop actual PHP/Python/realtime processes, check SDK event delivery/reconnect, private channel authorization, persistent HTTP idempotency, critical failures and CLI retry. Shared CVP fixtures run in all three languages. GitHub Actions is configured for PHP 8.2, 8.3 and 8.4.

CLI

serve                         routes                       modules
flow:list                     flow:run <name> --input=file.json [--key=key]
flow:show <run-id>             flow:retry <run-id> <step-index>
realtime:start                realtime:stop                doctor
make:module <Name>            make:action <Name>           make:flow <Name>

Generators refuse existing files and require PascalCase names. Generated actions/flows live under app/Generated; register them explicitly. Generated modules are added to the bootstrap module list. Server host/port options use --host=127.0.0.1 --port=8081 for HTTP and port 8080 for realtime.

MIT licensed. Contributions should preserve package boundaries, restrictive defaults and cross-language tests.

Read the historical V3 foundation guide, architecture checks, production acceptance and progress record. The current PHP framework version is 4.0.1; unchanged JS, Python and Dart SDK metadata remains 4.0.0. Protocol versions remain CVP/1 and CVP/2. Package-registry publication is separate from GitHub source publication.