Download the PHP package nabysyphpapi/xnabysygs without Composer

NAbySyGS - Framework PHP avec ORM Intégré

NAbySyGS est un framework PHP moderne conçu par PAM & MCP pour faciliter la création rapide d'API REST pour vos applications. Il intègre un ORM personnalisé avec création automatique de tables et champs, un système d'authentification JWT, une architecture modulaire, et un double système de routage (Action classique + URL Laravel-style).

✨ Fonctionnalités

• 🚀 ORM Automatique — Création automatique des tables et champs MySQL/MariaDB
• 🔗 Jointures ORM Fluentes — API de jointure chainable entre entités, sans écrire de SQL
• 🔐 Authentification JWT — Système de tokens sécurisés intégré
• 📦 Architecture Modulaire — Organisation en modules avec auto-chargement
• 🎯 Type-Safe — Détection automatique des types de données (INT, VARCHAR, DATE…)
• 🔄 Gestion d'Événements — Pattern Observer pour réagir aux changements
• 🌐 Double Routage — Routage par Action classique et routage URL Laravel-style, simultanément
• 🛡️ Middlewares — Appliqués automatiquement, personnalisables par le développeur
• 📋 Documentation des Routes Intégrée — Endpoint /api/describe avec rendu web interactif, export JSON/PDF et import
• 🛠️ Modules Métier — Gestion de boutiques, stocks, factures, clients…
• 🌐 CORS Ready — Gestion automatique des requêtes cross-origin
• 📝 Logs Intégrés — Journalisation système et débogage
• 🎛️ Setup HTML Interactif — Configuration initiale via interface web, ouverte automatiquement au premier lancement

📋 Prérequis

• PHP >= 8.1.0
• MySQL ou MariaDB
• Extensions PHP : mysqli, mbstring, json
• Composer

📦 Installation

Via Composer

Via la CLI NAbySyGS (koro / nsy)

Voir la documentation de la CLI pour le détail des commandes disponibles.

🎛️ Setup Initial Automatique

