Download the PHP package mawena/maravel without Composer

Maravel

Maravel est une librairie Laravel avancée qui accélère le développement d'API REST en fournissant un contrôleur générique avec CRUD complet, un système de permissions sophistiqué, des modèles enrichis avec formatage automatique, et des commandes Artisan pour générer du code prêt à l'emploi.

Table des matières

• Fonctionnalités principales
• Prérequis
• Installation
• Configuration
• Démarrage rapide
• Utilisation avancée
  • APIController
  • ModelBase
  • BasePolicy
  • Traits disponibles
  • Commandes Artisan
• Filtres avancés
• Système de permissions
• Hooks et callbacks
• Exemples complets
• Tests
• Changelog
• Contribution
• License

Fonctionnalités principales

🚀 APIController générique

• CRUD complet : Toutes les opérations (index, show, store, update, destroy) prêtes à l'emploi
• Création multiple : Méthode store_multiple() pour créer plusieurs enregistrements en une seule requête
• Filtrage automatique : Filtres basiques, min/max, IN/NOT IN, relations, recherche textuelle, JSON
• Reducers personnalisés : Transformations post-requête via méthodes reducer dans les modèles
• Upload de gros fichiers : Méthodes uploadChunk() et mergeChunks() pour fichiers volumineux
• Pagination intelligente : Pagination automatique ou désactivable avec paramètres configurables
• Tri dynamique : Tri ascendant/descendant sur n'importe quelle colonne
• Gestion des relations : Chargement automatique des relations Eloquent via paramètres d'URL

🔐 Système de permissions avancé

• BasePolicy : Classe de base pour créer des policies sophistiquées
• Permissions par profil : Support des profils utilisateur (admin, user, etc.)
• Règles d'abilités : Système de règles avec sujets et actions (CASL-like)
• PermissionCheckerTrait : Méthodes helper pour vérifier les permissions facilement
• Admin bypass : Les administrateurs ont accès complet automatiquement

📦 ModelBase enrichi

• Formatage automatique des dates : Conversion automatique avec localisation française
• Formatage des montants : Affichage des valeurs monétaires avec devise
• Conversion des booléens : Transformation en format lisible
• Traduction des énumérations : Support des enums avec traduction
• Formatage des décimaux : Notation française avec virgule
• Big integers : Conversion en int + formatage avec séparateurs de milliers (ex: 1 500 000)
• Méthodes dynamiques : Ajout de casts personnalisés à la volée

🛠️ Commandes Artisan

• maravel:install : Installe et configure automatiquement Maravel (API, AuthController, config)
• make:maravel.controller : Génère un contrôleur API complet avec CRUD, validation, hooks
• make:maravel.model : Génère un modèle avec ModelBase et formatage automatique
• make:maravel.policy : Génère une policy avancée avec système de permissions
• Note : Les commandes Laravel par défaut (make:controller, make:model, make:policy) restent disponibles

⚡ Traits réutilisables

• ModelTrait : Formatage automatique des données (dates, money, enums, booleans, big integers)
• CustomResponseTrait : Formatage standardisé des réponses JSON avec encodage UTF-8
• ControllerHelperTrait : Méthodes utilitaires pour les filtres, recherches, reducers et fichiers
• PermissionCheckerTrait : Vérification des permissions simplifiée
• ScriptGeneratorTrait : Génération de code automatique

Prérequis

• PHP : 8.1, 8.2, 8.3 ou 8.4
• Laravel : 10.x, 11.x ou 12.x
• Composer : 2.x

Installation

Installez la librairie via Composer :

Le service provider sera automatiquement enregistré grâce à l'auto-discovery de Laravel.

Installation automatique

Une fois la librairie installée, lancez la commande d'installation pour configurer automatiquement votre projet :

Cette commande effectue automatiquement les actions suivantes :

