# Tina4 PHP - Quick Reference

::: tip 🔥 Hot Tips

* Routes go in `src/routes/`, templates in `src/templates/`, static files in `src/public/`
* GET routes are public by default; POST/PUT/PATCH/DELETE require a token
* `$response->json()` returns JSON with the correct headers, no manual config
* Run `tina4 serve` to start the dev server on port 7145
:::

[Installation](index.md#installation) • [Static Websites](index.md#static-websites) • [Routing](index.md#basic-routing) • [Middleware](index.md#middleware) • [Templates](index.md#templates) • [Sessions](index.md#session-handling) • [SCSS](index.md#scss-stylesheets) • [Environments](index.md#environments) • [Authentication](index.md#authentication) • [Forms & Tokens](index.md#html-forms-and-tokens) • [AJAX](index.md#ajax) • [OpenAPI](index.md#swagger) • [Databases](index.md#databases) • [Database Results](index.md#database-results) • [Graph](index.md#graph) • [Migrations](index.md#migrations) • [ORM](index.md#orm) • [CRUD](index.md#crud) • [REST Client](index.md#consuming-rest-apis) • [Testing](index.md#inline-testing) • [Services](index.md#services) • [Websockets](index.md#websockets) • [Queues](index.md#queues) • [WSDL](index.md#wsdl) • [GraphQL](index.md#graphql) • [Localization](index.md#localization) • [HTML Builder](index.md#html-builder) • [Events](index.md#events) • [Logging](index.md#logging) • [Response Cache](index.md#response-cache) • [Health](index.md#health) • [DI Container](index.md#container) • [Error Overlay](index.md#error-overlay) • [Dev Admin](index.md#dev-admin) • [CLI](index.md#cli) • [MCP Server](index.md#mcp) • [FakeData](index.md#fakedata)

### Installation <a href="#installation" id="installation"></a>

```bash
# Install the tina4 CLI once. Windows: irm https://tina4.com/install.ps1 | iex
curl -fsSL https://tina4.com/install.sh | sh

tina4 init php my-app
cd my-app
tina4 serve
```

[More details](01-getting-started.md) on project setup and configuration options.

### Static Websites <a href="#static-websites" id="static-websites"></a>

Drop `.html` or `.twig` files in `./src/templates`. Put assets in `./src/public`.

```twig
<!-- src/templates/index.twig -->
<h1>Hello Static World</h1>
```

[More details](04-templates.md) on static website routing.

### Basic Routing <a href="#basic-routing" id="basic-routing"></a>

```php
<?php
use Tina4\Router;

Router::get("/", function ($request, $response) {
    return $response->json(["message" => "Hello Tina4 PHP"]);
});

// POST requires a formToken or Bearer auth
Router::post("/api/items", function ($request, $response) {
    return $response->json(["data" => $request->body], 201);
});

// Dynamic path parameters
Router::get("/users/{id:int}", function ($request, $response) {
    $id = $request->params["id"];
    return $response->json(["user_id" => $id]);
});
```

Follow the links for [basic routing](02-routing.md), [dynamic routing](02-routing.md) with variables, and [different response types](02-routing.md).

### Middleware <a href="#middleware" id="middleware"></a>

The v3 middleware system uses class-based middleware with `before*`/`after*` static methods.

```php
<?php
use Tina4\Request;
use Tina4\Response;

class AuthMiddleware
{
    public static function beforeAuth(Request $request, Response $response): array
    {
        if (!$request->bearerToken()) {
            return [$request, $response->json(["error" => "Unauthorized"], 401)];
        }
        return [$request, $response];
    }
}
```

Register middleware globally or attach it to a single route.

```php
<?php
use Tina4\Middleware;
use Tina4\Router;

// Global -- runs on every request
Middleware::use(AuthMiddleware::class);

// Per-route -- third argument
Router::get("/api/secret", function ($request, $response) {
    return $response->json(["secret" => "The answer is 42"]);
}, "requireApiKey");
```

Follow the links for more on [middleware declaration](10-middleware-security.md), [linking to routes](10-middleware-security.md), [middleware chaining](10-middleware-security.md), and [middleware with dynamic routes](10-middleware-security.md).

### Template Rendering <a href="#templates" id="templates"></a>

Templates live in `./src/templates`. The framework uses Frond, a Twig-compatible engine built from scratch. Call `$response->render()` and pass your data.

```twig
<!-- src/templates/hello.html -->
<h1>Hello {{ name }}</h1>
```

```php
<?php
use Tina4\Router;

Router::get("/", function ($request, $response) {
    return $response->render("hello.html", ["name" => "World"]);
});
```

### Sessions <a href="#session-handling" id="session-handling"></a>

Sessions start by default in the `Auth` constructor.

### SCSS Stylesheets <a href="#scss-stylesheets" id="scss-stylesheets"></a>

Drop files in `./src/scss`. The framework compiles them to `./src/public/css`.

```scss
// src/scss/main.scss
$primary: #2c3e50;
body {
  background: $primary;
  color: white;
}
```

[More details](17-frontend.md) on CSS and SCSS.

### Environments <a href="#environments" id="environments"></a>

The default development environment lives in `.env`.

```
[Project Settings]
VERSION=1.0.0
TINA4_DEBUG=true
TINA4_LOG_LEVEL=ALL
TINA4_CACHE_BACKEND=false
TINA4_DATABASE_URL=sqlite:///data/app.db
[Open API]
TINA4_SWAGGER_TITLE=Tina4 Project
TINA4_SWAGGER_DESCRIPTION=Edit your .env file to change this description
TINA4_SWAGGER_VERSION=1.0.0
```

Access environment variables through the `$_ENV` superglobal.

```php
$title = $_ENV["TINA4_SWAGGER_TITLE"];
```

Access env vars programmatically:

```php
use Tina4\DotEnv;

DotEnv::loadEnv('.env');                     // Load .env file (auto on server start)
DotEnv::getEnv('TINA4_DATABASE_URL');              // Get value or null
DotEnv::getEnv('PORT', '7146');              // Get value with default
DotEnv::hasEnv('TINA4_DEBUG');               // true if set
DotEnv::requireEnv('TINA4_DATABASE_URL');          // Throws if missing
DotEnv::isTruthy(DotEnv::getEnv('TINA4_DEBUG'));  // true for "true", "1", "yes"
```

### Authentication <a href="#authentication" id="authentication"></a>

POST, PUT, PATCH, and DELETE routes are secured by default. GET routes stay public unless you mark them otherwise.

```php
<?php
use Tina4\Router;

// @secured marks a GET route as protected
/**
 * @secured
 */
Router::get("/api/profile", function ($request, $response) {
    return $response->json(["user" => $request->user]);
});

// Or use the chainable ->secure() method
Router::get("/api/account", function ($request, $response) {
    return $response->json(["account" => $request->user]);
})->secure();
```

Generate and validate tokens with the `Auth` class.

```php
use Tina4\Auth;

$token = Auth::getToken(["userId" => 1, "role" => "admin"]);
$payload = Auth::validToken($token);
```

Guard a route by role or permission with the chainable `role()` and `can()`. Both read the verified `roles` and `permissions` claims from the signed token. A missing token returns 401, a valid token without the role or permission returns 403.

```php
Router::get("/admin/stats", function ($request, $response) {
    return $response->json(["active_users" => 42]);
})->role("admin");

Router::delete("/api/posts/{id}", function ($request, $response) {
    return $response->json(["deleted" => true]);
})->can("posts.delete");
```

### HTML Forms and Tokens <a href="#html-forms-and-tokens" id="html-forms-and-tokens"></a>

Form tokens protect POST routes from cross-site forgery. Add one with a Twig filter.

```twig
<form method="POST" action="/process-form">
    {{ "emailForm" | formToken }}
    <input name="email">
    <button>Save</button>
</form>
```

The filter renders a hidden input with a signed JWT.

```html
<form method="POST" action="/process-form">
    <input type="hidden" name="formToken" value="ey...">
    <input name="email">
    <button>Save</button>
</form>
```

[More details](03-request-response.md) on posting form data, [securing routes](03-request-response.md), [Tina4 tokens](03-request-response.md), [uploading files](03-request-response.md), [handling errors](03-request-response.md), and a [full login example](03-request-response.md).

### AJAX and frond.js <a href="#ajax" id="ajax"></a>

Tina4 ships with frond.js, a small zero-dependency JavaScript library for AJAX calls, form submissions, and real-time WebSocket connections.

[More details](https://github.com/tina4stack/tina4-documentation/blob/main/general/frond.md) on available features.

### OpenAPI and Swagger UI <a href="#swagger" id="swagger"></a>

Swagger is built in and lives at `/swagger`. The `@description` annotation registers a route in the documentation.

```php
<?php
use Tina4\Router;

/**
 * @description Returns all users
 */
Router::get("/users", function ($request, $response) {
    return $response->json((new User())->select("*"));
});
```

Follow the links for more on [configuration](20-swagger.md), [annotations](20-swagger.md), and [usage](20-swagger.md).

### Databases <a href="#databases" id="databases"></a>

Set `TINA4_DATABASE_URL` in `.env`. The framework reads it at startup and opens the connection.

```bash
TINA4_DATABASE_URL=sqlite:///data/app.db
TINA4_DATABASE_URL=postgres://localhost:5432/myapp
TINA4_DATABASE_URL=mysql://localhost:3306/myapp
TINA4_DATABASE_URL=firebird://localhost:3050/path/to/database.fdb
```

Access the connection through the `Database` class.

```php
<?php
use Tina4\Database\Database;

$db = Database::getConnection();
$result = $db->fetch("SELECT * FROM products WHERE price > ?", [50]);
```

Follow the links for more on [available connections](05-database.md), [core methods](05-database.md), [usage](05-database.md), [examples](05-database.md), and [transaction control](05-database.md).

### Database Results <a href="#database-results" id="database-results"></a>

Fetch a single row or a paginated set. The database returns a `DatabaseResult` object that converts to arrays or objects.

```php
$db = Database::getConnection();

$row = $db->fetchOne("SELECT * FROM products WHERE id = 1");

// fetch($sql, $params, $noOfRecords, $offset)
$result = $db->fetch("SELECT * FROM products ORDER BY name", [], 10, 0);
```

Dig into the [usage guide](05-database.md) and [examples](05-database.md) for deeper coverage.

### Graph <a href="#graph" id="graph"></a>

Graph engines work exactly like databases: one URL-selected factory, one portable node and edge surface, and a driver that loads only when you use it. The scheme picks the engine (Ultipa, Neo4j, Memgraph, or ArangoDB).

```php
use Tina4\Graph\GraphDatabase;

$graph = GraphDatabase::create("ultipa://localhost:60061/mygraph");

$alice = $graph->addNode("Person", ["name" => "Alice"]);
$bob = $graph->addNode("Person", ["name" => "Bob"]);
$graph->addEdge($alice->id, $bob->id, "KNOWS", ["since" => 2020]);
```

Follow the link for more on the [Graph data layer](graph-databases.md).

### Migrations <a href="#migrations" id="migrations"></a>

The CLI manages migrations. Create one, add your SQL, then run it.

```bash
tina4 migrate:create my-first-migration
```

Run all pending migrations in one command.

```bash
tina4 migrate
```

More details on [migrations](05-database.md), their [creation](05-database.md), [running](05-database.md) them, and [integration with ORM](05-database.md).

### ORM <a href="#orm" id="orm"></a>

Once your migrations have created the tables, ORM models map PHP classes to database rows.

```php
<?php
use Tina4\ORM;

class User extends ORM
{
    public string $tableName = "users";
    public string $primaryKey = "id";

    public int $id;
    public string $email;
}

$user = new User(["email" => "alice@example.com"]);
$user->save();
$user = (new User())->load("id = ?", [1]);
```

ORM covers a lot of ground. Study the [full reference](06-orm.md) to get the most from it.

### CRUD <a href="#crud" id="crud"></a>

One line of code generates a working CRUD system: screens, routes, and all.

```php
(new User())->generateCrud("/my-crud-templates");
```

[More details](19-scaffolding.md) on how CRUD works and where it puts the generated files.

### Consuming REST APIs <a href="#consuming-rest-apis" id="consuming-rest-apis"></a>

Pull data from an external API in a single call.

```php
$api = (new \Tina4\Api("https://api.example.com"))->sendRequest("/my-route", "GET");
```

[More details](21-api-client.md) on sending POST bodies, authorization headers, and other controls.

### Inline Testing <a href="#inline-testing" id="inline-testing"></a>

Tina4 lets you add tests to functions without setting up a test suite.

```php
/**
 * @tests
 * assert(2, 5) == 7, "2+5 not equal 7"
 */
public function addTwoNumbers($number1, $number2)
{
    return $number1 + $number2;
}
```

Run the tests from the CLI.

```bash
tina4 test
```

[Limitations](18-testing.md) and further reading on the testing system.

### Services <a href="#services" id="services"></a>

Create a process class. The service runner picks it up and executes it on schedule.

```php
class MyProcess extends \Tina4\Process
{
    public function canRun(): bool
    {
        return true;
    }

    public function run(): void
    {
        // Your work goes here
    }
}
```

Register the process with the service.

```php
$service = new \Tina4\Service();
$service->addProcess(new MyProcess("Unique Process Name"));
```

[Further reading](27-service-runner.md) on services. Study them alongside [threads](27-service-runner.md) for the full picture.

### Websockets <a href="#websockets" id="websockets"></a>

```php
Router::websocket("/ws/chat/{room}", function ($connection, $event, $data) {
    match ($event) {
        "open" => $connection->send("Welcome to room " . $connection->params["room"]),
        "message" => $connection->broadcast($data),
        "close" => null,
    };
});
```

### Queues <a href="#queues" id="queues"></a>

Tina4 includes a queue system with multiple backends: LiteQueue (SQLite), MongoDB, RabbitMQ, and Kafka. Install `tina4stack/tina4php-queue` and use a single API for producing and consuming messages.

```php
use Tina4\Queue;

$queue = new Queue(topic: 'my-events');
$queue->produce('Hello World', userId: 'user123');

foreach ($queue->consume() as $message) {
    echo $message->data;
}
```

[More details](12-queues.md) on queues, their backends, and configuration.

### WSDL <a href="#wsdl" id="wsdl"></a>

Define your WSDL service as a class. Tina4 handles the XML, the WSDL generation, and the SOAP envelope.

```php
class Calculator extends \Tina4\WSDL {
    protected array $returnSchemas = [
        "Add" => ["Result" => "int"],
    ];

    public function Add(int $a, int $b): array {
        return ["Result" => $a + $b];
    }
}
```

Wire it to a route.

```php
<?php
use Tina4\Router;

Router::any("/calculator", function ($request, $response) {
    $calculator = new Calculator($request);
    $handle = $calculator->handle();
    return $response->xml($handle);
});
```

[More details](25-wsdl-soap.md) on WSDL services.

### GraphQL <a href="#graphql" id="graphql"></a>

```php
use Tina4\GraphQL;

\$schema = <<<GQL
type Query {
    hello(name: String!): String
    users: [User]
}

type User {
    id: Int
    name: String
    email: String
}
GQL;

\$resolvers = [
    "hello" => fn(\$args) => "Hello, " . \$args["name"] . "!",
    "users" => fn() => \$db->fetch("SELECT * FROM users")->toArray(),
];

\$graphql = new GraphQL(\$schema, \$resolvers);
```

Register the endpoint:

```php
Router::post("/graphql", function (\$request, \$response) use (\$graphql) {
    \$result = \$graphql->execute(\$request->body["query"] ?? "");
    return \$response->json(\$result);
})->noAuth();
```

GraphiQL UI available at `/__dev/graphql` in debug mode.

### Localization (i18n) <a href="#localization" id="localization"></a>

Set `TINA4_LOCALE=en` in `.env`. Place JSON files in `src/locales/`:

```json
// src/locales/en.json
{ "greeting": "Hello, {name}!" }
```

```php
$i18n = new I18n();
$i18n->t("greeting", ["name" => "Alice"]);  // "Hello, Alice!"

// Switch locale
$i18n->setLocale("fr");
```

[Back to top](index.md)

### HTML Builder <a href="#html-builder" id="html-builder"></a>

```php
$el = new HtmlElement("div", ["class" => "card"], ["Hello"]);
echo $el; // <div class="card">Hello</div>

// Nesting
$card = new HtmlElement("div", ["class" => "card"], [
    new HtmlElement("h2", [], ["Title"]),
    new HtmlElement("p", [], ["Content"]),
]);

// Helper functions
extract(HtmlElement::helpers());
echo $_div(["class" => "card"], $_h1("Title"), $_p("Description"));
```

### Events <a href="#events" id="events"></a>

Register listeners and fire them anywhere in the application.

```php
use Tina4\Events;

// Register a listener
Events::on("user.registered", function (array $payload): void {
    echo "New user: " . $payload["email"];
});

// Fire once -- listener is removed after first call
Events::once("app.boot", function (): void {
    echo "Booted!";
});

// Emit an event
Events::emit("user.registered", ["email" => "alice@example.com"]);
```

Multiple listeners can bind to the same event. They run in registration order.

### Logging <a href="#logging" id="logging"></a>

Write log messages through the `Debug` class. The level is controlled by `TINA4_LOG_LEVEL` in `.env`.

```php
use Tina4\Debug;

Debug::message("Starting import", TINA4_LOG_INFO);
Debug::message("Query took 2.3s", TINA4_LOG_WARNING);
Debug::message("Connection failed", TINA4_LOG_ERROR);
```

```bash
# .env
TINA4_LOG_LEVEL=ALL    # DEBUG | INFO | WARNING | ERROR | NONE
```

Log output goes to `src/logs/` by default. Set `TINA4_LOG_DIR` to change the destination.

### Response Cache <a href="#response-cache" id="response-cache"></a>

Chain `->cache()` onto any route handler to store the response. Subsequent requests within the TTL skip the handler entirely.

```php
use Tina4\Router;

Router::get("/api/products", function ($request, $response) {
    $db = \Tina4\Database\Database::getConnection();
    return $response->json($db->fetch("SELECT * FROM products")->toArray());
})->cache(300); // cache for 300 seconds

// Cache with a custom key
Router::get("/api/report/{year}", function ($request, $response) {
    return $response->json(buildReport($request->params["year"]));
})->cache(3600, "report-" . date("Y"));
```

Set `TINA4_CACHE_BACKEND=true` in `.env` to activate caching globally.

### Health Endpoint <a href="#health" id="health"></a>

Tina4 exposes a built-in health check at `/health`. No setup required.

```bash
curl http://localhost:7146/health
```

```json
{
  "status": "ok",
  "uptime": 142,
  "memory_mb": 12.4,
  "php": "8.3.0",
  "tina4": "3.10.20"
}
```

Add custom checks by registering a `health.check` event listener.

```php
use Tina4\Events;

Events::on("health.check", function (array &$report): void {
    $report["db"] = \Tina4\Database\Database::getConnection()->ping() ? "ok" : "fail";
});
```

### DI Container <a href="#container" id="container"></a>

Register services once and resolve them anywhere. Singletons share one instance across the request lifecycle.

```php
use Tina4\Container;

// Bind a factory
Container::register("mailer", fn() => new Mailer($_ENV["TINA4_MAIL_HOST"]));

// Bind a singleton
Container::singleton("db", fn() => \Tina4\Database\Database::getConnection());

// Resolve
$mailer = Container::get("mailer");
$db     = Container::get("db");
```

Route handlers receive resolved dependencies automatically when type-hinted parameter names match registered keys.

### Error Overlay <a href="#error-overlay" id="error-overlay"></a>

When `TINA4_DEBUG=true`, unhandled exceptions render an interactive overlay in the browser instead of a blank 500 page. The overlay shows the stack trace, request details, and the source file at the point of failure. No configuration needed, it activates automatically.

```bash
# .env
TINA4_DEBUG=true
```

In production set `TINA4_DEBUG=false`. Errors log to `src/logs/` and return a plain `500` response.

### Dev Admin <a href="#dev-admin" id="dev-admin"></a>

Point a browser at `/__dev` while the dev server is running to open the admin dashboard.

```bash
tina4 serve
# open http://localhost:7146/__dev
```

The dashboard surfaces routes, registered middleware, environment variables, recent log entries, active queue workers, and the GraphiQL interface. It is disabled automatically when `TINA4_DEBUG=false`.

### CLI Commands <a href="#cli" id="cli"></a>

```bash
# Scaffold a new project
tina4 init php my-project

# Start the dev server (default port 7146)
tina4 serve

# Start on a custom port
tina4 serve --port 8080

# Run inline tests
tina4 test

# Create a migration
tina4 migrate:create add-users-table

# Run all pending migrations
tina4 migrate

# Rollback the last migration
tina4 migrate:rollback

# Generate CRUD for a model
tina4 crud User
```

### MCP Server <a href="#mcp" id="mcp"></a>

Tina4 ships an MCP (Model Context Protocol) server that starts automatically when `TINA4_DEBUG=true`. AI assistants connect to it to inspect routes, models, and data without leaving the editor.

```bash
# .env
TINA4_DEBUG=true
TINA4_MCP_PORT=7147   # optional override, defaults to main port + 1
```

```bash
# Verify the server is running
curl http://localhost:7147/mcp/manifest
```

The manifest lists every route, ORM model, and migration. Disable it in production by setting `TINA4_DEBUG=false`.

### FakeData <a href="#fakedata" id="fakedata"></a>

Generate realistic test data without an internet connection. `FakeData` ships with Tina4, no extra packages required.

```php
use Tina4\FakeData;

$fake = new FakeData();

echo $fake->name();          // "Alice Johnson"
echo $fake->email();         // "alice.johnson@example.com"
echo $fake->phone();         // "+1-555-0123"
echo $fake->address();       // "42 Maple Street, Springfield"
echo $fake->company();       // "Acme Corp"
echo $fake->lorem(10);       // 10 words of placeholder text
echo $fake->integer(1, 100); // random int between 1 and 100
echo $fake->uuid();          // "f47ac10b-58cc-4372-a567-0e02b2c3d479"

// Seed for reproducible output
$fake = new FakeData(seed: 42);
```

Use `FakeData` inside migrations, seeders, or test fixtures.

### OpenID Connect SSO <a href="#sso" id="sso"></a>

Configure any standard OIDC issuer, then use the normal secured-route gate and
Tina4 Session. See [OpenID Connect SSO](./41-sso.md) for the complete client API.

### GIS and PostGIS <a href="#gis" id="gis"></a>

Declare a Point field, query metres, and return GeoJSON. Coordinates are
longitude then latitude. See [GIS and PostGIS](./42-gis.md).

### IoT and MQTT <a href="#iot-mqtt" id="iot-mqtt"></a>

Use the MQTT 3.1.1 client for QoS 0/1 telemetry, retained state, Last Will, and
verified TLS. See [IoT and MQTT](./43-iot-mqtt.md).

***

## 📕 Download the book

[**Tina4 for PHP Developers** (PDF)](/pdfs/Tina4-for-PHP-Developers.pdf), full reference, printable, with clickable table of contents and PDF outline. Regenerated with every release.
