---

🚀 Introduction

StructureOne est une architecture PHP moderne et universelle, conçue pour être compatible avec n’importe quel serveur, que ce soit Apache ou Nginx.
Grâce à sa nouvelle conception, le framework détecte automatiquement l’environnement serveur et s’adapte sans configuration manuelle. Cette compatibilité universelle a été développée pour garantir une installation fluide, rapide et sécurisée, quel que soit l’hébergeur ou l’environnement.

---

✨ Fonctionnalités Clés

• 🔧 Versioning d'API : support natif pour /api/v1/, /api/v2/
• 🧠 Compatibilité multi-serveurs : Apache & Nginx
• 🛡️ Sécurité avancée : protection automatique des fichiers sensibles
• 🧩 Support Composer : StructureOne a été conçue pour être compatible avec Composer
• 🧰 Gestion des erreurs et du debug intégrée
• ♻️ Rétrocompatibilité garantie avec les versions précédentes
• 🎨 Interface HTML stylée : Pages d'erreur et d'accueil professionnelles (comme Laravel/Symfony)
• ⚡ Variables automatiques : Partage automatique entre fichiers, sans besoin de global
• 📝 Logging avancé : Traçabilité complète avec timestamps

StructureOne vise à évoluer continuellement. Pour les utilisateurs en production, chaque mise à jour restera compatible avec vos versions précédentes, sauf correctifs de sécurité critiques.

---

📂 Structure du projet

LLe projet est composer de plusieurs fichiers :

my-project/
├── core/
│   ├── routes/         # API route handlers
│   ├── database/       # Database migrations and seeds
│   ├── logs/           # Application logs
│   ├── versions/       # API route avec versions
│   ├── cache/          # Cache files
│   └── uploads/        # Uploaded files
├── vendor              # Les dependances au cas ou vous utilisez composer
├── .env                # Environment variables
├── .htaccess           # La configuration serveur Apache
├── index.php           # Le routeur
├── config.php          # Les configuartions manuelle
├── laoder.php          # Toute les fonctions globaux

Fichiers :

• index.php
  Gère dynamiquement les routes.
  Ajoutez simplement un dossier dans /core/routes/NOM_DU_DOSSIER et le système appellera automatiquement son code pour gérer la route.
  ➝ Aucun besoin de modifier ce fichier. ➝ Peut desormais prendre en charge des API par version depuis le dossier /core/versions/v1/NOM_DU_DOSSIER , la meme logique est garder.

• config.php
  Contient toutes les configurations globales et importantes.
  Utilisez des constantes plutôt que des variables afin d’éviter des conflits.

• loader.php
  Contient toutes les fonctions globales.
  ➝ Ajoutez ici vos nouvelles fonctions réutilisables (connexion BDD, helpers, etc.).
  ⚠️ Ne supprimez pas les fonctions par défaut sauf en cas de nécessité.

• install.py et install.js
  Scripts d’installation du projet (au choix Python ou Node.js).
  Une fois l’installation terminée, vous pouvez supprimer ces fichiers.

• .htaccess , .env et nginx.conf.example

  • nginx.conf.example → Crucial car il est le fichier d'example pour la configuration Nginx
  • .htaccess → Crucial pour la réécriture d’URL et la redirection des requêtes vers le routeur.
  • .env → Généré automatiquement lors de l’installation (contient les configurations sensibles).

Par defaut vous n'eetes pas obliger d'ajouter la configuration Nginx sauf si cela vous est utile.

Pour eviter d'exposer votre fichier d'environnement , veuillez ouvrir le fichier du routeur (index.php) puis allez a la ligne 107 , mettez le chemin vers votre nouvelle emplacement du fichier .env

Dossier /core/ :

• /routes/ → Contient les dossiers de chaque route API.
• /versions → Contient les dossiers par versions des routes , /versions/NOM_DE_LA_VERSIO/NOM_DE_LA_ROUTE (ex : /versions/v1/users_info)
• /logs/ → Stockage des logs (erreurs, succès, monitoring).
• /database/ → Contient les fichiers .sql ou .bdd.
• /uploads/ → Contient les fichiers uploadés (organisez par sous-dossiers : /uploads/file/, /uploads/images/ …).
• /cache/ → Contient les caches du système.

Vous etes libre de personnaliser vos dossiers , sauf les dossiers ci-haut , créez autant des dossiers que vous voulez soyez libre , nous vous imposons rien , au cas ou vous voulez que vos dossiers deviennet des parametres du systemes alors ouvrez le fichier config.php ajoutez son chemin comme constante

define('BASE_TEMPLATES','/core/templates');

---

⚙️ Installation

Lorsque vous clonez le projet depuis github , vous ne serez pas obliger d'utiliser les installateurs car ceux-ci sont rarement mis en jour , nous vous recommandons de passer directement a l'etape suivante.

Via Node.js

Assurez-vous d’avoir installé Node.js et ses dépendances :

const fs = require('fs');
const path = require('path');
const readline = require('readline');

Puis lancez :

node install.js

Via Python 3

Assurez-vous d’avoir Python 3 et ces dépendances :

import os
import re
import datetime
import sys

Puis lancez :

python3 install.py

---

🌐 Gestion des routes

Les routes API sont automatiquement gérées.
Exemple : route /api/test

Créez simplement un dossier test dans /core/routes/ ou core/versions/VOTRE_VERSION/ avec vos fichiers PHP.

✅ Chargement automatique de tous les fichiers : Le routeur charge automatiquement TOUS les fichiers .php présents dans le dossier de la route :