• 📦 Installation de Laravel Sanctum et configuration API (php artisan install:api)
• 🔐 Création du contrôleur AuthController dans app/Http/Controllers/API/
• 👥 Création du contrôleur UserController avec gestion du changement de mot de passe
• 🛡️ Création de la policy UserPolicy pour les permissions utilisateurs
• 🛣️ Configuration automatique du fichier routes/api.php avec les routes d'authentification et utilisateurs
• 👤 Création de la migration pour ajouter la colonne profile à la table users
• 🔒 Création de la migration pour ajouter les colonnes activated et password_change_required
• 🔧 Configuration du modèle User pour hériter de AuthenticatableBase
• 🛡️ Intégration du middleware AccountStatusMiddleware pour vérifier le statut des comptes
• ⚙️ Publication du fichier de configuration config/advanced-api-controller.php

✨ Fusion intelligente des fichiers existants

Nouvelle fonctionnalité (v2.6.0) : La commande maravel:install utilise désormais un système de fusion intelligente pour préserver vos personnalisations :

• Pas de remplacement destructif : Si les fichiers User.php, UserController.php, UserPolicy.php ou api.php existent déjà, ils sont fusionnés au lieu d'être remplacés
• Conservation de vos données : Toutes vos méthodes, propriétés et routes personnalisées sont préservées
• Priorité à la librairie : En cas de conflit (même nom de méthode/propriété), la version de la librairie est utilisée pour garantir la compatibilité
• Fusion intelligente :
  • Use statements : Fusion sans doublons
  • Traits : Conservation et ajout des nouveaux
  • Propriétés de classe : Fusion avec priorité aux valeurs de la librairie
  • Méthodes : Ajout des nouvelles méthodes, mise à jour des existantes
  • Routes : Fusion des use statements si les routes existent déjà
• Pas de confirmation : L'installation est automatique et non-destructive

Exemple : Si vous avez déjà ajouté des méthodes personnalisées dans UserController, elles seront conservées lors de l'exécution de maravel:install, et les méthodes de la librairie (comme updatePassword()) seront ajoutées ou mises à jour.

Le contrôleur AuthController créé inclut les méthodes suivantes :

• login() : Authentification des utilisateurs
• data() : Récupération des données de l'utilisateur connecté
• logout() : Déconnexion de l'utilisateur

Le modèle User est automatiquement configuré avec :

• Héritage de AuthenticatableBase (au lieu de Authenticatable)
• Champ profile dans $fillable
• Champs activated et password_change_required dans $fillable (v2.5.3+)
• Casts d'énumération pour le profil (admin → Administrateur, other → Utilisateur)
• Casts booléens pour activated et password_change_required
• Système de permissions via $enumCasts (v2.7.0+) : Les ability_rules sont générées automatiquement via $enumCasts
• Labels français automatiques pour profile, activated et password_change_required

Routes configurées automatiquement dans routes/api.php :

Endpoints disponibles :

• POST /api/auth/login - Connexion
• GET /api/auth/data - Données utilisateur (authentifié)
• DELETE /api/auth/logout - Déconnexion (authentifié)
• PUT /api/users/update-password - Changer le mot de passe (authentifié, toujours accessible)
• GET /api/users - Liste des utilisateurs (authentifié + statut actif)
• POST /api/users - Créer un utilisateur (authentifié + statut actif)
• GET /api/users/{id} - Voir un utilisateur (authentifié + statut actif)
• PUT /api/users/{id} - Modifier un utilisateur (authentifié + statut actif)
• DELETE /api/users/{id} - Supprimer un utilisateur (authentifié + statut actif)

Migrations créées :

1. xxxx_xx_xx_xxxxxx_add_profile_to_users_table.php

2. xxxx_xx_xx_xxxxxx_add_account_status_to_users_table.php (v2.5.3+)

Système de permissions (v2.7.0+) : Le modèle User est configuré avec un système de permissions basé sur les profils via $enumCasts :

• admin : Accès complet à toutes les ressources (['subject' => ['all'], 'action' => ['manage']])
• other : Permissions limitées (lecture utilisateur uniquement)

