Pair

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.

Status

Line	Status	Use
Pair 4	Stable	New and current applications
Pair 3	Maintenance	Existing applications awaiting migration

Pair 4 is used in production across the maintainer's applications. See Releases for version history and UPGRADE_V4.md for migration guidance.

Quick start

Install the stable release:

composer require viames/pair:^4.0

Bootstrap an application:

<?php

use Pair\Core\Application;

require __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

Why Pair

• 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

A Pair 4 page

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.

Main capabilities

Web and data

• 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

APIs and clients

• 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

Progressive enhancement

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.

Requirements

• PHP 8.4.1 or later
• MySQL 8.0 or later for the default database driver
• Composer 2
• Apache 2.4 with mod_rewrite for the standard web setup
• PHP extensions: curl, intl, json, mbstring, pdo, pdo_mysql

Feature-specific extensions such as fileinfo, openssl, redis and xdebug remain optional.

Development

composer install
composer test
composer run benchmark-v4

Generate 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_amount

Upgrade 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.

Documentation

• Application
• Router
• Controller
• ActiveRecord
• Forms
• API exposure
• CRUD controllers
• PairUI
• Configuration
• Pair 4 design
• Pair 4 upgrade guide

Security

Report vulnerabilities privately by following SECURITY.md. Do not open a public issue for an unassessed security report.

Contributing

Focused pull requests are welcome. Include tests when behavior changes and update the owning documentation when commands, requirements or public contracts change.

License

MIT