viames / pair

4.1.2 2026-10-02 10:12 UTC

Requires

• php: ^8.4.1
• ext-curl: *
• ext-intl: *
• ext-json: *
• ext-mbstring: *
• ext-pdo: *
• ext-pdo_mysql: *
• psr/log: ^1.1 || ^2.0 || ^3.0

Requires (Dev)

• phpunit/phpunit: ^13.0

Suggests

• ext-fileinfo: Recommended for reliable MIME detection in uploads.
• ext-openssl: Required for Passkey/WebAuthn features.
• ext-redis: Recommended for Redis-backed cache/session integrations.
• ext-xdebug: Useful while debugging Pair applications and tests.
• aws/aws-sdk-php: Required by Pair\Services\AmazonS3 for AWS S3 and S3-compatible object storage.
• stripe/stripe-php: Required by Pair\Services\StripeGateway for Stripe payments.

MIT

• Viames Marino

• framework
• orm
• php
• mysql
• composer
• mvc
• crud
• active-record
• pair
• multilingual
• openapi
• rest-api
• php-framework
• web-push
• server-side-rendering
• pwa
• passkey
• package-system
• runtime-extensions
• server-rendered
• progressive-enhancement

Published on Packagist.org on 2026-10-02 10:13 UTC

README

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

• 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