Vous pouvez étendre les permissions en modifiant le $enumCasts correspondant dans app/Models/User.php. Les ability_rules sont maintenant générées automatiquement via le système de casts unifié.

Gestion du statut des comptes (v2.5.3+) :

Le middleware AccountStatusMiddleware (alias : account.status) vérifie automatiquement :

• activated = false : Bloque l'accès avec le message "Votre compte est désactivé"
• password_change_required = true : Bloque l'accès avec le message "Vous devez changer votre mot de passe" (sauf pour la route /users/update-password)

Ce middleware est automatiquement appliqué aux routes CRUD des utilisateurs, mais pas à la route de changement de mot de passe, permettant ainsi aux utilisateurs de changer leur mot de passe même si password_change_required est à true.

Publication manuelle de la configuration (optionnel)

Si vous souhaitez uniquement publier le fichier de configuration sans exécuter l'installation complète :

Cela créera le fichier config/advanced-api-controller.php.

Configuration

Le fichier de configuration config/advanced-api-controller.php vous permet de personnaliser :

Defaults (Paramètres par défaut)

Filters (Configuration des filtres)

Models (Configuration des modèles)

Permissions (Configuration des permissions)

Démarrage rapide

1. Créer un contrôleur

2. Définir le modèle et la validation

3. Créer les routes

4. C'est prêt!

Votre API est maintenant opérationnelle avec :

• GET /api/products - Liste tous les produits
• GET /api/products/{id} - Affiche un produit
• POST /api/products - Crée un produit
• PUT/PATCH /api/products/{id} - Modifie un produit
• DELETE /api/products/{id} - Supprime un produit

Utilisation avancée

APIController

Le contrôleur de base fournit toutes les méthodes CRUD et de nombreuses options de personnalisation.

Propriétés disponibles

Méthodes disponibles

• index(Request $request) : Liste les ressources avec filtrage, recherche, tri, pagination
• show($id, Request $request) : Affiche une ressource spécifique
• store(Request $request) : Crée une nouvelle ressource
• store_multiple(Request $request) : Crée plusieurs ressources en une fois
• update(Request $request, $id) : Met à jour une ressource
• destroy($id) : Supprime une ressource

Gestion des uploads de gros fichiers

L'APIController inclut des méthodes pour gérer l'upload de fichiers volumineux par chunks (morceaux) :

uploadChunk()

Permet de télécharger un fichier volumineux en plusieurs morceaux :

mergeChunks()

Fusionne tous les morceaux uploadés en un seul fichier :

Fonctionnalités :

• Stockage temporaire des chunks dans storage/app/tmp/
• Fusion sécurisée avec verrouillage de fichier
• Nettoyage automatique des fichiers temporaires
• Nom de fichier sécurisé (slug + extension)
• Stockage final dans storage/app/public/uploads/{timestamp}/

Sécurité :

• Validation des chunks
• Tri numérique correct des morceaux
• Gestion des erreurs de lecture/écriture
• Suppression récursive des répertoires temporaires

ModelBase

Utilisez ModelBase comme classe parente pour vos modèles afin de bénéficier du formatage automatique.

Structure de $enumCasts (v2.6.8+)

Depuis la version 2.6.8, la structure de $enumCasts a été améliorée pour offrir plus de flexibilité. Chaque élément est maintenant un tableau associatif avec les clés suivantes :

Avantages de cette structure :

• ✅ Personnalisation du nom de la colonne formatée (au lieu du suffixe _fr automatique)
• ✅ Support de plusieurs énumérations dans un même modèle
• ✅ Plus de clarté et de lisibilité dans la configuration

Exemple de résultat JSON :

Méthodes dynamiques

Ajoutez des casts à la volée :

Attributs automatiques

Les attributs suivants sont automatiquement ajoutés :