Lors de la première installation (via composer require ou via n'importe quelle commande koro), NAbySyGS ouvre automatiquement setup.html dans votre navigateur par défaut.

Cette interface web vous permet de configurer :

• La connexion à la base de données
• L'URL du serveur
• Le nom de l'application et les informations client

Une fois le formulaire validé, appinfos.php est généré automatiquement à la racine de votre projet. Le setup ne s'ouvrira plus automatiquement par la suite.

⚠️ Toute commande koro (sauf koro version) déclenche cette vérification et ouvre le setup si le projet n'est pas encore configuré.

Structure Générée

🚀 Démarrage Rapide

1. Configuration Initiale

Créez un fichier index.php à la racine :

En pratique, appinfos.php généré par le setup contient déjà cet appel N::Init() configuré pour votre environnement.

2. Déclarer vos Modules — db_structure.php

Tous les modules (catégories, ORM, routes URL) sont déclarés dans db_structure.php, inclus automatiquement dans appinfos.php. Ce fichier peut être généré et enrichi via la CLI ou manuellement.

Vous pouvez également avoir plusieurs fichiers de structure en les déclarant via la CLI avec --struct :

3. Créer Votre Premier Module

Cela génère automatiquement :

• gs/client/client_action.php — Endpoints API
• gs/client/xClient/xClient.class.php — Classe ORM

4. Utiliser l'ORM

🌐 Double Système de Routage

NAbySyGS supporte deux modes de routage simultanément. Vous pouvez utiliser l'un, l'autre, ou les deux dans le même projet.

Mode 1 — Routage par Action (classique)

Le routage historique de NAbySyGS. Chaque requête transmet un paramètre action ou Action.

Mode 2 — Routage URL Laravel-style

Routage expressif basé sur l'URL, avec paramètres dynamiques, contraintes et middlewares. Déclaré via GenerateUrlRouteController().

Déclaration d'un contrôleur de route

Définir des routes dans le contrôleur

Récupérer les paramètres d'URL dans l'action

Middlewares

Les middlewares sont appliqués automatiquement par défaut (authentification JWT, CORS, etc.). Le développeur peut les personnaliser :

Coexistence des deux modes

Les deux modes fonctionnent simultanément dans le même projet. Le framework détecte automatiquement le type de requête et dispatch vers le bon handler.

📋 Documentation des Routes — /api/describe

NAbySyGS génère automatiquement une documentation interactive de vos routes URL accessible via un endpoint dédié, sans aucune configuration supplémentaire.

Accès

L'endpoint est disponible dès le premier lancement, même si db_structure.php est vide. Les routes internes du framework y figurent toujours à titre de référence.

La documentation est pour l'instant limitée aux routes déclarées via le routage URL (GenerateUrlRouteController).

Authentification

L'accès à /api/describe (JSON ou HTML) est protégé par les credentials de la table utilisateur créée automatiquement lors du setup initial. Des accès supplémentaires peuvent être ajoutés directement dans cette table.

Version Web Interactive (?HTML=1)

La page web propose :

• Vue structurée de toutes les routes enregistrées (méthode HTTP, chemin, action, middlewares)
• Ajout de titres et commentaires par route, pour documenter le rôle de chaque endpoint
• Export JSON — pour sauvegarder la description annotée sur votre support de stockage
• Export PDF — pour produire une documentation imprimable, générée côté navigateur
• Import JSON — pour recharger une description précédemment exportée et retrouver vos annotations

Les annotations (titres, commentaires) ne sont pas stockées côté serveur. C'est l'utilisateur qui gère ses exports/imports, garantissant une totale portabilité sans aucune dépendance serveur.

Exemple — Réponse JSON

Avantage par rapport aux autres solutions

Doctrine et Eloquent ne fournissent aucune documentation d'API intégrée — il faut intégrer des outils tiers comme Swagger/OpenAPI, configurer des annotations et maintenir un fichier YAML séparé. Avec NAbySyGS, la documentation est vivante, toujours à jour et disponible immédiatement, avec une interface web prête à l'emploi et un système d'export/import sans infrastructure supplémentaire.

📖 ORM — Opérations CRUD

Créer

Lire

Mettre à Jour

Supprimer

Conversions de Données

Clonage d'Enregistrements

Jointures entre Entités

NAbySyGS propose une API de jointure fluente et chainable directement sur les classes ORM, sans écrire une seule ligne de SQL. Là où Doctrine exige des annotations de relation et Eloquent impose de déclarer belongsTo / hasMany dans chaque Model, NAbySyGS permet de joindre n'importe quelles deux entités à la volée, même créées dynamiquement.

Signature de JoinTable() :

La méthode retourne $this, permettant de chaîner plusieurs jointures successives :

Comparaison jointures avec autres ORM

Aucune relation ne doit être déclarée à l'avance : la jointure s'exprime directement là où vous en avez besoin, ce qui est particulièrement puissant sur des tables créées dynamiquement.

🔐 Authentification JWT

Connexion

Protection des Routes

Configuration Session

🎭 Système d'Événements Unique

NAbySyGS intègre un système d'événements innovant qui se démarque des autres ORM PHP par sa simplicité et sa puissance.

Comparaison des Événements avec Autres ORM

Avantages Clés du Système d'Événements NAbySyGS

1. Événements Automatiques sur TOUTES les Tables

2. Observer Centralisé Multi-Tables

Autres ORM : Nécessitent un Observer/Subscriber par entité.

3. Support des Tables Créées Dynamiquement

Aucun autre ORM ne permet cela ! Doctrine et Eloquent nécessitent de créer Entity/Model, configurer les événements, puis redéployer.

4. Observateur Global "Catch-All"

Impossible avec cette simplicité sur Doctrine ou Eloquent !

5. Événements avec Contexte Complet et Modifiable

Utilisations pratiques : validation automatique, enrichissement de données, normalisation, calculs automatiques, audit trail complet.

Créer un Observateur

1. Créer la Classe Observateur

Créez un fichier dans gs/votre_module/xObservVotreModule/xObservVotreModule.class.php :

2. Activer l'Observateur

L'observateur est chargé automatiquement au démarrage de NAbySyGS. Assurez-vous que votre classe :

• Hérite de xObservGen
• Est dans un dossier xObserv* sous votre module
• Implémente la méthode RaiseEvent()

Exemple Complet : Système de Notifications pour les Commandes

Événements Disponibles

Le framework déclenche automatiquement :

• {CLASS}_ADD — Après création d'un enregistrement
• {CLASS}_EDIT — Après modification d'un enregistrement
• {CLASS}_DEL — Après suppression d'un enregistrement

Où {CLASS} est le nom de votre table (ex : xProduit_ADD, xClient_EDIT).

Cas d'Usage Pratiques

1. Synchronisation Automatique avec API Externe

2. Alertes Automatiques de Stock Faible

3. Mise à Jour Automatique de Statistiques

Déclencher Manuellement un Événement

Désactiver un Observateur

Debug des Événements

Bonnes Pratiques avec les Événements

1. Nommage cohérent : Utilisez {Classe}_{Action} pour les événements
2. Logging : Toujours logger les actions importantes
3. Performances : Évitez les traitements lourds dans les observateurs
4. Async : Pour les traitements longs, utilisez des queues (Beanstalkd, RabbitMQ)
5. Test : Créez des observateurs de test pour vérifier le déclenchement
6. Documentation : Documentez les événements disponibles dans votre module

🛠️ Modules Intégrés

Module Boutique

Module Stock

Module Facture

📚 Exemples Complets

API Gestion de Produits

Appel API (curl)

🔧 Configuration Avancée

Mode Debug

Ignorer Certaines Requêtes dans les Logs

Personnalisation du Dossier Racine

🔄 Mise à Jour de la Structure via db update

La CLI NAbySyGS fournit une commande db update (alias koro db u) qui appelle l'API du projet pour synchroniser la structure de base de données avec db_structure.php.

Cette commande est appelée automatiquement après chaque koro create. Elle peut aussi être invoquée manuellement à tout moment pour forcer la synchronisation.

L'URL de l'API est lue automatiquement depuis __SERVER_URL__ dans appinfos.php. Vous pouvez la surcharger avec --url.

⚖️ Comparaison avec d'autres ORM PHP

✅ Avantages de NAbySyGS

1. Simplicité et Rapidité de Développement

2. Auto-création de Tables et Champs

• 🚀 Aucune migration nécessaire — Les tables et champs se créent automatiquement
• 🎯 Zero configuration — Pas besoin de définir des schémas
• ⚡ Prototypage ultra-rapide — Concentrez-vous sur la logique métier

3. Jointures à la Volée

4. API REST + Documentation Intégrées

• 🎁 Structure d'API fournie "out of the box"
• 🔐 Authentification JWT intégrée
• 🌐 CORS géré automatiquement
• 📋 Documentation des routes via /api/describe, avec export JSON/PDF
• 📝 Journalisation système incluse

5. Pas de Dépendances Complexes

• ✅ Fonctionne avec PHP 8.1+ et MySQLi natif
• ✅ Pas besoin de Symfony, Laravel ou autre framework
• ✅ Package autonome et léger (~2MB)

❌ Limitations

📊 Tableau Récapitulatif

🎯 Quand Utiliser NAbySyGS ?

1. Prototypes et MVPs Rapides — Lancer une API en quelques heures, tester des idées rapidement
2. Petites et Moyennes Applications — < 200 tables, < 500 000 enregistrements/table, équipe de 1-50 développeurs
3. Applications Métier Internes — ERP légers, stocks, factures, clients, outils administratifs
4. Projets Sans Infrastructure DevOps — Hébergement mutualisé, pas de CLI disponible, environnement simple
5. Développeurs Débutants en ORM — Courbe d'apprentissage douce, résultats immédiats

🔄 Migration vers NAbySyGS

Depuis Eloquent (Laravel)

Depuis Doctrine

📝 Structure de Réponse API

Succès

Erreur

🎯 Bonnes Pratiques

1. Toujours utiliser ValideUser() pour protéger vos endpoints sensibles
2. Nommer vos actions en MAJUSCULES avec préfixe module : PRODUIT_CREATE
3. Utiliser xNotification pour les réponses réussies, xErreur pour les erreurs
4. Activer le debug uniquement en développement
5. Versionner votre fichier appinfos.php pour la configuration personnalisée
6. Créer des observateurs pour automatiser les tâches répétitives
7. Logger les événements importants pour faciliter le débogage
8. Utiliser koro db update après toute modification manuelle de db_structure.php
9. Consulter /api/describe pour vérifier que toutes vos routes URL sont bien enregistrées

🤝 Contribution

Les contributions sont les bienvenues ! N'hésitez pas à :

1. Proposer des suggestions via les Issues
2. Créer une branche (git checkout -b feature/amelioration)
3. Committer vos changements (git commit -m 'Ajout fonctionnalité')
4. Pusher sur la branche (git push origin feature/amelioration)
5. Ouvrir une Pull Request

📄 Licence

MIT License — voir le fichier LICENSE pour plus de détails.

👨‍💻 Auteur

Paul Isidore A. NIAMIE

• Email : [email protected]
• Website : https://groupe-pam.net

🙏 Remerciements

Développé par Paul & Aïcha Machinerie (PAM) et Micro Computer Programme (MCP).

⭐ Si ce projet vous est utile, n'hésitez pas à lui donner une étoile sur GitHub !