Home

Pair framework documentation

Pair is a compact PHP framework for server-rendered applications. It combines a classic MVC flow, an ActiveRecord-oriented ORM, API tooling, and lightweight frontend utilities without forcing a heavy build chain.

The current stable release is Pair 4.1.3. This wiki tracks Pair v4 on the default main branch; unreleased changes may appear before the next tag. Pair v4 is the current stable line; the v3 branch and 3.x tags remain available for applications on the previous maintenance line.

The most useful way to read it is to distinguish between:

• class reference pages, which explain the main methods with examples and keep secondary methods concise
• workflow and integration pages, which focus on end-to-end patterns such as API modules, PWA features, or external service integrations

Install and configure

Pair requires PHP 8.4.1 or later within PHP 8, with PHP 8.4 and 8.5 as the target runtimes, and the Composer extensions curl, intl, json, mbstring, PDO, and pdo_mysql. Optional features may require additional extensions or packages; check the relevant integration page before using them.

Install Pair 4.1.3 or a later compatible Pair 4 release:

composer require "viames/pair:^4.1.3"

For a ready-to-run application, use the starter project. Configure the environment and database before running the bootstrap: see Configuration file, htaccess, and Env.

New modules should use Pair\Web\Controller and explicit responses. Pair\Core\Controller, Model, and View remain migration bridges; see Upgrade to v4.

Pair uses two distinct extension mechanisms:

• Installable Packages: ZIP/manifest packages for modules, templates, providers, or custom records; see InstallablePackage and InstallablePackageRecord.
• Runtime Extensions: explicit bootstrap registrations for adapters, services, UI renderers, routes, or configuration; see RuntimeExtensionInterface and AdapterRegistry.

Development and tests

Pair includes a lightweight PHPUnit suite for framework-level checks.

Typical local workflow:

• composer install
• composer test

Notes:

• the suite focuses on isolated framework behavior, so many tests do not require a full Pair application bootstrap
• vendor/ is a local install artifact and should not be committed to the Pair repository
• when you change observable framework behavior, update the relevant wiki page together with the code

Code generation

Pair v4 includes a small bin/pair generator for explicit web modules, API modules, and CRUD skeletons. Start from Generator when creating new Pair v4 files.

Recommended learning paths

1) Bootstrap and request lifecycle

Read index.php -> Application -> Router -> Controller -> Input -> UploadedFile -> PageResponse -> FragmentResponse -> ResponseInterface.

2) Build a CRUD module with explicit responses

Read Generator -> Controller -> PageResponse -> FragmentResponse -> ReadModel -> ActiveRecord -> Query -> Form.

3) Build a JSON API

Read API -> ApiController -> Request -> RequestData -> ApiResponse -> JsonResponse -> CrudController -> ReadModel -> Idempotency.

4) Authentication, session, and ACL

Read User -> Session -> ApiToken -> AuthAttemptLimiter -> SocialAuth -> Acl -> Rule -> OAuth2Token.

5) Native mobile API clients

Read Mobile auth app setup, Mobile iOS stack, and Mobile Android stack before wiring native apps directly to Pair authentication endpoints.

6) External services and integrations

Start from Integrations for optional SDK requirements and adapter registration, then use the relevant service reference below.

Navigation tree

• Pair framework
• Core runtime and MVC -> Application, Router, Controller, Input, UploadedFile, FileMediaType, ResponseInterface, PageResponse, FragmentResponse, JsonResponse, TextResponse, EmptyResponse, Model, View, Generator
• Forms and HTML layer -> Form, FormControl, FormValidationPreset, File, UiRenderer, UiTheme, UiLogBarRenderer, TemplateRenderer, Classes folder
• Data and ORM -> ReadModel, MapsFromRecord, ArraySerializableData, RecordMapper, Payload, ActiveRecord, Query, Database, Collection, JoinClause, QueryGrammar
• API stack -> API, ApiController, Request, RequestData, AuthorizationHeader, ApiResponse, ApiErrorResponse, ApiToken, CrudController, CrudResourceConfig, Middleware, RateLimiter
• Frontend and PWA -> PWA, PairUI.js, PairValidation.js, PairPush.js, PairPasskey.js, PwaConfig, PwaManifest
• Integrations and Runtime Extensions -> Integrations, RuntimeExtensionInterface, AdapterRegistry, AmazonS3, SocialAuth, OpenStreetMap, GoogleMaps, GoogleMapsClient, GoogleGeocoder, GooglePlacesService, GoogleAddress, Mailer, Sendmail, SmtpMailer, AmazonSes, ResendMailer, StripeGateway, OpenAIClient, GeminiClient, ClaudeClient, HumanChallenge, CloudflareTurnstile, MeilisearchClient, SupabaseClient, TelegramBotClient, WhatsAppCloudClient
• Security and operations -> User, Session, ApiToken, AuthAttemptLimiter, Acl, PasskeyAuth, Schedule, Log, Logger, LogEvent, ErrorLog, DatabaseLogWriter, LogEventSanitizer, LogEventFingerprint, Observability, ObservabilityAdapter, ObservabilityEvent, ObservabilityEventAdapter, SentryObservabilityAdapter, OpenTelemetryHttpExporter, OAuth2Client
• Native mobile stacks -> Mobile auth app setup, Mobile iOS stack, Mobile Android stack
• Push and notifications -> PushDispatcher, SubscriptionRepository, PushSubscription, WebPushSender, OneSignalNotification
• Packages and maintenance -> InstallablePackage, InstallablePackageRecord, Composer Dist Contents, Module, Template, Migration, Upgrade to v4
• UI helpers -> SweetAlert, SweetToast, IziToast, ChartJs, ChartJsDataset, AppTrait
• Misc helpers -> Translator, Locale, Language, Country, DateRange, Markdown, Report

Reading tips

• When a page is about a class, prefer it for method-by-method reference.
• When a page is about a feature area or hub such as API or Integrations, expect overview material, architecture notes, recipes, and cross-links rather than a full method inventory.
• Use composer show viames/pair to identify the version installed in an application. Compare its source with the matching Git tag; Pair 4.1.3 source is the current stable baseline, while this wiki follows main.