README

Small PHP 8.4 web framework: FastRoute routing, Latte views, noirapi/database models, Tracy debugging, NEON config, and pluggable auth (password, magic link, TOTP, GitHub/Google OAuth).

Package: noirapi/framework, namespace Noirapi\, PHP ^8.4, MIT.

Installation

There are two supported layouts, and they run the same code (Noirapi\Lib\Kernel).

Composer (new projects)

composer require noirapi/framework

Project layout. Every path is relative to the project root, which the kernel is given:

myapp/
  app/
    Route.php            App\Route: process($method, $uri) -> FastRoute dispatch result
    controllers/ models/ views/ layouts/
    config/default.neon  picked by the CONFIG env var, else the virtual host name, else "default"
  htdocs/index.php       web root
  temp/  logs/           must exist and be writable (Latte/config cache, Tracy logs)
  data/                  SQLite databases with relative DSNs
  vendor/
  composer.json          "autoload": {"classmap": ["app/"]}

htdocs/index.php:

<?php

declare(strict_types=1);

require dirname(__DIR__) . '/vendor/autoload.php';

Noirapi\Lib\Kernel::run(dirname(__DIR__));

CLI scripts only boot (config, timezone, sessions, Tracy):

require __DIR__ . '/../../vendor/autoload.php';
Noirapi\Lib\Kernel::boot(__DIR__ . '/../..');

Tools are exposed as one Composer binary (see docs/cli.md):

vendor/bin/noirapi dev-server start [--port 8000] [--host localhost] [--config NAME]
vendor/bin/noirapi dev-server stop|restart|status
vendor/bin/noirapi latte-lint app/views
vendor/bin/noirapi latte-check [--strict] [--no-controller-check]
vendor/bin/noirapi latte-format [--check] [paths]   # tidy templates
vendor/bin/noirapi crawl crawl.json [--start]   # see docs/crawl.md
vendor/bin/noirapi cache:clear | config:check | routes:list | key:generate
vendor/bin/noirapi make:controller Name | make:model Name | db:migrate

git submodule (existing projects)

Existing apps keep the framework checked out at <root>/noirapi/ and use the legacy entry points, which are thin shims over the same kernel:

require dirname(__DIR__) . '/noirapi/kernel.php';   // htdocs/index.php and CLI scripts
require dirname(__DIR__) . '/noirapi/include.php';  // bootstrap only

noirapi/bin/dev-server start
noirapi/bin/latte-lint app/views
php noirapi/bin/latte-check.php

See UPGRADE.md for what a submodule app needs when it updates to 1.x, and for moving it to the Composer layout.

How the application root is found

Noirapi\Config::getRoot() resolves, in order:

the root passed to Kernel::run() / Kernel::boot();
the NOIRAPI_ROOT environment variable (vendor/bin/noirapi and dev-server set it);
the submodule layout: the framework's parent directory, when it contains app/;
the Composer layout: the root of the Composer install that contains noirapi/framework.

The framework's own files (bundled templates, bin scripts) are found with Config::getFrameworkDir().

Documentation

Routing, Controllers, Views, Layouts
Database, Sessions, Mail
Command line, Security (trusted proxies, CSRF, headers/CSP, rate limits), Authentication
Configuration reference, Validation, Swoole

Development

composer install
composer test        # PHPUnit
composer phpstan     # PHPStan (level 5)
composer psalm       # Psalm 7 (level 4, purity annotations required)
composer phpmd       # PHPMD 3
composer phpcs       # PSR-12
composer coverage    # coverage summary (needs pcov or Xdebug)

Releases are tagged vX.Y.Z on master. CI (.github/workflows/ci.yml) runs the tests and then notifies Packagist; it needs the PACKAGIST_USERNAME and PACKAGIST_TOKEN repository secrets.

noirapi / framework

Package info

Security

Statistics