A lightweight PHP framework for maintainable, server-rendered applications.
Website · Documentation · Starter project · Releases · Security
Pair is designed for small and medium PHP/MySQL applications where clear architecture, low operational overhead and long-term maintainability matter more than a heavy frontend toolchain.
It combines explicit MVC responses, an ActiveRecord-style ORM, CRUD and OpenAPI tooling, progressive enhancement, authentication helpers and conservative upgrade tooling in a codebase intended to remain inspectable by both people and AI-assisted workflows.
| Line | Status | Use |
|---|---|---|
| Pair 4 | Stable | New and current applications |
| Pair 3 | Maintenance | Existing applications awaiting migration |
Pair 4.1.2 is the current stable release. Pair 4 is used in production across the maintainer's applications. See Releases for version history and UPGRADE_V4.md for migration guidance.
Install Pair 4.1.2 or a later compatible Pair 4 release:
composer require "viames/pair:^4.1.2"Bootstrap the application in public/index.php after configuring its .env
and database (see the setup guide):
<?php
use Pair\Core\Application;
require dirname(__DIR__) . '/vendor/autoload.php';
$app = Application::getInstance();
$app->run();For authentication, ACL, migrations, localization and a ready-to-run application structure, start with the boilerplate:
composer create-project viames/pair_boilerplate my-project- Server-rendered applications without a mandatory frontend build chain
- Explicit controllers, responses and typed page-state objects in Pair 4
- ActiveRecord-style ORM with casting, relations and query helpers
- CRUD generators and OpenAPI-oriented API contracts
- PairUI progressive enhancement with no runtime dependency
- PWA, push, passkey and native mobile helpers
- Conservative, dry-run-first migration tools
- Focused tests and CI across supported PHP versions
- Optional integrations without forcing them into the core runtime
Pair 4 favors explicit responses over hidden view bootstrapping:
<?php
use Pair\Web\Controller;
use Pair\Web\PageResponse;
final class UserController extends Controller {
public function defaultAction(): PageResponse {
$state = new class ('Hello Pair') {
public function __construct(public string $message) {}
};
return $this->page('default', $state, 'User');
}
}The corresponding layout stays presentation-focused:
<main class="user-page">
<h1><?= htmlspecialchars($state->message, ENT_QUOTES, 'UTF-8') ?></h1>
</main>Default routes use the form /<module>/<action>/<params...>. Legacy Pair
controllers and views remain available as migration bridges, while new Pair 4
modules should use explicit response contracts.
- MVC routing and explicit page, JSON, redirect, file and stream responses
- ActiveRecord-style persistence, collections, relations and type casting
- Form controls, validation presets and CSRF protection
- Authentication, ACL and session helpers
- Logging, SQL traces and development diagnostics
- CRUD-oriented API controllers and explicit read models
- OpenAPI-oriented response contracts
- OAuth2 and bearer-session building blocks
- iOS and Android helpers for Pair-backed applications
PairUI adds lightweight data-* directives for text, visibility, attributes,
events, models and repeated content. Additional helpers cover PWA installation,
service workers, routing, skeleton states, validation, passkeys and push
notifications while preserving server-rendered behavior.
See PairUI.js and the documentation index for examples.
- PHP 8.4.1 or later within PHP 8.x; PHP 8.5 recommended
- MySQL 8.0 or later for the default database driver
- Composer 2
- Apache 2.4 with
mod_rewritefor the standard web setup - PHP extensions:
curl,intl,json,mbstring,pdo,pdo_mysql
Feature-specific extensions are optional for the core runtime: fileinfo for
MIME detection, openssl for passkeys, redis for Redis integrations and
xdebug for debugging. AWS S3 and Stripe integrations also require their
respective SDKs; see Integrations.
composer install
composer test
composer run benchmark-v4Generate Pair 4 code from an application that has Pair installed:
vendor/bin/pair make:module orders
vendor/bin/pair make:api api
vendor/bin/pair make:crud order --table=orders --fields=id,customer_id,total_amountUpgrade tools operate in dry-run mode first and report application-specific code that still requires manual migration. Follow UPGRADE_V4.md and begin from a clean working tree or verified backup.
- Application
- Router
- Controller
- ActiveRecord
- Forms
- API exposure
- CRUD controllers
- PairUI
- Configuration
- Pair 4 design
- Pair 4 upgrade guide
Report vulnerabilities privately by following SECURITY.md. Do not open a public issue for an unassessed security report.
Focused pull requests are welcome. Include tests when behavior changes and update the owning documentation when commands, requirements or public contracts change.
MIT