• created_at_fr : Date de création formatée
• updated_at_fr : Date de mise à jour formatée
• {field}_formatted : Version formatée des booléens
• {field}_fr : Version formatée des dates, montants, floats et big integers
• {additional_column_name} : Version formatée des énumérations avec nom personnalisable (défini dans $enumCasts)

Exemple avec big_integer_casts :

Exemple avec booleanCasts (v2.6.9+) :

Note : Depuis la version 2.6.9, les booléens sont automatiquement convertis en entiers (0 ou 1) pour améliorer la compatibilité avec les APIs et bases de données qui attendent des valeurs numériques.

ModelTrait

Le coeur du système de formatage. Ce trait est utilisé par ModelBase et AuthenticatableBase.

Fonctionnalités du trait

Méthodes disponibles

• addDateCast($column, $format) : Ajoute un cast de date dynamiquement
• addMoneyCast($column) : Ajoute un cast monétaire dynamiquement
• addBooleanCast($column) : Ajoute un cast booléen dynamiquement
• addEnumCast($column, $choices) : Ajoute un cast enum dynamiquement
• addFloatCast($column) : Ajoute un cast float dynamiquement
• addBigIntegerCast($column) : Ajoute un cast big integer dynamiquement (conversion en int + formatage avec espaces)

Détails des casts

big_integer_casts

Convertit les grands entiers en int et ajoute une version formatée avec séparateurs de milliers :

Utilisation directe du trait

Vous pouvez utiliser ModelTrait directement sans hériter de ModelBase :

AuthenticatableBase

Pour les modèles nécessitant l'authentification (comme User), Maravel fournit AuthenticatableBase.

Créer un modèle User

Exemple de modèle User

Avantages d'AuthenticatableBase

• ✅ Compatible avec l'authentification Laravel : Étend Illuminate\Foundation\Auth\User
• ✅ Formatage automatique : Utilise ModelTrait pour les mêmes fonctionnalités que ModelBase
• ✅ Support Sanctum : Compatible avec Laravel Sanctum pour les API
• ✅ Permissions intégrées : Système d'abilités prêt à l'emploi
• ✅ Méthodes utilitaires : isAdmin(), hasProfile() générées automatiquement

Architecture

Les deux classes utilisent le même trait ModelTrait, évitant ainsi la duplication de code.

Gestion des utilisateurs et sécurité des comptes

Maravel inclut un système complet de gestion des utilisateurs avec contrôle du statut des comptes (v2.5.3+).

UserController

Le contrôleur UserController est automatiquement créé lors de l'installation et inclut :

• Opérations CRUD complètes : Liste, création, modification, suppression des utilisateurs
• Méthode updatePassword() : Permet aux utilisateurs de changer leur mot de passe
• Validation automatique : Règles de validation pour création et modification
• Hachage des mots de passe : Les mots de passe sont automatiquement hachés
• Gestion du statut : Support des champs activated et password_change_required

Méthode updatePassword :

Cette méthode :

• Vérifie que le mot de passe actuel est correct
• Valide le nouveau mot de passe (minimum 8 caractères)
• Vérifie que la confirmation correspond
• Met automatiquement password_change_required à false après changement

AccountStatusMiddleware

Le middleware AccountStatusMiddleware (alias : account.status) vérifie le statut du compte utilisateur avant d'autoriser l'accès aux routes protégées.

Vérifications effectuées :

1. Compte désactivé (activated = false) :

   Code HTTP : 403

2. Changement de mot de passe requis (password_change_required = true) :

   Code HTTP : 403

Important : Le middleware n'est PAS appliqué à la route /users/update-password, permettant aux utilisateurs de changer leur mot de passe même si password_change_required = true.

Utilisation du middleware

Le middleware est automatiquement configuré dans bootstrap/app.php :

Appliquez-le sur vos routes :

Scénarios d'utilisation

1. Désactiver un utilisateur :

2. Forcer le changement de mot de passe :

3. Réactiver un compte :

BasePolicy

Créez des policies avancées avec système de permissions.

Créer une policy

Exemple de policy

Enregistrer la policy

