Upgrading from v2

Who this is for#

You maintain a v2 Pionia app (pre-AppRealm) and need a clear path to v3 — or you want to regenerate DeskFlow with pionia/pionia-app and port your services.

What you will learn#

• Replacing PioniaApplication with AppRealm::create()
• Moving switch registration into [app_switches] in settings.ini
• When a fresh scaffold beats incremental file edits

Before you start#

How it works#

v3 separates framework boot (AppRealm) from API versioning ([app_switches]). Your DeskFlow services (task, member, project) port mostly unchanged — the wiring around them moves to settings.ini and bootHttp().

Requirements#

• PHP 8.5+
• pionia/pionia-core ^3.0

Bootstrap#

v3 environment/settings.ini (switches):

[app_switches]
v1=Application\Switches\MainSwitch

v3 bootstrap/application.php:

<?php

require __DIR__ . '/../vendor/autoload.php';

use Pionia\Realm\AppRealm;

return AppRealm::create(__DIR__);

Switches#

registerServices() must return Arrayable (use arr([...])):

public static function registerServices(): Arrayable
{
    return arr([
        'task' => TaskService::class,
        'member' => MemberService::class,
        'project' => ProjectService::class,
    ]);
}

Static assets#

Move static/ at repo root → public/static/ (or rely on the framework welcome page).

Autoload#

Prefer a single PSR-4 root:

"Application\\": "./"

CLI (native console)#

v3 ships a native console at Pionia\Console\Application. Custom and generated commands extend Pionia\Console\Command. Input types live under Pionia\Console\Input\ (InputArgument, InputOption).

The CLI banner shows the installed pionia/pionia-core version from Composer (e.g. v3.0.2-beta), not a hardcoded framework string.

HTTP routing (Symfony removed)#

v3 replaces Symfony Routing with native classes:

See HTTP routing for CompiledRouteMatcher, bootstrap route cache, and production php pionia optimize --production.

Production optimization (new in v3)#

Deploy-time performance is opt-in:

composer install --no-dev -o
php pionia optimize --production

See Production performance.

Fresh start option#

Regenerate and port services:

composer create-project pionia/pionia-app deskflow-api-v3
# copy services/, switches/, environment/ from the old app
php pionia serve
curl -s http://127.0.0.1:8000/api/v1/ping

See Application structure for the full v3 tree.

Common mistakes#

• Leaving imperative router wiring in bootstrap — delete PioniaRouter::wireTo() calls; use [app_switches] only.
• Returning plain arrays from registerServices() — wrap with arr([...]) for the Arrayable contract.
• Porting without updating JSON keys — v3 expects lowercase service and action in request bodies.
• Running v3 on PHP 8.4 — upgrade PHP before bumping pionia/pionia-core to ^3.0.

What’s next#