README

Adige is a small PHP framework with a focused core around:

HTTP and console request handling
explicit routing with controller autodiscovery
a lightweight ActiveRecord ORM
file-based views
migrations and model validation

About

Adige is the second-largest river in Italy, it was and still is one of the most important rivers in the country since the Middle Ages. The river gives its name to the Trentino-Alto Adige region. The name of the project is just a tribute to the memories of a trip that one of the collaborators (@mathmpr) took to this region of Italy.

Release target

The current release target is 1.0.0-alpha.

At this stage, Adige can be described as a stabilized microframework for the current line:

small and focused
tested around its HTTP core, console flow, ORM, migrations and validation layer
suitable for small, controlled and serious projects

Important scope note:

Adige is not positioned as a general replacement for large, battle-tested frameworks
the current scope is best suited for small applications, internal tools, simple APIs and controlled production environments
the package baseline is now aligned for the 1.0.0-alpha distribution model

Public API and compatibility notes for this target are documented in:

PUBLIC_API.md

Git rules

Let's try to use git in a professional way, for this we will establish some rules.

Try to never commit and push directly to the branch master or develop.
Branch models must follow a standard:
- adjust - for general adjustments. EX: adjust/<component-name>/fix-number-of-params-for-bind-value
- hotfix - When a bug is in master, we can make a branch directly from master and then make a pull request directly to master, just to fix some "urgent" bug. EX: hotfix/<component-name>/fix-regex-for-identify-routes
- feature - when we upload the feature for the first time. EX: feature/<component-name>
- enhancement - when we are going to make a code improvement or refactoring. EX: enhancement/<component-name>/new-router-system
When committing, always type a message about what is inside it in a reduced form.
When making a pull request, we always point our branch to develop (and unless it is a hotfix), and on a certain day of the week or month we move everything from develop to master.
Pull requests must have a description of what was done in the commits contained in it.
The pull request cannot be merged into the target branch until there is at least one approve on the pull request and all pull request conversations are resolved.

Goals

Study OO concepts.
- What is an object and what is a class.
- Understanding the public, private and protected access levels.
- Differences between static and non-static methods. Understand the properties too.
- How the concept of inheritance works.
- How the interface concept works.
- How the concept for abstract classes works.
Study the concepts of DDD.
Create a component for router to allow calls to the HTTP: GET methods; POST; OPTIONS; PUT; DELETE.
- Study the HTTP method.
- Understand how a router works. Study references laravel, yii2 and slim.
- Implement something similar to the basics of slim allowing groups of routes.
- Allow auto discover route based on URI.
- Implement middleware.
Create base component to perform basic and dynamic operations on the MySQL database.
- The input must be the query and the array with the data for any operation.
- Study how a query builder ORM works
- Implement a query builder.

Installation

Install the package in a consumer project with Composer:

composer require trentino-alto/adige

The package exposes its console entrypoint through Composer bin proxies:

vendor/bin/adige

This is the main command entrypoint of the framework.

Package consumption

Adige is now distributed as a Composer library.

The important runtime paths are:

package root: where the framework code itself lives
vendor dir: the consumer project's Composer vendor/
basePath: the consumer project root

The console launcher already passes the project root automatically:

Adige::run(null, getcwd());

If you start the framework manually, pass the consumer base path explicitly:

use Adige\core\Adige;

Adige::run(null, __DIR__);

Minimal web consumer

Example project structure:

my-app/
├── bootstrap.php
├── public/
│   └── index.php
├── controllers/
│   └── IndexController.php
└── composer.json

Example composer.json for the consumer project:

{
  "require": {
    "trentino-alto/adige": "1.0.0-alpha"
  },
  "autoload": {
    "psr-4": {
      "App\\": ""
    }
  }
}

Example bootstrap.php:

<?php

use Adige\core\Adige;
use Adige\core\App;
use Adige\core\BaseView;

return [
    Adige::VIEW_HANDLER => [
        'class' => BaseView::class,
        '__construct()' => [
            __DIR__ . '/views',
        ],
    ],
    Adige::ROUTER_HANDLER => [
        'class' => Adige\core\routing\Router::class,
        '__construct()' => [
            '@request',
            '@response',
            true,
            'index',
        ],
        'controllerNamespaces' => [
            'App\\controllers',
        ],
    ],
];

Example public/index.php:

<?php

require __DIR__ . '/../vendor/autoload.php';

use Adige\core\Adige;

Adige::run(null, dirname(__DIR__));

Example controllers/IndexController.php:

<?php

namespace App\controllers;

use Adige\core\controller\BaseController;

class IndexController extends BaseController
{
    public function actionIndex(): string
    {
        return 'Hello from Adige';
    }
}

Minimal console consumer

Once the package is installed, console commands run from the project root:

vendor/bin/adige
vendor/bin/adige migrate/create --name=create-users-table
vendor/bin/adige migrate/up

The recommended command flow is:

use vendor/bin/adige as the primary framework command
use it to start the built-in PHP server
use it to create and run migrations
use it to generate the optional project-root launcher

Examples:

vendor/bin/adige server/start
vendor/bin/adige migrate/create --name=create-users-table
vendor/bin/adige migrate/up
vendor/bin/adige install/index

If you want a project-root launcher, generate one after installation:

vendor/bin/adige install/index

That command creates ./adige in the consumer project root and the generated file resolves:

./vendor/autoload.php
Adige::run(null, __DIR__)

The generated ./adige file is an optional shortcut. It does not replace vendor/bin/adige as the official package entrypoint.

Configuration notes

The current package defaults are intentionally small:

console controllers default to Adige\console\controllers
web controller autodiscovery should be configured explicitly through controllerNamespaces
bootstrap files are discovered from the consumer basePath
migrations default to <basePath>/migrations
.env is loaded from the consumer basePath first

Tests

The core test suite is based on PHPUnit.

Run the full unit suite:

vendor/bin/phpunit --do-not-cache-result tests/Unit

Run a single test file:

vendor/bin/phpunit --do-not-cache-result tests/Unit/Routing/RouterFindRouteTest.php

Current tests focus on framework contracts such as:

router matching and autodiscovery precedence
route parameter resolution
middleware short-circuit and failure handling
response normalization
HTTP request/response behavior without a real web server
migrations, validators and package/runtime path behavior

trentino-alto / adige

Maintainers

Package info

Statistics

Security