# 1. Introduction
Phlo is an integrated platform with its own full-stack language. You write `.phlo` source files; Phlo compiles them to PHP, CSS and JavaScript you can open and read, with every runtime error pointing back at the `.phlo` line you wrote. The same language carries four layers: the language itself, the application platform (backend resources plus the phlo.js SPA engine), the server platform (FrankenPHP, phloWS, phloWA) and the operations platform (the Phlo Dashboard). This guide covers all of them. The production release runs on a shared runtime, usually in `/srv/phlo/`, while each app keeps its own source, data, generated PHP and webroot.
---
## 1.1 Philosophy
* **Source first**: you work in `.phlo`, not in generated PHP, CSS or JavaScript.
* **A small runtime**: the web entrypoint loads `/srv/phlo/phlo.php` and starts the app with `phlo_app(...)`.
* **Explicit runtime resources**: `data/app.json` selects which Phlo resources an app loads from the runtime catalog; app code stays in the app.
* **Dev and release separated**: dev builds, debugs and can use auth; release uses the generated output.
* **HTML, routes and behavior close together**: a route, view, style or script can live in the same topic file when that makes the app clearer.
---
## 1.2 Installation
Phlo requires PHP 8.3 or higher; the CLI build runs on the same PHP. For production, [FrankenPHP](https://frankenphp.dev) is the recommended runtime (built-in web server, worker mode); classic PHP-FPM behind Nginx works too.
Fetch the runtime and scaffold your first app with the bundled installer:
```bash
git clone https://github.com/q-ainl/phlo.git /srv/phlo
php /srv/phlo/install.php /srv/example.nl/
```
The installer asks for a name, host and target, shows the runtime catalog and lets you pick resources (their `@ requires` are included automatically), writes the entrypoint, `data/app.json`, `data/app.md`, a first route and `.gitignore`, and only finishes after a clean build with concrete next steps.
Prefer a copy that cleans up after itself? Copy `install.php` into the new app directory and run it there; after a successful installation it removes itself:
```bash
cp /srv/phlo/install.php /srv/example.nl/ && cd /srv/example.nl && php install.php
```
The next sections describe what the installer sets up for you, and how to build the same thing by hand.
---
## 1.3 Project structure
A typical app:
```text
/srv/example.nl/
app.phlo
page.home.phlo
data/
app.json
auth.ini
creds.ini
php/
app.php
classmap.php
release/
www/
app.php
www/
app.php
```
`php/`, `www/app.js`, `www/app.css` and `release/` are build output. Only change them through the source and rebuild.
---
## 1.4 Entrypoint
Dev entrypoint in `www/app.php`:
```php
` and `
```
* `app.var.background = '#000000'` → live-updates the value of `--background` in the DOM, without a rebuild or reload.
* `const textColor = app.var.text` → reads back the current value.
👉 These updates work **in real time** in the browser and immediately affect all elements that use the variable.
You can use this for, among other things:
* **Theme switches** (dark/light mode)
* Dynamically adjusting accent colors based on user input
* Interactive UIs without toggling separate CSS classes
### How it works
* The CSS engine converts `$background` to `--background`.
* The frontend engine reads/writes it via `document.documentElement.style`.
* `app.var` provides a simple proxy object, so you can work with these as if they were plain JS properties.
---
## 7.6 Full example
**Input**
```phlo
html: height: 100dvh
body {
background: #947b6c
font-family: Sans-serif
p: line-height: 2em
}
body: h1, p: \:first-letter: color: green
h1 {
color: white
@media (max-width: 768px): color: black
}
p {
color: navy
\:last-child: color: yellow
}
```
**Output**
```css
body {
background: #947b6c;
font-family: Sans-serif;
}
body h1:first-letter,
body p:first-letter {
color: green;
}
body p {
line-height: 2em;
}
h1 {
color: white;
}
html {
height: 100dvh;
}
p {
color: navy;
}
p:last-child {
color: yellow;
}
@media (max-width: 768px){
h1 {
color: black;
}
}
```
---
## 7.7 Best practices
* **Use `$variables`** for colors, spacing, and fonts; this makes theming and dark/light modes easy.
* Define global theme variables in `:root`.
* Use selector chains and grouping for compact, readable code.
* Put `@media` right inside the block; Phlo hoists it to the right place.
* Use `\` in nestings to glue pseudos or attributes to the parent selector.
* No semicolons in your code; Phlo produces correct CSS output.
---
## 7.8 Icon sprites
Point `icons` in `data/app.json` at one or more folders of PNG files and the build composes them into a single `www/icons.png` sprite plus the CSS to use them:
```json
{
"icons": "%app/icons/",
"iconNS": "app"
}
```
Naming convention: `save.png` becomes class `.icon.save`; `save.dark.png` becomes the same class scoped to `body.dark`, so one icon name can have per-context variants (themes, states). Usage in a view:
```phlo
```
The generated CSS lands in the `iconNS` bundle (default `app`) and `view()` preloads the sprite automatically.
---
# 8. ORM
Phlo ships with a powerful built-in **ORM** that lets you define database tables as classes.
Models can be defined quickly via `columns` or in full via a declarative `schema`.
Records are treated as **instances**, with support for props, methods, views, relations and multiple database engines.
---
## 8.1 Basics
An ORM model is a `.phlo` file with:
* `@ class:` the name of the model (and table)
* `@ extends: model`
* `static table` and `columns` or `schema`
* Optional: relations (`parent`, `child`, `many`)
* Props, methods and views operate per **record instance**
Example:
```phlo
@ class: user
@ extends: model
view => $this->name
static table = 'users'
static columns = 'id,name,email,active,created'
```
---
## 8.2 Defining models
### 7.2.1 Flat with `columns` (quick and lightweight)
Use `columns` for simple tables:
```phlo
@ class: shipment
@ extends: model
view: $this->destination ($this->user)
static table = 'shipments'
static order = 'changed DESC'
static columns = 'id,user,destination,costs,valid,weight,shipped,created,changed'
static objParents = ['user' => 'user']
```
```phlo
@ class: user
@ extends: model
view => $this->name
static table = 'users'
static order = 'changed DESC'
static columns = 'id,name,email,level,active,created,changed'
static objChildren = ['shipments' => 'shipment']
```
---
### 7.2.2 With `schema` and `field(...)` (rich and declarative)
With `schema` you define fields, relations and UI in one place:
```phlo
@ class: shipment
@ extends: model
view: $this->destination ($this->user)
static table = 'shipments'
static schema => arr (
id: field (type: 'token', length: 4, title: 'ID'),
destination: field (type: 'text', required: true, search: true),
user: field (type: 'parent', obj: 'user', required: true),
costs: field (type: 'price', prefix: '€ '),
valid: field (type: 'bool'),
attachments: field (type: 'child', obj: 'attachment', list: true),
)
```
```phlo
@ class: user
@ extends: model
view => $this->name
static table = 'users'
static schema => arr (
id: field (type: 'token'),
name: field (type: 'text', search: true, required: true),
email: field (type: 'email', required: true),
shipments: field (type: 'child', obj: 'shipment'),
groups: field (type: 'many', obj: 'group', table: 'user_groups'),
)
```
> `schema` is especially powerful in combination with PhloCMS, but works standalone too.
---
## 8.3 CRUD
Fetching:
```phlo
$user = user::record(id: 1)
$list = shipment::records(order: 'created DESC')
```
Creating:
```phlo
$shipment = shipment::create(destination: 'Paris', user: 1)
```
Editing and saving:
```phlo
$shipment->destination = 'Lyon'
$shipment->objSave
```
Deleting:
```phlo
shipment::delete('id=?', $shipment->id)
```
* `record(...)` → single record (or null)
* `records(...)` → array of records (class instances)
* `create(...)` → insert + instant fetch
* `objSave` → save the instance (insert/update depending on id)
* `delete(...)` → static delete with an SQL where clause
---
## 8.4 Relational navigation
Relations are available as properties:
| Type | Declaration | Usage |
| ------ | -------------- | ------------------ |
| parent | `type: parent` | `$shipment->user` |
| child | `type: child` | `$user->shipments` |
| many | `type: many` | `$user->groups` |
### Many-to-many
`type: many` uses a pivot table:
```phlo
groups: field (
type: 'many',
obj: 'group',
table: 'user_groups',
)
```
Navigation:
```phlo
$user = user::record(id: 1)
foreach ($user->groups as $group)
echo $group->title
```
Relations are **batch-loaded** for performance. There are no cross-DB joins; each class loads from its own engine.
---
## 8.5 Instance dynamics
Every record is a **real instance** of your model class.
You can use props, methods and views to add virtual fields, computations or representations:
```phlo
@ class: shipment
@ extends: model
prop summary => $this->destination.' ('.$this->user.')'
method tax => $this->costs * 0.21
view:
$this->summary
$this->tax
```
Usage:
```phlo
$shipment = shipment::record(id: 'AB12')
echo $shipment->summary
echo $shipment
```
Using a record as a string invokes its view representation.
Props and methods always operate on the **record instance**, never statically.
---
## 8.6 Filtering and queries
All query methods accept named arguments and SQL-like filters:
```phlo
shipment::records(destination: 'Paris')
shipment::records(where: 'valid=1 AND weight>10')
shipment::pair(columns: 'id,destination')
```
Supported: `where`, `order`, `group`, `joins`, caching and schema-aware columns.
---
## 8.7 Caching and performance
The ORM uses internal buffers (`objRecords`, `objLoaded`) for relational lookups and optional **APCu caching** via:
```phlo
static objCache = true
```
Or a number of seconds:
```phlo
static objCache = 600
```
Records and relations are loaded in batches.
Use `records()` for bulk selections instead of `record()` in loops.
---
## 8.8 Multiple engines
Phlo supports multiple backends via `prop DB`.
The default is `%MySQL`, but you can set any engine per model.
### SQLite
```phlo
prop DB => %SQLite(data.'users.db')
```
```phlo
@ class: notes
@ extends: model
prop DB => %SQLite(data.'notes.db')
static table = 'notes'
static columns = 'id,title,body'
```
### PostgreSQL
```phlo
prop DB => %PostgreSQL
```
```phlo
@ class: invoices
@ extends: model
prop DB => %PostgreSQL
static table = 'invoices'
static columns = 'id,customer_id,total,created'
```
> Tables on different engines can be combined in relations; each class fetches its own data.
---
### `/data/creds.ini`
For engines such as MySQL and PostgreSQL, place your credentials in:
```
/data/creds.ini
```
```ini
[mysql]
host = localhost
database = db_name
user = db_user
password = db_password
[postgresql]
host = localhost
database = my_pg_db
user = pg_user
password = pg_pass
```
Phlo loads these automatically via `%creds->...`.
---
## 8.9 Opt-in features: audit, validation, custom PK
An `@ extends: model` gives you CRUD + identity map + relations + soft delete out of the box. Three additional opt-ins are enabled per model with a static flag.
### X.9.1 Audit log
```phlo
static objAudit = true
```
From then on, every `create`, `objSave` (update) and `delete` is logged to an audit table via the `security/audit` resource:
| Operation | What gets logged |
| --- | --- |
| `create(...)` | full new values |
| `objSave` (update) | diff: only changed fields, `from` → `to` |
| `delete(...)` | full old values, per affected record |
Setup:
1. Add `security/audit` to the resources in `data/app.json`.
2. Import the schema SQL once: `mysql < /srv/phlo/resources/security/audit.sql`.
Excluding sensitive fields:
```phlo
method afterCreate => %audit->log($this, 'create', [], (array)$this, exclude: ['password_hash'])
```
Toggle per environment, dev only:
```phlo
static objAudit => debug
```
Or release only:
```phlo
static objAudit => !debug
```
(`debug` is the runtime constant from `phlo_app(debug: ...)`.)
### X.9.2 Validation
```phlo
static objValidate = true
```
Before `create()`, Phlo runs the matching `objValidate($value)` for each field in `static schema()`. On errors: `create()` returns `null`, with errors available via `Class::objErrors()`:
```phlo
if (!user::create($args)){
return apply(errors: user::objErrors())
}
```
Field rules in `schema()`:
```phlo
static schema => arr (
email: field (type: 'email', required: true),
name: field (type: 'text', length: 100, required: true),
slug: field (type: 'text', pattern: '^[a-z0-9-]+$'),
status: field (type: 'text', enum: ['draft', 'sent', 'paid']),
)
```
Custom field validation: override `method objValidate($value)` in your own field subclass.
### X.9.3 Custom primary key
The default is `id` (auto-increment integer). Override it for other PKs:
```phlo
static idColumn = 'sku'
static idType = 'string'
```
Effect:
- The identity map uses `sku` as its key
- `Class::record(sku: 'XYZ-123')` (not `id:`)
- With `create()`: you supply the PK value yourself (no auto-increment)
- `$record->id` does not work, use `$record->sku`
### X.9.4 Combining
The three opt-ins are independent and can be combined:
```phlo
@ class: giftcard
@ extends: model
static objAudit = true
static objValidate = true
static idColumn = 'sku'
static idType = 'string'
```
Every feature is off by default (`false`, `'id'`, `'int'`). A model without opt-ins stays a plain model.
---
## 8.10 Function overview
| Function / Property | Type | Description |
| ------------------------------- | ----------- | --------------------------------- |
| `record(...)` | static | Fetches 1 record (or null) |
| `records(...)` | static | Fetches multiple records (array) |
| `create(...)` | static | Insert + fetch |
| `objSave` | instance | Insert or update |
| `delete(where, …)` | static | Delete |
| `pair`, `item`, `column` | static | Quick query helpers |
| `objParents` / `schema: parent` | declarative | Parent relations |
| `objChildren` / `schema: child` | declarative | Child relations |
| `schema: many` | declarative | Many-to-many |
| `objCache` | static | Optional APCu caching |
| `prop DB` | static | Per-model engine |
---
## 8.11 Best practices
* Use `columns` for quick, simple models.
* Use `schema` for rich definitions and CMS integration.
* Define a `view` for string representations.
* Use props for virtual fields.
* `objSave` instead of `save`.
* Use `records()` for bulk loads.
* Separate models per engine with `prop DB`.
* Keep credentials in `/data/creds.ini`.
* Keep models declarative; put logic in props/methods.
---
# 9. Instance Management
Phlo uses its own **instance manager** to initialize and reuse objects efficiently and predictably. This system determines **when controller code runs**, how instances are stored, and how circular references are prevented.
---
## 9.1 The basics
When you define a `.phlo` file, the build phase turns it into a class.
Every call to an object via `%name` goes through the **instance manager** (`phlo()` in `/phlo/phlo.php`).
Example:
```phlo
prop title = 'Welcome'
route GET home => $this->main
method main => view($this->home)
view home:
$this->title
```
When the route `/home` is requested:
1. The instance manager checks whether an instance of this class already exists.
2. If not, it is **created and stored**.
3. After creation, **the controller code** runs (see §8.2).
4. Then the requested method is called.
---
## 9.2 Controller code
All code in a `.phlo` file that does **not** belong to `route`, `prop`, `static`, `method`, `function`, `view`, `