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

Quick start

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

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 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_rewrite for 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.

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

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