Dans AuthServiceProvider.php :

Traits disponibles

CustomResponseTrait

Formatage standardisé des réponses JSON :

ControllerHelperTrait

Méthodes utilitaires pour les contrôleurs :

Reducers personnalisés

Le trait fournit également reduceCollection() qui permet d'appliquer des transformations personnalisées sur une collection après une requête SQL :

Les reducers sont automatiquement appliqués par l'APIController après l'exécution de la requête SQL, permettant des transformations complexes sans surcharger la requête.

PermissionCheckerTrait

Vérification simplifiée des permissions :

Commandes Artisan

Maravel fournit plusieurs commandes personnalisées qui coexistent avec les commandes Laravel standard. Les commandes par défaut (make:controller, make:policy) restent disponibles et fonctionnelles.

maravel:install

Installe et configure automatiquement Maravel dans votre projet Laravel :

Ce qui est exécuté automatiquement :

• ✅ Installation de Laravel Sanctum et configuration API (php artisan install:api)
• ✅ Création du contrôleur AuthController dans app/Http/Controllers/API/
• ✅ Création du contrôleur UserController avec méthode updatePassword() (v2.5.3+)
• ✅ Création de la policy UserPolicy pour les permissions utilisateurs (v2.5.3+)
• ✅ Configuration automatique des routes d'authentification et utilisateurs dans routes/api.php
• ✅ Création de la migration pour ajouter la colonne profile (enum: admin, other)
• ✅ Création de la migration pour activated et password_change_required (v2.5.3+)
• ✅ Configuration du modèle User avec AuthenticatableBase et système de permissions
• ✅ Intégration du middleware AccountStatusMiddleware dans bootstrap/app.php (v2.5.3+)
• ✅ Publication du fichier de configuration config/advanced-api-controller.php
• ✅ Fusion intelligente des fichiers existants (v2.6.0+) : Vos personnalisations sont préservées

Avantages :

• Configuration rapide et sans erreur
• AuthController prêt à l'emploi avec login, logout et récupération des données utilisateur
• Routes d'authentification configurées automatiquement (plus besoin de les ajouter manuellement)
• Support complet de Laravel Sanctum pour l'authentification API
• Structure de routes organisée avec groupes et préfixes
• Système de permissions prêt à l'emploi avec profils utilisateur (admin, user)
• Modèle User configuré avec AuthenticatableBase et ability_rules
• Fusion non-destructive : Vos méthodes et propriétés personnalisées sont conservées
• Installation répétable : Vous pouvez relancer la commande pour mettre à jour sans perte de données

Recommandation : Lancez cette commande immédiatement après composer require mawena/maravel pour configurer votre projet en une seule commande. Vous pouvez aussi la relancer après une mise à jour de la librairie pour bénéficier des nouvelles fonctionnalités sans perdre vos personnalisations.

make:maravel.controller

Génère un contrôleur API complet avec APIController :

Ce qui est généré :

• Toutes les méthodes CRUD prêtes à l'emploi
• Système de validation avancé
• Hooks (before/after create, update, delete)
• Documentation PHPDoc complète
• Gestion des permissions intégrée
• Support automatique des filtres et pagination

Emplacement : App\Http\Controllers\API\ProductController.php

make:maravel.model

Génère un modèle avec ModelBase ou AuthenticatableBase :

Ce qui est généré :

• Extension de ModelBase (ou AuthenticatableBase avec option -a)
• Formatage automatique des dates (created_at_fr, updated_at_fr)
• Support des casts personnalisés ($dateCasts, $moneyCasts, $enumCasts, $booleanCasts)
• Relations Eloquent commentées (exemples)
• Scopes commentés (exemples)
• Méthodes utilitaires (pour User: isAdmin(), hasProfile())

Emplacement : App\Models\Product.php

Options disponibles :

