Download the PHP package astral-php/astral without Composer

Astral MVC — Framework PHP 8.1+ minimaliste

Micro-framework MVC orienté objet, compatible PHP 8.1 → 8.5. Dépendances de production : vlucas/phpdotenv, phpmailer/phpmailer. Minimaliste par design, puissant par convention.

Prérequis : PHP ≥ 8.1 (recommandé : 8.2+ / 8.3+ / 8.4 / 8.5).

Écosystème Composer

Trois familles (détail : astral.md) :

Composants optionnels

Applications

Puis enregistrer le ServiceProvider du package dans config/dependencies.php (voir le README de chaque dépôt).

Roadmap : 1.2.3 = extraction astral-core ; ensuite blog en application, puis extend-orm / payment.
Le core 2.x (enums, readonly, PHP 8.2+) est un chantier séparé.

Organisation : Packagist astral-php · GitHub astral-php.

Structure

Installation

Prérequis : PHP 8.1 ou supérieur (8.1 → 8.5).

Via Composer (recommandé)

Crée un projet à partir de la branche 1.2.x (actuelle : 1.2.3) :

Pour figer exactement la 1.2.3 :

Dépend de astral-php/astral-core ^1.2.

Depuis un clone Git

Vérifiez notamment APP_DEBUG=true en développement (pages d'erreur détaillées + dump()).

Démarrage rapide (Laragon / Apache)

1. Créer le projet (create-project ou clone) dans laragon/www/ (ex. mon-projet)
2. Accéder à http://mon-projet.test ou http://localhost/mon-projet
3. La base SQLite et le dossier storage/logs/ sont créés automatiquement

Démarrer un projet from scratch

Astral MVC est livré avec un module d'exemple complet (Article / Category) qui démontre les ORM léger (hasMany, belongsTo), l'API REST JSON et les migrations.

Si vous souhaitez repartir d'une base vierge pour construire votre propre application, supprimez les fichiers suivants :

1. Modèles et DAOs d'exemple

2. Contrôleurs API d'exemple

3. Migrations d'exemple

4. Nettoyer AppServiceProvider

Dans app/Providers/AppServiceProvider.php, retirez :

5. Nettoyer config/routes.php

Retirez le groupe /api/v1 et ses imports :

Note : Les middlewares CorsMiddleware et BearerTokenMiddleware, ainsi que la classe ApiResponse et AbstractApiController, font partie du framework (astral-php/astral-core) — vous pouvez les réutiliser pour vos propres modules API sans les supprimer.

Variables d'environnement (.env)

Copiez .env.example en .env et adaptez les valeurs. Le fichier .env ne doit jamais être versionné (déjà dans .gitignore).

Les fichiers config/app.php et config/database.php lisent $_ENV avec des valeurs de fallback. En production, les variables peuvent aussi être injectées directement par le serveur (.env non requis).

Architecture du démarrage

public/index.php n'est jamais modifié par l'application. Les providers cœur (FrameworkServiceProvider) ne le sont que pour étendre le framework lui-même.

Fonctionnalités

Debug & erreurs (ErrorHandler, dump, dd)

Zéro dépendance. Activé automatiquement au démarrage.

Avec APP_DEBUG=true, la page 500 affiche classe, message, fichier et stack trace. Avec APP_DEBUG=false, message générique uniquement (aucun détail technique exposé).

Session & Messages flash

Validation

Règles disponibles :

Protection CSRF

Le token est partagé automatiquement dans toutes les vues via $csrf.

La vérification se fait via CsrfMiddleware à appliquer aux routes concernées :

Partials (vues réutilisables)

Le moteur de vues expose renderPartial() et un alias court partial() pour inclure des sous-vues (sans layout). La variable $viewEngine est partagée dans toutes les vues et le layout (nom dédié pour éviter tout conflit avec une donnée view), ce qui permet d’inclure des partials depuis n’importe quel template.

Convention : placer les partials dans views/partials/ (ex. partials/flash.php, partials/field-error.php).

Depuis une vue ou le layout :

Partials fournis (Tailwind CSS) :

Pagination — 3 modes ($mode optionnel, défaut numbers) : simple (Précédent / Suivant), numbers (toutes les pages), elastic (fenêtre glissante 1 … 5 6 7 … 42 pour gros volumes).

En contrôleur, $this->view->renderPartial('nom/vue', $data) retourne le HTML sans layout (utile pour des réponses AJAX ou fragments). Dans les vues, utilisez toujours $viewEngine->partial(...) pour inclure un partial.

Middleware

Créer un middleware dans app/Middleware/ :

Enregistrer dans config/dependencies.php :

Appliquer dans config/routes.php :

Routes — verbes HTTP complets & groupes

Logger

Les erreurs 500 sont loguées automatiquement dans storage/logs/YYYY-MM-DD.log.

Format d'une ligne de log :

Pagination

Objet Response (actions testables)

Les méthodes render(), redirect() et json() retournent désormais des objets Response. L'envoi HTTP n'est déclenché qu'à la fin par le Router, ce qui permet de tester les contrôleurs sans sortie réelle.

Cache fichier

Console CLI

Ajouter une commande applicative :

Service Providers

config/dependencies.php déclare un tableau de providers — plus de Closure plate. Application instancie chaque provider et appelle register() dans l'ordre du tableau.

Ajouter un groupe de services (ex: envoi d'e-mails) :

Les providers du framework (astral-core → Core\Providers\) ne sont jamais modifiés. Vos ajouts se font exclusivement dans app/Providers/.

JSON / API REST

Basculer vers MySQL

Éditer .env (recommandé) :

Relations entre entités — ORM léger

Philosophie Astral : pas de lazy-loading, pas de magie. Les relations sont des appels explicites dans les DAOs.

AbstractDao expose deux helpers protected que les DAOs concrets peuvent appeler :

hasMany() — relation 1→N

belongsTo() — relation N→1

Chargement combiné

Les DAOs exposent des méthodes de "chargement avec relation" pour éviter de multiples appels :

Exemple complet : module Article

Règles et conventions

Migrations fournies

Authentification & Rôles

Le premier compte créé via /register devient automatiquement admin.
Ensuite, l’admin paramètre l’inscription des utilisateurs suivants dans le .env :

Rôles disponibles

Service Auth

Disponible dans tous les contrôleurs via le conteneur, et dans toutes les vues via la variable $auth partagée automatiquement.

Middleware Auth

Trois middleware intégrés, utilisables dans config/routes.php :

Gestion des rôles dans UserDao

Interface d'administration des rôles

L'application embarque une interface dédiée accessible aux administrateurs :

Contrôleur : App\Controllers\Admin\UserController

Règles de sécurité intégrées :

• Un admin ne peut pas modifier son propre rôle.
• Le dernier administrateur ne peut pas être rétrogradé (protection anti-lockout).
• Seuls les rôles définis dans Role::all() sont acceptés.

Événement dispatché après chaque changement :

Listener fourni : App\Listeners\LogRoleChange — journalise l'action via Logger.

Modèle User — helpers de rôle

Routes d'authentification (incluses par défaut)

Routes disponibles (application de démonstration)

Tests

Couverture actuelle :

Events & Listeners

Le système d'événements découple les effets de bord des contrôleurs. EventDispatcher est synchrone et zéro dépendance.

Créer un événement

Créer un listener

Enregistrer dans AppServiceProvider

Dispatcher depuis un contrôleur

Subscriber (regroupement de listeners)

Événements fournis

Migrations de base de données

Le système de migrations versionne le schéma de base de données via des fichiers PHP dans database/migrations/. Chaque migration est un batch identifié en base dans la table migrations (créée automatiquement, SQLite et MySQL compatibles).

Convention de nommage

Commandes

Anatomie d'un fichier de migration

Résultat de migrate:status

API REST JSON

Astral embarque une couche API complète, activée via des routes /api/v1/* protégées par CORS et Bearer Token.

Format de réponse uniforme

Configuration

Dans .env :

Appels depuis un client

Routes disponibles

Créer un contrôleur API

Middlewares

Scaffolding — Générateur de code

Le générateur crée automatiquement le squelette d'un module complet (Model, DAO, Controller, Migration).

Mode interactif (recommandé)

Le prompt guide étape par étape :

Mode direct

Ce que génère chaque commande

Après la génération — étapes manuelles

public/index.php et Core\Application (package astral-core) ne sont jamais modifiés.

Fonctionnalités PHP 8.1+ utilisées

• declare(strict_types=1) partout
• Constructor Property Promotion + propriétés readonly (ex. ErrorHandler)
• Named Arguments (findAll(orderBy: 'name'))
• match expression
• Union types (string|array)
• First-class callables ($this->handleError(...))
• str_contains(), str_starts_with()
• fn() arrow functions
• mixed type hint
• never return type (dd())