Download the PHP package flytachi/winter-ppa without Composer

Winter PPA

📖 Documentation · Repositories · Entities · Connection pool

PHP Persistence API — the data layer for PHP that stays resident.

Two problems, one package. Writing SQL by hand means the same query rebuilt in every place it is needed, parameters bound by hand, and a renamed column discovered at runtime. And a worker that lives for weeks cannot simply open a connection and keep it: the connection dies, the database restarts, the firewall drops idle sockets — while under Swoole one socket cannot be shared by concurrent requests at all.

PPA answers both: repositories that assemble queries as method calls, entities that describe tables as attributes, migrations built from those attributes — over a connection pool that keeps its connections working rather than merely reused.

Installation

Requires PHP 8.4+ and ext-pdo. ext-swoole is optional: with it every coroutine gets its own connection from a pool, without it one self-maintaining connection serves the process — the calling code is identical.

Inside the Winter framework it is an optional package: the kernel wires it up when it is installed and works without it when it is not.

Quick start

Describe the table:

Bind a repository to it:

The @extends line is what makes findById() return ?UserEntity instead of object; the code works without it, the editor does not.

Ask it questions:

No connection to obtain, none to return. The connection is taken on the first query and goes back to the pool when the request ends.

What you get from it

A query built from methods, not strings. where(), join*(), with(), union*() accumulate parts; values travel as bound parameters, never as text. A sub-repository can be joined, used as a source or as a CTE — and brings its own binds along, which a string could not.

A schema that comes from the code. Attributes on entity properties describe types, keys, indexes and constraints; call db migrate compares that description with the live database and shows what it would change before doing it.

Connections that heal. An idle connection is probed before it is handed over, an aged one is rotated ahead of time, and the number is capped per worker. A database restart stops poisoning a worker for the rest of its life.

Correctness under concurrency. A repository may be a container singleton while serving concurrent coroutines: its query state is isolated per coroutine, so two requests cannot build each other's conditions.

Failures that are classified, not guessed. A dead connection is retired; a constraint violation leaves the connection alone. Where the driver's verdict is uninformative — as PostgreSQL's is when the socket is gone — the pool probes instead of parsing the message.

A taste of the API

Outside a framework

The package fetches nothing from its host. Three things it takes, and what happens when they are not given:

Each default is the inert one deliberately: a library that logs somewhere by itself, or imposes a timezone on your session, is a library that surprises you. Fork safety and shutdown are yours to call as well — PpaConnectionPool::reset() in a forked child (which forgets sockets without closing them, since the descriptors are shared with the parent), shutdown() when a worker exits.

Inside the Winter kernel all of this is installed at boot.

Documentation

The user-facing documentation lives at winterframe.net/docs/ppa (the link picks your language; RU and EN are both complete).

Start here

Schema

Operating it

Contributing

Internal technical notes — the layering, how an attribute becomes a column, why query state is per coroutine, and the rules for adding to any of it — live in docs/. Read those before changing the pool or the mapping.

• Setup, the testing philosophy and the documentation rules: CONTRIBUTING.md
• Changes and upgrade notes: CHANGELOG.md
• Reporting a vulnerability, and what the package does and does not guarantee: SECURITY.md

License

MIT License. See LICENSE.