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.

Quick start · Requirements · Documentation · Development

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. The release history lists published versions; see the upgrade guide for migration from earlier lines.

Quick start

With the requirements installed, create a ready-to-run application with authentication, ACL, migrations and localization:

composer create-project viames/pair_boilerplate my-project

To add the framework to an existing project:

composer require "viames/pair:^4.1.3"

Configure the application's .env and database using the setup guide, then bootstrap in public/index.php:

<?php

use Pair\Core\Application;

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

Application::getInstance()->run();

Why Pair

• Explicit controllers, typed page state and page, fragment, JSON, text and empty responses
• ActiveRecord persistence, casting, relations and collections
• Forms, validation, CSRF, authentication, ACL and sessions
• API and CRUD tooling with explicit read models and OpenAPI contracts
• PairUI progressive enhancement, PWA, push and passkeys without a mandatory frontend build
• Native iOS/Android helpers and optional integrations
• Conservative upgrade tooling, logging, diagnostics and tests across supported PHP versions

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.

For a complete controller/state/layout example, see the implementation patterns.

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

From the framework checkout:

composer install
composer test

Use composer run benchmark-v4 for migration/performance checks when relevant.

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

For upgrades, follow UPGRADE_V4.md, start from a clean working tree or verified backup, and pass --dry-run explicitly before writing changes. Tool mode defaults differ between upgrade generations.

Documentation

Choose a guide by task:

Task	Guide
Set up an application	Bootstrap, configuration, starter project
Learn the framework or find a class	Wiki learning paths and reference index
Generate a web, API or CRUD module	Generator
Migrate an existing application	Pair 4 upgrade guide
Connect native clients	Mobile auth setup, iOS, Android
Work on the framework with an agent	AGENTS.md, then quick start and source map
Understand v4 internals and design	Architecture, design rationale
Release or inspect package contents	Release workflow, Composer dist contents

The wiki follows main and may document unreleased changes. Compare examples with the source for the Pair version installed in your application.

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