README

Stage is a PHP framework for people and coding agents. It provides HTTP routing, request and response values, and caller permission checks. Write your application rules in typed PHP objects and pass dependencies through their constructors.

Requires PHP 8.4 or later within PHP 8. Stage is open source under MIT. Version 0.2 is an early release. The API can change between minor versions before 1.0. Read the changelog before updating.

Create an application

Install PHP 8.4 or later within PHP 8 and Composer. In a new application directory:

mkdir stage-app
cd stage-app
composer require skyyware/stage:^0.2
mkdir public

For an existing Composer project, install the same package:

composer require skyyware/stage:^0.2

Composer installs the tagged package from Packagist. No GitHub account or custom repository setting is required. Commit your application's composer.lock.

Create public/index.php in your application:

<?php
declare(strict_types=1);

use Stage\Http\Application;
use Stage\Http\Response;
use Stage\Http\Route;

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

(new Application(
	Route::get('/', fn () => Response::json(['hello' => 'world'])),
))->run();

Start PHP's local development server from the application directory:

php -S 127.0.0.1:8080 -t public public/index.php

Open http://127.0.0.1:8080. The response is {"hello":"world"}. Press Ctrl+C to stop the server.

Keep vendor/ outside public/. Use only public/ as the web root when you configure a production server. PHP's built-in server is for local development.

Continue with routes and JSON input to add an endpoint and check successful, malformed, and rejected requests.

Keep rules in your application

Pass dependencies through constructors. No global container is required.
Validate external input and turn it into typed values before calling an operation.
Check permissions inside the operation, including calls outside HTTP.
Define a PHP interface when another feature needs to call yours.
Test successful, denied, and malformed calls in your application.

Stage requires no other production Composer packages. Choose your application's testing and analysis tools. Installing Stage does not install its development tools or add a composer check command to your application.

Documentation

Start with the guide that matches your next task:

Task	Guide
Add routes, accept JSON, and check responses	Build your first HTTP application
Accept file uploads and stream downloads	Transfer files
Package reusable routes as an idea	Share an idea
Keep rules and permissions in reusable PHP objects	Compose features
Look up HTTP methods, errors, and limits	HTTP reference
Give a coding agent a bounded application task	Work with agents
Understand the core's responsibilities and tradeoffs	Design and principles
Change the framework or publish a package version	Contributing and releases

Choose a package

Install only the packages your application needs:

Stage CMS adds editing, revisions, publication, and scoped agent access.
Stage Chat defines a stateless chat contract without a provider dependency.
Stage Chat Codex implements that contract with an isolated Codex CLI process.

Each package has its own installation guide, version, and MIT license.

Current scope

The core provides literal and named-parameter HTTP routes, bounded request bodies, JSON responses, validated PHP uploads, streamed file downloads, inline media with single byte ranges, and an optional caller permission value. Authentication, persistence, queues, templates, and agent integrations belong to your application or a package you choose.

Ordinary message bodies are buffered. File downloads use bounded chunks; PHP handles multipart uploads before dispatch. Worker lifecycle and performance under load have not been validated. See the design for the current boundaries.

License

MIT. To work on the framework itself, follow contributing. Maintainers follow the package release guide.

skyyware / stage

Package info

Security

Statistics