Search by

sailantis / azera-app

lumielis

A starter project for the Azera PHP framework

Package info

github.com/sailantis/azera-app

Type:project

pkg:composer/sailantis/azera-app

Statistics

Installs: 1

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v0.4.0 2026-11-14 21:53 UTC

This package is auto-updated.

Last update: 2026-11-14 22:00:42 UTC


README

A starter application for the Azera PHP Framework. It includes MVC routing, Clarity templates, PSR-4 autoloading and a console.

Requirements

  • PHP >= 8.2
  • Composer
  • ext-pdo and ext-mbstring

Getting Started

1. Create the Project

composer create-project sailantis/azera-app my-app
cd my-app

create-project downloads the skeleton, installs sailantis/azera-framework and its dependencies, and leaves you without the upstream Git history, so the project is ready to become your own repository.

Alternatively, clone the repository and run composer install yourself.

2. Configure the Environment (optional)

The application can start without this file. Database tasks require it. Create env.php from the example:

cp env.example.php env.php

When env.php exists, boot() loads it and registers a lazy default database connection using the DB_* constants. The connection is opened when a query runs.

3. Run the Development Server

composer serve

Or use the Azera CLI directly:

php vendor/bin/azera serve

Both commands start the server at http://localhost:8000 by default. Pass --port= to use a different port:

php vendor/bin/azera serve --port=8080

4. Use the CLI

# List registered routes
php vendor/bin/azera routes:list

# Show the framework version, resolved bootstrap and view engine
php vendor/bin/azera about

# List available tasks and actions
php vendor/bin/azera help

The composer routes and composer db scripts run routes:list and db:tables, respectively.

Project Structure

azera-app/
├── app/
│   ├── Bootstrap.php           # BootstrapProvider: views, database, routes
│   └── Controllers/            # Your controllers
│       └── IndexController.php
├── public/
│   └── index.php               # Entry point
├── tests/
│   └── RoutesTest.php          # Smoke tests for the shipped routes
├── views/                      # Clarity templates
│   ├── home.clarity.html
│   └── about.clarity.html
├── env.example.php             # Environment example
├── phpunit.xml
└── composer.json

Routing

app/Bootstrap.php implements Azera\Boot\BootstrapProvider, which allows the azera CLI to discover and start the application. Add routes in registerRoutes():

private function registerRoutes(Router $router): void
{
    $router->controller(Controllers\IndexController::class, function (Router $r): void {
        $r->get('/', '::indexAction');
        $r->get('/about', '::aboutAction');
        $r->get('/hello/{name}', '::helloAction');
    });
}

A handler must be a string. Supported forms include 'Controller::action', ::action inside a controller() block, and an array of strings such as ['controller' => IndexController::class, 'action' => 'indexAction']. Closures and objects are not supported because the route table must be serializable for the route cache.

Path variables are passed to the action as parameters with matching names:

public function helloAction(string $name): string
{
    return 'Hello ' . $name;
}

Enabling the route cache

Wrap the route declarations in cached(). This enables caching and identifies the files used to check whether the route table is current:

$router->cached(__FILE__, function (Router $r): void {
    // ...routes...
});

The first request that reads the router builds the table and writes it to a derived temporary path. Later requests load the cached table with require. routes:status reports whether the cache is current, routes:cache rebuilds it, and routes:clear removes it.

Controllers

Create a controller in app/Controllers/ that extends Azera\Core\Controller:

<?php

namespace App\Controllers;

use Azera\Http\Request;
use Azera\Http\Response;

class HelloController extends \Azera\Core\Controller
{
    public function greetAction(Request $request, string $name): Response
    {
        return Response::json([
            'title' => 'Hello ' . $name,
            'secure' => $request->isSecure(),
        ]);
    }
}

The dispatcher converts action return values as follows: a Response is sent unchanged, a string becomes an HTML response, an array becomes JSON, an int is used as the status code, and null becomes status 204. The container injects parameters typed as Request.

Views

The starter renders Clarity templates from views/. configureViews() registers a lazy factory for the view engine, so booting the application does not create the engine:

private function configureViews(AppContext $ctx): void
{
    $viewsPath = \dirname(__DIR__) . '/views';

    $ctx->set(
        ViewEngine::class,
        fn() => (new ClarityEngine())->setViewPath($viewsPath),
    );
}

Render a template from a controller with $this->view()->render('home', ['title' => 'Welcome']). The .clarity.html extension is implied. Run php vendor/bin/azera make:view users.index to create views/users/index.clarity.html.

Database

Define the DB_* constants in env.php. boot() registers a factory for the default database role, so its PDO connection opens on first use:

$db = \Azera\AppContext::instance()->dbManager()->get('default');
$rows = $db->query('SELECT * FROM users')->fetchAll();

Useful tasks:

php vendor/bin/azera db:tables              # List tables
php vendor/bin/azera db:table <name>        # Show a table's columns
php vendor/bin/azera db:query "SELECT 1"    # Run raw SQL
php vendor/bin/azera migrate:diff           # Model definitions vs. live schema
php vendor/bin/azera model:sync <Model>     # Sync a model from its table

Add roles with dbManager()->set('analytics', fn() => new Database(...)), then retrieve them with get('analytics').

Testing

composer test

PHPUnit reads phpunit.xml and runs the tests in tests/. tests/RoutesTest.php starts the application, matches each included route and checks the rendered page. Run php vendor/bin/azera test to execute the same suite through the CLI.

License

MIT

Resources