Pionia
Everything you need to build versioned JSON APIs with Pionia v3.
The example app: Pionia Shop
Hands-on pages follow one small store so names stay consistent:
- Pionia Shop — a fictional online store + wallet (named after the framework)
- pionia-shop — the Composer project name used in commands
- ada@pionia.shop — sample customer in curl examples
Requires PHP 8.5+. Tutorial services: product, customer, order, wallet.
| Table | What it stores |
|---|---|
products | Catalog (name, price, stock) |
customers | Shoppers (email, password_hash) |
orders / order_items | Checkouts and line items |
wallets / wallet_transactions | Balance and top-ups / payments |
Build it in the Pionia Shop tutorial.
Pick your learning path
Getting started
Install Pionia and meet Pionia Shop.
Pionia Shop tutorial
15 steps — scaffold through deploy.
Browse examples
Copy-paste curl payloads and JSON envelopes.
First steps
| Order | Guide | Description |
|---|---|---|
| 1 | Introduction | Install with Composer, first ping, meet Pionia Shop |
| 2 | PHP basics | Minimum PHP (optional) |
| 3 | Pionia Shop tutorial | Catalog, checkout, and wallet step by step |
| 4 | Glossary | service, action, switch, envelope |
How the documentation is organized
| Type | Reader goal | Examples |
|---|---|---|
| Tutorials | Hands-on; build Pionia Shop | Shop tutorial |
| Topic guides | Understand concepts | Moonlight overview, Auth |
| Reference | Look up APIs and config | Helpers, Porm API |
| How-to guides | One task, one recipe | RoadRunner, Maintenance |
What these docs cover
| Layer | Topics |
|---|---|
| Getting started | Composer install, PHP basics, Pionia Shop tutorial, app structure, v3 changelog |
| Building your API | Moonlight, services, actions, validation, generic CRUD, API docs |
| Database (Porm) | Migrations, configuration, queries, filtering, joins, pagination, connections |
| HTTP | Envelopes, welcome page, middleware, exceptions, routing, collections |
| Security | JWT, authentication backends, authorization in services |
| Frontend | Vite SPA scaffold, dev proxy, production build |
| Operations | CLI, bench, RoadRunner, caching, logging, maintenance, production optimize |
| Extending | App providers, Composer packages, helpers, maintainer notes |
The API layer
Services · Actions · Validation · Generic services · Moonlight overview · Documenting your API
The data layer (Porm)
Migrations · Getting started · Making queries · Filtering · Joins · Pagination
The HTTP layer
Requests & responses · Welcome page & branding · Middleware · Exceptions · Routing
Security
JWT authentication · Protecting actions · Authentication · Security utilities
Frontend & operations
Vite integration · RoadRunner · Production performance · CLI · Benchmarking · Caching · Logging
Extending Pionia
App providers · Composer packages · Maintainer notes
Getting help
- Common mistakes — each guide ends with a troubleshooting section
- Logs —
storage/logs/withDEBUG=truein.env - Examples — curl snippets for Pionia Shop actions
- Resources — packages, CLI, and links
Community
- GitHub — PioniaPHP-project — core, app template, docs
- Packagist — pionia/pionia-app —
composer create-projecttemplate - pionia-docs on GitHub — contribute to this site
- OSCA Kampala Chapter — local open-source community
- Stats —
/statswhenDEBUGorSTATS_ENABLEDis on
Common mistakes
- Starting with advanced topics — follow Introduction → Pionia Shop tutorial before auth or RoadRunner.
- Skipping the glossary — terms like switch, envelope, and action are defined in Glossary.
- Using maintainer commands —
php pionia newis for framework contributors only; apps install viacomposer create-project pionia/pionia-app. - Old flat URLs — bookmark
/documentation/getting-started/introduction/not/documentation/introduction/(redirects exist but paths moved).