• -m ou --migration : Crée automatiquement la migration
• -c ou --controller : Crée automatiquement le contrôleur API
• -p ou --policy : Crée automatiquement la policy
• -a ou --authenticatable : Crée un modèle Authenticatable (User)
• --all : Crée migration, contrôleur et policy en une seule commande

Exemples :

make:maravel.policy

Génère une policy avancée avec BasePolicy :

Ce qui est généré :

• Toutes les méthodes de permissions (viewAny, view, create, update, delete, restore, forceDelete)
• Méthode before() pour vérifications globales
• Support des permissions personnalisées
• Système de règles d'abilités
• Documentation PHPDoc complète

Emplacement : App\Policies\ProductPolicy.php

Différence avec les commandes Laravel standard

Exemples d'utilisation complète

Filtres avancés

L'APIController supporte plusieurs types de filtres via l'URL :

Filtres basiques

Filtrer par égalité :

Filtres min/max

Filtrer par plage de valeurs :

Filtres IN/NOT IN

Filtrer par liste de valeurs :

Recherche textuelle

Rechercher dans plusieurs champs :

Les champs de recherche sont définis dans $indexSearchFieldList.

Chargement des relations

Charger des relations Eloquent :

Relations imbriquées :

Tri

Trier les résultats :

Pagination

Contrôler la pagination :

Reducers personnalisés

Appliquer des transformations personnalisées après la requête :

Les reducers sont définis dans le modèle (voir section ControllerHelperTrait).

Combinaison de filtres

Combiner plusieurs filtres :

Système de permissions

Maravel utilise un système de permissions flexible basé sur les profils et les règles d'abilités.

Structure des ability_rules

Les utilisateurs doivent avoir un attribut ability_rules qui est un tableau de règles :

Actions disponibles

• read : Lecture (viewAny, view)
• create : Création
• update : Mise à jour
• delete : Suppression
• manage : Toutes les actions
• Personnalisées : Vous pouvez définir vos propres actions

Profils utilisateur

L'attribut profile détermine le niveau d'accès :

Vérification des permissions

Dans les contrôleurs

Dans les policies

Dans les vues Blade

Hooks et callbacks

L'APIController propose de nombreux hooks pour personnaliser le comportement.

Hooks de création

Hooks de mise à jour

Hooks de suppression

Filtre manuel sur index

Exemples complets

Exemple 1 : API de blog

Modèle

Contrôleur

Routes

Utilisation

Exemple 2 : E-commerce avec permissions

Modèle Product

Policy

Contrôleur

Configuration des ability_rules

Tests

La librairie inclut des tests PHPUnit pour assurer la qualité du code.

Exécuter les tests

Tests disponibles

• Tests du contrôleur API (CRUD complet)
• Tests des filtres (basiques, min/max, IN/NOT IN, etc.)
• Tests de la pagination
• Tests des relations
• Tests de validation
• Tests des permissions
• Tests des hooks

Changelog

Consultez le fichier CHANGELOG.md pour voir l'historique complet des modifications.

Contribution

Les contributions sont les bienvenues! Voici comment contribuer :

1. Fork le projet
2. Créez votre branche de fonctionnalité (git checkout -b feature/AmazingFeature)
3. Committez vos changements (git commit -m 'Add some AmazingFeature')
4. Push vers la branche (git push origin feature/AmazingFeature)
5. Ouvrez une Pull Request

Guidelines

• Suivez les conventions de codage PSR-12
• Ajoutez des tests pour les nouvelles fonctionnalités
• Mettez à jour la documentation si nécessaire
• Assurez-vous que tous les tests passent

License

Ce projet est sous licence MIT. Consultez le fichier LICENSE pour plus de détails.

Copyright (c) 2024 Charles GAMLIGO

Auteur

Charles GAMLIGO (Mawena)

• Email: [email protected]
• GitHub: @mawena

Support

• Issues: GitHub Issues
• Source: GitHub Repository

Remerciements

Merci à tous les contributeurs qui ont participé au développement de cette librairie.

Maravel - Accélérez votre développement d'API Laravel avec élégance et puissance.