Skip to content
Antares

Application

Antares\Application is the entry point for every Antares app. It exposes a fluent API for wiring up providers, middleware, and the route layer before calling run().

Application::create(string $basePath): self

Creates the application instance. $basePath should be the root of your project (the directory that contains composer.json, .env, vendor/, app/ and storage/). It is used to load .env, find bridge packages, store the route cache, and is available as $_ENV['APP_BASE_PATH'].

->providers(array $providers): static

Registers service providers. These run on every boot, before route providers, and are used for container bindings and singletons.

->routeProviders(array $providers): static

Registers route providers. These are responsible for calling $router->register() with your controller classes. In production they are skipped when the route cache is valid, so only register routes here.

->middleware(array $middleware): static

Registers global middleware. Middleware runs in order on every request, wrapping the Dispatcher as the innermost layer. Middleware is resolved through the container, so it can take constructor dependencies (from v0.2.4). See Middleware.

->exceptions(array $map): static

Shows the listed exceptions to the client instead of hiding them behind a 500: [SomeException::class => 404] keeps the exception’s message, [SomeException::class => [409, 'Conflict']] replaces it. See Error Handling. An invalid map (a class that isn’t an exception, or a status outside 400–599) throws InvalidArgumentException right away.

providers(), routeProviders(), middleware() and exceptions() each replace their list, so calling one twice keeps only the second call’s list. Pass everything in one call.

MethodRuntimeWhat it does
->run(): voidPHP-FPM, php -S, any classic setupBoots, builds the request from PHP globals, handles it, and sends the response.
->runSwoole(string $host = '0.0.0.0', int $port = 8000): voidSwooleBoots once, then starts a Swoole HTTP server that handles every request with the same booted app. Requires the swoole extension and composer require ilexn/swoole-psr7.
->runWorker(): voidFrankenPHP worker modeBoots once, then handles requests in a loop with frankenphp_handle_request() until FrankenPHP stops the worker. Set MAX_REQUESTS to restart the worker after that many requests (a guard against memory leaks). Throws if not running under FrankenPHP.
->boot(): void + ->handle($request): ResponseInterfaceTests, custom runtimesboot() sets everything up; handle() runs one PSR-7 request through middleware, the Dispatcher and the error handler, and returns the response without sending it.

Under runSwoole() and runWorker() the app stays in memory between requests. Use scoped() for anything that holds per-request state.

See Boot Sequence for exactly what boot() does.

Application reads these from .env (or the real environment):

VariableDefaultEffect
APP_ENVlocalproduction turns on the route cache and changes the defaults of APP_DEBUG and APP_DOCS
APP_DEBUGon, off when APP_ENV=productionAdds the real error to 500 responses. See Error Handling
APP_DOCSon, off when APP_ENV=productionRegisters /openapi.json and /docs. See OpenAPI
MAX_REQUESTS0 (no limit)runWorker() only: restart each FrankenPHP worker after this many requests

APP_DEBUG and APP_DOCS accept true/false, 1/0, on/off and yes/no. Any other value falls back to the default.

Application::create(__DIR__ . '/..')
->providers([
AppServiceProvider::class,
DatabaseServiceProvider::class,
])
->routeProviders([
RouteServiceProvider::class,
])
->middleware([
CorsMiddleware::class,
AuthMiddleware::class,
LogMiddleware::class,
])
->exceptions([
EmailAlreadyTaken::class => 409,
])
->run();

Use boot() + handle() to test without emitting output:

use Antares\Application;
use Nyholm\Psr7\Factory\Psr17Factory;
$app = Application::create(__DIR__ . '/..')
->providers([AppServiceProvider::class])
->routeProviders([RouteServiceProvider::class]);
$app->boot();
$request = (new Psr17Factory())->createServerRequest('GET', '/users');
$response = $app->handle($request);
assert($response->getStatusCode() === 200);

boot() reads $_ENV, so set variables such as APP_ENV or APP_DEBUG before calling it. Call boot() once and reuse the app for every request in a test; handle() resets per-request state (scoped instances and ResponseBag headers) on each call.