README

Skeleton project for building applications with Pair PHP Framework.

This repository provides a ready-to-install baseline for small and medium PHP applications such as CRM tools, internal portals and web back offices. It includes authentication, users and groups, ACL management, localization, a REST API entry point, OAuth2 support, migrations and a generator for CRUD modules.

The project targets the stable Pair 4 release line. Bundled modules use the explicit Pair 4 web path based on Pair\Web\Controller, PageResponse and typed *PageState classes. The crafter module generates Pair 4-style controller, state and layout files for new modules, while legacy implicit View variables are retained only where migration compatibility still requires them.

Release status

Starter 4.0.0 targets stable Pair ^4.1.12. The previous starter 3.x belongs to Pair 3. The installation below selects the Pair 4 starter explicitly. See RELEASING.md for tests, publication order and the public installation gate.

Requirements

PHP 8.4.1 or later within PHP 8; PHP 8.4 and 8.5 are tested.
MySQL 8.0 or later; fresh installation is tested on 8.0, 8.4 and 26.10.
Apache with mod_rewrite enabled.
Composer.
PHP extensions:
- curl
- fileinfo
- intl
- json
- mbstring
- pdo
- pdo_mysql

Installation

Create a new project with Composer:

composer create-project viames/pair_boilerplate my_project_name "^4.0"

Open the project URL in the browser:

http://localhost/my_project_name

The installer starts automatically when the root URL is opened for the first time. It checks the environment, creates a new database or accepts an empty one, imports the Pair 4 baseline schema and seed data, writes the .env file, creates the first administrator account and removes itself after a successful installation.

A populated database is rejected before schema, seed or collation writes. Use the migration runner for an existing application.

After installation, open the application URL and log in with the generated administrator credentials shown by the installer. Change the generated password after the first login.

Apache Configuration

On Debian/Ubuntu, enable Apache mod_rewrite with the distribution command below. On other systems, enable the module through that Apache installation:

sudo a2enmod rewrite

Make sure the project directory allows .htaccess rules. A typical configuration is:

<Directory /var/www/html>
    Options Indexes FollowSymLinks
    AllowOverride All
</Directory>

MySQL Configuration

Use a dedicated new or empty database. The installer creates its schema with utf8mb4 and utf8mb4_unicode_ci; Pair configures communication at the connection level. Existing server-wide charset, SQL-mode and authentication settings do not need to be replaced by a boilerplate-specific MySQL configuration.

The installation account needs access to initialize only this application's schema. Do not give it unrelated application databases. The installer refuses a schema containing tables, including before changing its default collation.

Configuration

Runtime configuration is stored in .env. Fresh installations generate it automatically from the installer. For existing installations, use .env.example as the reference structure.

Important Pair options include:

PAIR_AUDIT_ALL
PAIR_SINGLE_SESSION
PAIR_AUTH_BY_EMAIL
PAIR_LOGGER_EMAIL_RECIPIENTS
PAIR_LOGGER_EMAIL_THRESHOLD
PAIR_LOGGER_TELEGRAM_CHAT_IDS
PAIR_LOGGER_TELEGRAM_THRESHOLD
PAIR_MOBILE_ACCESS_TOKEN_LIFETIME
PAIR_MOBILE_REFRESH_TOKEN_LIFETIME

The generated .env also contains cryptographic keys. Keep those values private and do not commit real production secrets.

Updates and Migrations

Install or update dependencies from the project root:

composer install
composer update

Composer runs php migrate-cli.php after install and update. Without .env, it exits successfully without connecting to a database. After configuration, it applies the normal migration flow. The migration runner applies Pair vendor migrations first and application migrations immediately after.

Application migrations live in /migrations and should use the YYYYMMDD_description.sql naming convention. Treat migration files as append-only after they have been applied to an environment.

When checking legacy code against the Pair 4 migration helper, run:

composer run upgrade-to-v4 -- --dry-run

The expected dry-run result for the current codebase is:

Changed files: none
Warnings: none

A new project resolves compatible stable dependencies and receives its own composer.lock. Commit that lock with the application. The starter template's obsolete lock is intentionally excluded from distributions.

Development Commands

Run the bundled repository tests in a starter checkout or before completing browser installation:

composer test

