viames/pair

lightweight PHP framework as the air

3.0.0-alpha 2026-02-28 07:40 UTC

Requires

• php: ^8.3||^8.4||^8.5
• ext-curl: *
• ext-intl: *
• ext-json: *
• ext-mbstring: *
• ext-pdo: *
• psr/log: ^1.1|^2.0|^3.0

Suggests

• ext-xdebug: *

MIT

• Viames Marino

• framework
• php
• active-record
• pair
• multilingual
• rest-api
• plugin-system

README

Website | Wiki | Issues

Pair is a lightweight PHP framework for server-rendered web applications. It focuses on fast setup, clear MVC routing, practical ORM features, and optional integrations (Aircall, S3, SES, Sentry, Telegram, Push, Passkey) without heavy tooling.

What's New

Pair v3 is currently in alpha and includes breaking changes compared to previous major versions.

Quick Start

1) Install with Composer

composer require viames/pair

2) Bootstrap the application

<?php

use Pair\Core\Application;

require 'vendor/autoload.php';

$app = Application::getInstance();
$app->run();

3) Next Steps

• Wiki
• Routing
• Configuration (.env)
• Boilerplate project

Why Pair

• Small and fast for small/medium projects.
• MVC structure with SEO-friendly routing.
• ActiveRecord-style ORM with automatic type casting.
• Plugin-oriented architecture (modules/templates).
• Good defaults for timezone, logging, and framework utilities.
• Optional third-party integrations when needed.

Core Features

ActiveRecord

Pair maps classes to DB tables and supports automatic casts (int, bool, DateTime, float, csv), relation helpers, and caching-oriented query helpers.

Docs: ActiveRecord

Routing Basics

Default route format (after base path):

/<module>/<action>/<params...>

Example: example.com/user/login

• module: /modules/user
• controller: /modules/user/controller.php (extends Pair/Core/Controller.php)
• action: loginAction() when present
• auto-loaded by convention: model.php, viewLogin.php (UserViewLogin), and /modules/user/layouts/login.php

Docs: Router

Log Bar and Debugging

Built-in log bar for loaded objects, memory usage, timings, SQL traces, backtraces, and custom debug messages.

Frontend Helpers

PairUI

Dependency-free helper for progressive enhancement in server-rendered apps (assets/PairUI.js).

Main directives:

• data-text, data-html, data-show, data-if
• data-class, data-attr, data-prop, data-style
• data-model, data-on, data-each

Docs: PairUI.js

PWA Helpers (No Build Step)

Available assets:

• PairPWA.js
• PairSW.js
• PairRouter.js
• PairSkeleton.js
• PairDevice.js
• PairPasskey.js

Minimal frontend setup:

<script src="/assets/PairUI.js" defer></script>
<script src="/assets/PairPWA.js" defer></script>
<script src="/assets/PairRouter.js" defer></script>
<script src="/assets/PairSkeleton.js" defer></script>
<script src="/assets/PairDevice.js" defer></script>
<script src="/assets/PairPasskey.js" defer></script>

Important notes:

• Keep progressive enhancement.
• Service workers require HTTPS (except localhost).
• Use a single SW URL if you also enable Push.

Passkey Quick Start

Backend:

class ApiController extends \Pair\Api\PasskeyController {}

This enables:

• POST /api/passkey/login/options
• POST /api/passkey/login/verify
• POST /api/passkey/register/options (requires sid)
• POST /api/passkey/register/verify (requires sid)
• GET /api/passkey/list (requires sid)
• DELETE /api/passkey/revoke/{id} (requires sid)

Third-Party Integrations

Pair includes optional support for services such as:

• Aircall
• Amazon S3
• Amazon SES
• ELK Stack
• InsightHub
• Sentry
• Telegram Bot API
• OneSignal
• Stripe

Configuration reference: Configuration (.env)

Upgrading

If you are upgrading between major versions:

composer run upgrade-to-v2
composer run upgrade-to-v3

To test unreleased code from main:

composer require viames/pair dev-main

Documentation

Main docs live in the Wiki.

Useful pages:

• Application
• Controller
• View
• Form
• Collection
• Push notifications
• index.php
• .htaccess
• classes

Requirements

Software	Recommended	Minimum	Configuration
Apache	2.4+	2.4	modules: mod_rewrite
MySQL	8.0+	8.0	character_set: utf8mb4 collation: utf8mb4_unicode_ci storage_engine: InnoDB
PHP	8.4+	8.3	Composer-required extensions: curl, intl, json, mbstring, PDO

Runtime notes:

• pdo_mysql is required when using the default MySQL driver (Pair\\Orm\\Database).
• fileinfo is strongly recommended for reliable MIME detection in uploads.
• openssl is required only for Passkey/WebAuthn features.
• pcre and Reflection are part of standard PHP 8+ builds.

Example Project

Start from pair_boilerplate to bootstrap a new app quickly.

Support

• Issues: github.com/viames/pair/issues
• Wiki: github.com/viames/pair/wiki
• Source: github.com/viames/pair/tree/master/src
• Homepage: viames.github.io/pair

Changelog

Version history is available in GitHub Releases: github.com/viames/pair/releases

Security

If you discover a security issue, please open a GitHub issue with a clear description and steps to reproduce.

Contributing

Feedback, code contributions, and documentation improvements are welcome via pull request.

License

MIT