• functions.php est chargé en premier (si présent)
• Les autres fichiers sont chargés par ordre alphabétique
• index.php est chargé en dernier

⚠️ Inutile d'inclure loader.php et config.php, le routeur s'en charge déjà.

StructureOne gère automatiquement le chargement de tous vos fichiers, plus besoin de les inclure manuellement !

🚫 Variables réservées - IMPORTANT

Pour éviter les conflits, n'utilisez JAMAIS les variables suivantes dans vos routes :

• Toutes les variables préfixées par $_so_ (réservées au système)
• $GLOBALS['JWT_HTTP_TOKEN'] (à lire uniquement, ne pas écraser)

✅ Bonnes pratiques de nommage :

// ✅ BON - Noms descriptifs et contextualisés
$userData = $_POST['data'];
$dbResult = db_find(...);
$apiResponseData = [...];

// ❌ MAUVAIS - Noms trop génériques ou réservés
$data = $_POST['data'];
$_so_routeName = "test"; // INTERDIT !

📚 Consultez /core/routes/exemple_bonnes_pratiques/ pour un exemple complet.

Exemple de réponse /api/test :

{
    "status": "success",
    "message": "L'api fonctionne",
    "role": "cette api n'est qu'un exemple qui va renvoyer les cordonnees du fichier d'env",
    "env": {
        "DB_HOST": "localhost"
    }
}

---

🐛 Gestion des Erreurs

Lorsque vous creez votre route , n'oubliez pas d'ajouter la fonction getError() si vous utilisez une exception , et cela va activer ou desactiver automatiquement les erreurs si vous etes en production. Sans DEBUG_MODE :

try {
    // Votre code ici 
} catch (Exception $e) {
   // A L'execption 
    echo getError($e);
}

Si certains de nos fonctions de base ne tiennent pas a vos besoin comme par exemple la fonction getError alors , vous pouvez ajouter cette suite de code :

try{
   // Votre code ici
} catch (Exception $e) {
    // Gestion des erreurs inattendues
    error_log("ERROR TITLE " . $e->getMessage());
    
    $debug_info = null;
    if (env('DEBUG_MODE') === 'true') {
        $debug_info = [
            'error' => $e->getMessage(),
            'file' => $e->getFile(),
            'line' => $e->getLine()
        ];
    }
    
    echo api_response(500, null, $debug_info);
}

Les deux codes ci-haut font carrement la meme chose.

⚙️ Configuration

// .env
DEBUG_MODE=true
API_TOKEN_SECRET=votre_cle_super_secrete
API_TOKEN_EXP=3600

---

🛠️ Fonctions globales

Les fonctions globals , sont des fonctions déjà mis en place pour vous aidez à aller plus vite , vous n'etes pas conditionner de les utiliser , ses fonctions repondent a des besoins varier.

Renvoyer une reponse a la sortie de votre API

Pour eviter a chaque fois d'ecrire un bloc de code repetif :

// Exemple de tableau 
$VOTRE_TABLEAU = [
  "status" => "success",
  "message" => "Utilisateur inscrit avec success",
  "data" => ["uid" => 1]
];
// Renvoyer un code 
http_respone_code(200);
// Renvoyer une reponse
echo json_encode($VOTRE_TABLEAU,true);
exit;

Ce travail pourrait etre très fatiguant , surtout lorsque vous avez beaucoup des routes a gérez , alors pour ce faire nous avons mis en place une fonction bien speciale , pour resoudre ce probleme.

api_response($status, $message = null, $data = null)

Cette fonction simplifie la sortit des reponses JSON , gère les caractères pour eviter les erreurs de caracters Unicode et bien plus. Cette fonction prends en entré 3 valeurs :

• $status : Il s'agit du status de la reponse , precedement mis dans http_response_code(200) , ici ce parametre prends en charge tout type de code d'erreur.
• $message : ce parametre est optionnel , c'est juste le message qui sortira a la reponse , precedement Utilisateur inscrit avec success , ici au cas ou vous mettez rien , il va mettre lui meme la reponse correspondant a l'erreur , par exemple 404 correspond a Not Found
• $data : Ceci est aussi optionnel , prends en entré un string ou un tableau , precedement "data" => ["uid" => 1].

Exemple D'utilisation :

echo api_response(200, "Requête réussie", [
    "token" => "example-token"
]);

Recuperer un element existant dans le fichier d'environnement

Nous avons mis en place une fonction qui permet de recuperer directement un element venant du fichier d'environnement :

$db_host = env('DB_HOST');

Generer un jeton JWT

Il existe une fonction pour generer un jeton JWT , fonctionnel , cette fonction prends en entré un string ou un tableau.

<?php
/** Premier cas **/
// Génération du token
$userData = [
    'id' => 123,
    'name' => 'John Doe',
    'email' => 'john@example.com'
];
// Va generer un token en fonction du tableau
$token = jwt_generate($userData);

/** Deuxieme cas **/
$id = 1; // Par exemple on suppose que c'est l'id 1 qu'on veux renvoyer en token 
$myToken = jwt_generate($id);
?>

Il est important d'utiliser la meme methode pour decoder votre jeton JWT

Verifier et Valider un jeton JWT

• Valide un token JWT existant.
• Vérifie rigoureusement l’expiration et la validité du token.
• Utilise également API_TOKEN_SECRET et API_TOKEN_EXP.

Pour verifier si un token est valide , vous n'aurez qu'a entrer le token :

<?php

// exemple de token 
$token = "eyJ1aWQiOiI4IiwiZXhwIjoxNzU5NDQ2NDY0fQ.NTY2NDc4