README

Markdown

NILS Framework Core (nils-core)

Le composant nils-core est le moteur central, découplé et ultra-performant du framework PHP NILS. Il prend en charge l'intégralité du cycle de vie de la requête HTTP (Request-Response Lifecycle), de l'aiguillage automatique par réflexion à l'injection magique d'arguments.

Ce composant est conçu de manière 100 % agnostique : il n'embarque aucune logique métier ni dépendance forte envers les modules optionnels d'authentification ou de base de données.

🚀 Fonctionnalités Clés

• Routage par Attributs PHP 8 : Déclaration native des routes directement au-dessus des méthodes des contrôleurs (#[Get], #[Post]...).
• Auto-discovery (Découverte Automatique) : Scan intelligent de la cartographie PSR-4 de Composer pour charger vos contrôleurs sans configuration manuelle.
• Compilation d’Arbre (Trie Tree) : Résolution algorithmique des routes en temps constant $O(N)$ (indépendant du nombre total de routes).
• Mise en Cache Atomique : Sérialisation de l'arbre compilé en fichier PHP natif pour annuler le coût de la réflexion en production.
• Pipeline Intergiciel (IoC Middlewares) : Système d'Inversion de Contrôle permettant à des packages externes (nils-auth, nils-roles) de greffer leur sécurité sur des attributs spécifiques.
• Argument Resolver System : Injection automatique et typée des composants requis par vos méthodes (Request, Body, Query, Params), inspiré du standard industriel Symfony.

📦 Installation

Installez le cœur du framework dans votre application via Composer :

composer require nils-framework/nils-core
Note : Ce package requiert l'existence préalable du package de contrats de votre organisation nils-framework/nils-contracts.

🛠️ Utilisation de Base
1. Déclarer un Contrôleur
Pour être détecté automatiquement par le moteur de routage, votre contrôleur doit simplement implémenter l'interface de marquage ControllerInterface :

PHP
<?php
namespace App\Controllers;

use Nils\Contracts\ControllerInterface;
use core\ValueObjects\Query;
use core\Response;
use core\Attributes\Get;

class PlanningController implements ControllerInterface
{
    #[Get('/api/v1/shifts')]
    public function listerShifts(Query $query): void
    {
        $search = $query->get('search', 'default');
        
        Response::json([
            'success' => true,
            'data' => [['id' => 1, 'statut' => 'assigne']]
        ]);
    }
}
2. Point d'Entrée Global (index.php)
PHP
<?php
require_once __DIR__ . '/vendor/autoload.php';

// 1. Définir la racine de l'application (requis pour le cache et l'autoloader)
define('APP_ROOT', __DIR__);

use core\Request;
use core\Routeur;

$requete = new Request();
$routeur = new Routeur();

// 2. Initialiser et compiler les routes (Lit le cache en production)
$routeur->enregistrerDepuisAnnotations();

// 3. Dispatcher la requête vers le contrôleur correspondant
try {
    $routeur->diriger($requete);
} catch (\core\Exceptions\HttpException $e) {
    \core\Response::json(['error' => $e->getMessage()], $e->getCode());
}
🏗️ Architecture du Code (src/)
Plaintext
src/
├── Attributes/     # Attributs natifs de verbes HTTP (Get, Post, Put...)
├── Commandes/      # Commandes systèmes CLI du framework
├── Exceptions/     # Gestionnaire d'exceptions HTTP structurées (404, 400...)
├── Intergiciel/    # Middlewares globaux du système (CORS, Handler d'erreurs)
├── params/         # Système scellé de casting de paramètres d'URL ({id:int})
├── Resolvers/      # Ouvriers d'injection de dépendances (Argument Resolvers)
├── ValueObjects/   # Conteneurs de données nettoyées (Body, Query, Headers)
├── Request.php     # Représentation orientée objet de la requête HTTP
├── Response.php    # Gestionnaire de sorties de flux et de codes HTTP
├── RouteMethode.php# Entité de modélisation d'une route en mémoire
└── Routeur.php     # Compilateur et aiguilleur central de l'écosystème
⚙️ Mode Production vs Développement
Le framework adapte son comportement à la constante de débogage de votre application :

Mode Développement (Debug::DEBUG = true) : Le routeur re-parcourt et re-compile les fichiers à chaque requête. Vos modifications de routes sont instantanées.

Mode Production (Debug::DEBUG = false) : Le routeur charge un fichier PHP sérialisé dans /cache/routes.php. Les performances de routage sont maximales.

Pour vider manuellement le cache lors de vos scripts de déploiement (CI/CD) :

PHP
$routeur->viderCache();
📄 Licence
Ce projet est distribué sous licence MIT. Développé avec passion par Traore.