These checks inspect installer sources/schema as well as application behavior. Successful browser installation removes the installer, so an installed app no longer contains those source fixtures. Keep application-specific regression tests separate from these starter release checks.

Run the Pair CLI wrapper:

composer run pair -- list

Generate a module:

vendor/bin/pair make:module orders

Generate a CRUD module from a database table:

vendor/bin/pair make:crud order --table=orders --fields=id,customer_id,total_amount

Verify the distributable installation path before publishing the starter:

php tests/install.php

This command uses the sibling Pair checkout (override with PAIR_FRAMEWORK_PATH) and tests real Composer archives/create-project offline, both CLI entrypoints, the initial installer page and the starter unit suite. Supply only disposable PAIR_INSTALL_DB_* credentials for the optional fresh-schema/administrator test. See RELEASING.md for the complete gate and remaining browser checks.

Cron

Schedule cronjob.php every minute on Linux:

* * * * * /var/www/html/cronjob.php

Adjust the path to match the project location.

Self-Test

After installation:

Log in as an administrator.
Open the Self test module.
Confirm that every check is green.
Fix every reported red X before treating the environment as ready.

The checks cover the installed schema and application/session settings. Optional Web Push storage is checked only when its subscription table has been provisioned; server-wide charset/collation defaults are not requirements of this application.

Folder Structure

A generated application has the following structure; .env, temp, vendor and its own composer.lock are created during dependency/application installation.

/classes
/installer
    /sql
        schema.sql
        seed.sql
/migrations
/modules
    /module1
        /assets
        /classes
        controller.php
        model.php
        /layouts
            default.php
/public
    /assets
    /css
    /img
    /js
    /plugins
    .htaccess
    index.php
/temp
/templates
    /template1
        default.php
        login.php
        404.php
/translations
    en-GB.ini
    it-IT.ini
/vendor
/widgets
.env
.env.example
.gitignore
.htaccess
composer.json
composer.lock
cronjob.php
migrate-cli.php
README.md
routes.php

The /installer/sql folder contains the fresh-install baseline split into schema and seed files. The /migrations folder contains append-only upgrade migrations.

Architecture

Pair modules are organized around Controller, Model, state classes and layouts.

Controller

Controllers should contain routing, access checks and request orchestration. Keep business rules, SQL details and presentation markup out of controllers.

In Pair 4-style modules, controllers return explicit responses such as PageResponse and pass typed state objects to layouts.

Model

Models should contain business logic, queries and form handling that is shared by multiple pages of the same module. Keep request routing and presentation markup out of models.

Page State and Layouts

Typed *PageState classes carry the data needed by a page. Layout files render HTML and should stay presentation-focused, with only simple conditions, loops and escaped output.

Do not add new legacy View classes for Pair 4 modules. Prefer typed state classes and explicit responses.

Crafter Module

The crafter module scans database tables that are not yet associated with a module and generates Pair module code for CRUD workflows.

For best results:

use InnoDB tables;
define primary keys clearly;
type every field correctly;
define foreign key relationships where they express real data ownership or lookup behavior;
review generated code before shipping it.

Coding Conventions

Use CamelCase for PHP classes and variables:

$mySpecialClass = new MySpecialClass();

Use uppercase constants separated by underscores:

define('CUSTOMIZED_CONSTANT', TRUE);

Prefer clear multiline conditions:

if (is_null($var)) {
    $var = 0;
} else {
    $var = 1;
}

Use short inline conditions only when readability stays high:

$var = is_null($var) ? 0 : 1;

Use tabs for indentation in .php files, configured at 4 spaces visually.

In inline PHP templates, avoid abbreviated PHP tags and use print consistently with the existing codebase:

<?php print $var ?>

Comment every PHP and JavaScript function. Add comments for non-trivial blocks when the intent is not immediately obvious:

/**
 * Render the setup form with the current installer state.
 */
public function printSetupPage(): void {
    // ...
}

Public Text

When adding user-facing HTML, wiki content, documentation, notifications or error messages, check grammar before finishing the change. For Italian text, verify accents and wording carefully.

Contributing

Pull requests are welcome. Keep changes focused, include tests when behavior changes and update documentation when commands, requirements, API behavior or installation steps change.

License

MIT

viames / pair_boilerplate

Package info

Security

Statistics