Home
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.
This wiki tracks the current Pair source in /Users/viames/Sites/pair.
The default main branch is the Pair v4 alpha line; the v3 branch and the 3.x tags remain the stable Pair v3 reference.
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
If you are new to Pair v4, begin with index.php, Application, Router, Controller, Input, PageResponse, and ReadModel. For legacy Pair v3-style modules, also read Model and View.
For project bootstrap and environment setup, read Configuration file, htaccess, and Env.
Pair v4 uses two official extension/package terms:
- Installable Packages are ZIP/manifest packages for modules, templates, providers, or custom package records, handled by InstallablePackage and InstallablePackageRecord.
- Runtime Extensions are explicit bootstrap registrations for adapters, services, UI renderers, routes, or integration configuration, handled through RuntimeExtensionInterface and AdapterRegistry.
Pair includes a lightweight PHPUnit suite for framework-level checks.
Typical local workflow:
composer installcomposer 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
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.
Read index.php -> Application -> Router -> Controller -> Input -> UploadedFile -> PageResponse -> ResponseInterface.
Read Generator -> Controller -> PageResponse -> ReadModel -> ActiveRecord -> Query -> Form.
Read API -> ApiController -> Request -> RequestData -> ApiResponse -> JsonResponse -> CrudController -> ReadModel -> Idempotency.
Read User -> Session -> Acl -> Rule -> OAuth2Token.
Start from Integrations, then move to the specific service area you actually need. Optional third-party support should use Runtime Extensions and manually registered adapters:
- storage -> AmazonS3
- maps and geocoding -> GoogleMaps, GoogleMapsClient, GoogleGeocoder, GooglePlacesService, GoogleAddress
- mail delivery -> Mailer, SendMail, SmtpMailer, AmazonSes, ResendMailer
- payments -> StripeGateway
- AI -> OpenAIClient, GeminiClient, ClaudeClient
- anti-bot -> CloudflareTurnstile
- search -> MeilisearchClient, SearchIndexableReadModel
- messaging and notifications -> TelegramBotClient, WhatsAppCloudClient
- Pair framework
- Core runtime and MVC -> Application, Router, Controller, Input, UploadedFile, FileMediaType, ResponseInterface, PageResponse, JsonResponse, TextResponse, EmptyResponse, Model, View, Generator
- Forms and HTML layer -> Form, FormControl, File, UiRenderer, TemplateRenderer, Classes folder
- Data and ORM -> ReadModel, MapsFromRecord, ArraySerializableData, RecordMapper, Payload, ActiveRecord, Query, Database, Collection, JoinClause, QueryGrammar
- API stack -> API, ApiController, Request, RequestData, ApiResponse, ApiErrorResponse, CrudController, CrudResourceConfig, Middleware, RateLimiter
- Frontend and PWA -> PWA, PairUI.js, PairPush.js, PairPasskey.js, PwaConfig, PwaManifest
- Integrations and Runtime Extensions -> Integrations, RuntimeExtensionInterface, AdapterRegistry, AmazonS3, GoogleMaps, GoogleMapsClient, GoogleGeocoder, GooglePlacesService, GoogleAddress, Mailer, SendMail, SmtpMailer, AmazonSes, ResendMailer, StripeGateway, OpenAIClient, GeminiClient, ClaudeClient, CloudflareTurnstile, MeilisearchClient, SupabaseClient, TelegramBotClient, WhatsAppCloudClient
- Security and operations -> User, Session, Acl, PasskeyAuth, Schedule, Log, ErrorLog, Observability, SentryObservabilityAdapter, OpenTelemetryHttpExporter
- Misc helpers -> Translator, Locale, Language, Country, DateRange, Markdown
Pair v4 explicit contracts: Input, UploadedFile, FileMediaType, ResponseInterface, PageResponse, JsonResponse, ReadModel, MapsFromRecord, RecordMapper, Payload.
API hardening and consistency: Middleware, ThrottleMiddleware, RateLimiter, Idempotency, QueryFilter, Resource.
Push, notifications, and passkeys: PushDispatcher, SubscriptionRepository, PushSubscription, WebPushSender, OneSignalNotification, PasskeyAuth, PasskeyController.
UI and visual helpers: UiRenderer, SweetAlert, IziToast, ChartJs, ChartJsDataset, Markdown, AppTrait.
Installable Packages, templates, and maintenance: InstallablePackage, InstallablePackageRecord, Module, Template, Migration, InsightHub, OAuth2Client, Observability, ObservabilityEvent, ObservabilityEventAdapter, SentryObservabilityAdapter, OpenTelemetryHttpExporter.
Service integrations: Integrations, AmazonS3, GoogleMaps, GoogleMapsClient, GoogleGeocoder, GooglePlacesService, GoogleAddress, Mailer, SendMail, SmtpMailer, AmazonSes, ResendMailer, StripeGateway, OpenAIClient, GeminiClient, ClaudeClient, CloudflareTurnstile, MeilisearchClient, SearchIndexableReadModel, SupabaseClient, TelegramBotClient, WhatsAppCloudClient.
- 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.
- When you need the exact runtime behavior, trust the class pages aligned with the current codebase under
/Users/viames/Sites/pair.
