Flyokai glossary¶
A single-source list of terms that recur across the framework. Most have detailed treatment in a specific module; this page is the index.
| Term | One-line definition | See |
|---|---|---|
| ACL | Laminas Permissions\Acl instance built lazily by AclProvider. Modules contribute resources/roles via tuners. |
flyokai/application |
| AGENTS.md | The agent-facing deep-dive doc that lives next to every module. Contains internal architecture, dataflow, gotchas. | Doc contract |
| Alias (DI) | A one-way map from interface to implementation registered via AliasResolverImpl. Asking for the interface returns the implementation; asking for the implementation directly does not go through the alias. |
flyokai/amphp-injector |
| AltId | An alternative or composite identity for a DTO (e.g. username, email) declared via static $altIdKeys. Returned by altId(...). |
flyokai/data-mate |
AmpConnectionPool |
The native AMPHP-MySQL connection pool. One of three ConnectionPool implementations in Flyokai. |
flyokai/laminas-db-driver-amp |
AsyncMysqliConnectionPool |
The default Flyokai ConnectionPool. Uses MYSQLI_ASYNC + EventLoop::onMysqli(). |
flyokai/laminas-db-driver-async |
AsyncPdoConnectionPool |
Worker-pool-based PDO ConnectionPool. Process-isolated. |
flyokai/laminas-db-driver-async |
| ApplicationType | Enum (Setup, Cluster, Worker, Task, Web, Cli) — controls which module bootstraps load. |
flyokai/application |
| Bootstrap (module) | A class declared via Registry::addModule() that registers DI config and runs init() / bootstrap() during application startup. |
flyokai/application |
| CLAUDE.md | The agent quick-reference doc that lives next to every module. ≤30 lines, points at AGENTS.md. | Doc contract |
| Composition (DI) | An ordered collection of items, sorted topologically via before / after / depends. Implemented as CompositionOrdered + CompositionItem in amphp-injector. |
flyokai/amphp-injector |
| Composition (module) | The framework-level topological-sort utility (sortComposition, castCompositionArgument) used to order modules and pipeline items. Same idea, different layer. |
flyokai/composition |
ConfigPile |
Two-layer config object — default + local. Path-based access (get('db/connection/default/host')). |
flyokai/application |
ConnectionPool |
Factory contract for DB pools. Implementations: Amp, AsyncPdo, AsyncMysqli, TwoLevel. |
flyokai/application |
Context (channel-dispatcher) |
Per-request data attached by the dispatcher: dispatcher weakref, sendRequest, iterator storage. |
flyokai/amp-channel-dispatcher |
#[Column] |
Parameter attribute on a Solid DTO that overrides any subset of the inferred column definition (type, length, nullable, default, …). | flyokai/db-schema |
| diconfig file | A config/diconfig*.php file returning ['aliases', 'arguments', 'definitions', 'runtimeDefinitions']. One per ApplicationType. |
docs/dependency-injection.md |
| Draft | Marker interface for mutable, schema-flexible DTOs. Pairs with a Solid for input staging. | flyokai/data-mate |
Dto |
Base interface every DTO obeys: toArray, toDbRow, with, cloneWith, fromArgs. |
flyokai/data-mate |
| Edition | A composer create-project template that bundles a curated subset of the framework. Currently: webapi-edition, data-service-edition. |
Editions section in central README |
EventLoop (Revolt) |
The static event-loop API. defer, delay, repeat, onReadable, onWritable, onSignal, onMysqli, getSuspension. |
flyokai/revolt-event-loop |
| Execution (generic) | A composable side-effect runner — Execution<TContext> from flyokai/generic. |
flyokai/generic |
| Fiber | PHP 8.1+ stackful coroutine. Every Revolt callback runs in its own fiber. | flyokai/revolt-event-loop |
#[ForeignKey] |
Class-level attribute on a Solid DTO. referencesDto is a class-string; resolved to the target's table name in a second discovery pass. |
flyokai/db-schema |
| GreyData | Marker interface for dynamic key/value DTOs backed by a $data array. Used for API payloads, third-party blobs. |
flyokai/data-mate |
HasId / HasAltId / HasIdDto |
Identity interfaces — primary id, alternative ids, combined Dto+id. | flyokai/data-mate |
| HandlerGuard | HTTP middleware that runs Authorization::isAllowed() (or a RequestDefender for the data-service) before delegating to the handler. |
flyokai/application |
| Indexer | Implementation of Flyokai\Indexer\Indexer. Registered via DI composition; orchestrated by IndexerFacade; status persisted in flyok_indexer. |
flyokai/indexer |
InsertOnDuplicate |
Bulk MySQL upsert builder with batching, ID resolution, and FOREIGN_KEY_CHECKS management. |
flyokai/laminas-db-bulk-update |
| Lifecycle | An interface (start() / stop()) implemented by services that need ordered startup/shutdown. The Application walks dependencies forward on start, reverse on stop. |
flyokai/amphp-injector |
LicWiseRequest |
Marker interface for inter-service requests that require license validation. | flyokai/data-service-message |
| Module | A package whose bootstrap.php calls Registry::addModule(). Has a Bootstrap\Type\* marker per app type and config/diconfig*.php files. |
flyokai/application |
#[PrivateParameter] |
Attribute on a constructor parameter — resolved by runtimeTypes() weaver to a fresh instance per injection site. |
flyokai/amphp-injector |
| Repeatable (setup step) | A setup step that runs on every setup:upgrade (vs. one-shot install steps). Used by db-schema's ApplySchema. |
flyokai/db-schema |
| Repository | A class implementing SearchableRepository (or otherwise loaded into RepositoryContainer) keyed by entity type. |
flyokai/search-criteria |
RouterBuilder |
Frozen-after-start builder that wraps every route with a HandlerGuard and registers middleware. |
flyokai/application, flyokai/data-service |
searchCompiler |
DI singleton orchestrating the six-stage criteria compile pipeline. | flyokai/search-criteria |
#[ServiceParameter] |
Attribute on a constructor parameter — resolved by runtimeTypes() weaver to a shared singleton of the parameter's type. |
flyokai/amphp-injector |
#[SharedParameter] |
Attribute on a constructor parameter — resolved to a shared instance scoped to the current definition. | flyokai/amphp-injector |
| Skill | A .agents/skills/*.md document that scaffolds a recurring workflow (new module, new endpoint, new DTO, …). Synced into .claude/skills/ and .agents/skills/. |
docs/scaffolding.md |
| Solid | Marker interface for immutable, constructor-validated DTOs. Properties typically public readonly. |
flyokai/data-mate |
SchemaModel |
The unified value object that carries a declared or introspected MySQL schema. | flyokai/db-schema |
#[Table] |
Class-level attribute on a Solid DTO declaring the MySQL table name (and optional alias used by search-criteria). |
flyokai/db-schema |
| TableModel | The single value object carried by every db-schema pipeline stage (declared, introspected, diffed). | flyokai/db-schema |
| Tuner (generic) | A composable state mutator — Tuner<T> from flyokai/generic. Containers run them in topological order. |
flyokai/generic |
TwoLevelConnectionPool |
A hybrid ConnectionPool that tries a primary pool first and falls back to a secondary. |
flyokai/application |
| Weaver | Parameter resolver in amphp-injector. names(), types(), runtimeTypes(), automaticTypes(), chained via any(). |
flyokai/amphp-injector |
Doc contract¶
Every flyokai package ships three documents next to its source:
| File | Audience | Purpose | Length |
|---|---|---|---|
README.md |
humans | Front door — install, quickstart, examples | unbounded |
CLAUDE.md |
agents | Quick-ref — pointers to AGENTS, 10-line cheat sheet | ≤30 lines |
AGENTS.md |
agents | Deep architecture, dataflow, gotchas | unbounded |
The header User docs → README · Agent quick-ref → CLAUDE · Agent deep dive → AGENTS appears on every doc.