viames / pair

4.1.12 2026-11-07 11:24 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-11-07 11:26 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.

Quick start · Application development · Requirements · Documentation · Development

Status

Line	Status	Use
Pair 4 releases	Stable	New and current applications
Pair 4 main	Unreleased	Framework development and upcoming changes
Pair 3	Maintenance	Existing applications awaiting migration

The current stable release is Pair 4.1.12.

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 an application with authentication, ACL, migrations and localization:

composer create-project viames/pair_boilerplate my-project
cd my-project

The stable starter 4.0.0 requires Pair ^4.1.12. Composer resolves stable dependencies and creates the new application's own composer.lock; commit that lock with your application.

1. Serve the project through Apache with mod_rewrite and .htaccess overrides enabled. If it is inside your local document root, open http://localhost/my-project/; otherwise use your configured virtual-host URL. See the starter setup for the Apache configuration.
2. Follow the browser installer using a dedicated new or empty MySQL database and an account permitted to initialize it. The installer imports the schema and seed data, writes .env and creates the first administrator. It requires fileinfo in addition to the framework's required PHP extensions.
3. Log in with the generated credentials, change the initial password and run the administrator's Self test module.

For an existing application, install the framework directly:

composer require "viames/pair:^4.1.12"

Then follow the bootstrap guide and environment reference to configure its database and public/index.php.

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

An explicit controller passes a named, immutable state object to its layout. These files belong to an application's modules/welcome/ directory.

classes/WelcomePageState.php:

<?php

/** Data rendered by the welcome page. */
final readonly class WelcomePageState {

	/** Create the page state. */
	public function __construct(public string $message) {}

}

controller.php:

<?php

use Pair\Web\Controller;
use Pair\Web\PageResponse;

require_once __DIR__ . '/classes/WelcomePageState.php';

/** Render the welcome module. */
final class WelcomeController extends Controller {

	/** Return the default page with explicit state. */
	public function defaultAction(): PageResponse {

		return $this->page('default', new WelcomePageState('Hello Pair'), 'Welcome');

	}

}

layouts/default.php:

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

Application development

In the starter project, run generators through its local CLI wrapper:

composer run pair -- make:module orders
composer run pair -- make:api catalogapi
composer run pair -- make:crud order --table=orders --fields=id,customer_id,total_amount

Choose unused module names and review generated code using the generator guide. For an existing application's major-version upgrade, 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.

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

Pair 4.1.12 supports MySQL 26.10 alongside MySQL 8.0/8.4 and uses utf8mb4 connection defaults. The test matrix is described under Development. See the database reference and upgrade notes for connection behavior, existing schema requirements and rollout guidance.

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

For framework contributors, start with AGENTS.md and the source map. Run checks from the framework checkout:

composer install
composer test
composer test:install

The installation check tests real Composer archives and consuming projects offline. Add -- ../pair_boilerplate to verify stable starter creation as well; it needs the development-only PHP zip extension. Optional database checks use a guarded disposable schema and never read an application's credentials.

Database compatibility has a separate real-server suite: composer test:mysql. Provision a disposable schema and a restricted account using the MySQL integration guide. The configured CI matrix targets PHP 8.4/8.5 with MySQL 8.0, 8.4 and 26.10; the unit suite does not require a MySQL server.

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

For internals, see the architecture and database metadata cache. For publication, follow the release workflow and Composer package contents.

Documentation

Choose a guide by task:

Task	Guide
Start an application	Starter project, bootstrap, configuration
Build modules and APIs	Wiki learning paths and class reference, generator
Upgrade an application	Pair 4 upgrade guide
Contribute to Pair	Framework development, implementation patterns

For native clients, start with mobile auth setup, then the iOS or Android guide.

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

Maintainer

Pair is created and maintained by Viames Marino. His professional practice, VM Ingegneria, covers external technical direction, software modernization and governed AI integration.

For a professional project, use the VM Ingegneria contact form. For framework usage and contributions, use the documentation and repository channels above.

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