# Documentation du Projet PlatformAPI ## Vue d'ensemble **PlatformAPI** est une plateforme de gestion de contenu (CMS) headless moderne construite avec Laravel 12 et React/TypeScript. Elle offre une interface d'administration complète et une API RESTful pour la gestion de projets, collections, contenus, médias et webhooks. ### Technologies principales - **Backend**: Laravel 12 (PHP 8.2+) - **Frontend**: React 19, TypeScript, Inertia.js - **Base de données**: MySQL/PostgreSQL (via Laravel) - **Authentification**: Laravel Sanctum - **Permissions**: Spatie Laravel Permission - **Stockage**: Support local et AWS S3 - **Interface**: Radix UI, Tailwind CSS 4 - **Tests**: Pest PHP --- ## Architecture du projet ### Structure des dossiers ``` platformapi/ ├── app/ │ ├── Console/Commands/ # Commandes Artisan │ ├── Events/ # Événements │ ├── Http/ │ │ ├── Controllers/ # Contrôleurs web et API │ │ ├── Middleware/ # Middleware personnalisés │ │ ├── Requests/ # Form requests de validation │ │ └── Resources/ # API Resources │ ├── Jobs/ # Jobs de queue │ ├── Listeners/ # Écouteurs d'événements │ ├── Models/ # Modèles Eloquent │ ├── Providers/ # Service providers │ ├── Rules/ # Règles de validation │ └── Services/ # Services métier ├── database/ │ ├── migrations/ # Migrations de base de données │ ├── seeders/ # Seeders │ └── factories/ # Factories pour les tests ├── resources/ │ ├── js/ # Code frontend React/TypeScript │ │ ├── components/ # Composants React réutilisables │ │ ├── pages/ # Pages Inertia │ │ ├── layouts/ # Layouts │ │ ├── hooks/ # Hooks React personnalisés │ │ ├── lib/ # Utilitaires et configurations │ │ └── types/ # Définitions TypeScript │ └── css/ # Styles CSS ├── routes/ │ ├── api.php # Routes API REST │ ├── web.php # Routes web (interface admin) │ ├── auth.php # Routes d'authentification │ └── settings.php # Routes de paramètres └── tests/ # Tests Pest ``` --- ## Concepts principaux ### 1. Projets (Projects) Un **projet** est le conteneur principal de l'application. Chaque projet contient : - Des collections - Des assets (fichiers médias) - Des membres (utilisateurs) - Des webhooks - Des paramètres de localisation **Caractéristiques** : - UUID unique pour l'accès API - Support multi-locale - API publique ou privée (avec authentification) - Stockage configurable (local ou S3) **Modèle**: `App\Models\Project` ### 2. Collections Une **collection** définit un schéma de contenu avec des champs personnalisables. Elle peut être : - **Standard** : contient plusieurs entrées de contenu - **Singleton** : contient une seule entrée de contenu **Caractéristiques** : - Slug unique par projet - Ordre personnalisable - Champs configurables - Support des templates **Modèle**: `App\Models\Collection` ### 3. Champs (Fields) Les **champs** définissent la structure des données dans une collection. Types de champs supportés : #### Types de base - `text` : Texte court - `longtext` : Texte long - `richtext` : Éditeur WYSIWYG (TinyMCE) - `slug` : Slug automatique (basé sur un autre champ) - `email` : Adresse email - `password` : Mot de passe (hashé) - `number` : Nombre - `boolean` : Booléen - `color` : Sélecteur de couleur - `date` : Date (avec option heure) - `time` : Heure - `json` : Données JSON arbitraires #### Types avancés - `enumeration` : Liste de valeurs prédéfinies (multi-sélection possible) - `media` : Fichiers médias (images, vidéos, documents) - `relation` : Relation vers d'autres entrées de contenu **Options communes** : - `repeatable` : Permet plusieurs valeurs - `required` : Champ obligatoire - `hideInContentList` : Masquer dans la liste de contenu - `hiddenInAPI` : Masquer dans les réponses API **Modèle**: `App\Models\Field` ### 4. Entrées de contenu (Content Entries) Les **entrées de contenu** sont les instances réelles de données dans une collection. **Caractéristiques** : - UUID unique - Statut : `draft` ou `published` - Support multi-locale - Soft deletes (suppression réversible) - Métadonnées de création/modification **Modèle**: `App\Models\ContentEntry` ### 5. Assets (Médias) Les **assets** sont les fichiers médias (images, vidéos, documents) associés à un projet. **Caractéristiques** : - Support de multiples types de fichiers - Génération automatique de miniatures pour les images - Métadonnées (dimensions, taille, type MIME) - Stockage configurable (local ou S3) - Recadrage d'images **Types supportés** : - Images : JPG, PNG, GIF, WebP, SVG, BMP - Vidéos : MP4, WebM, OGG, MOV, AVI, WMV, FLV - Audio : MP3, WAV, OGG, AAC, FLAC - Documents : PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT **Modèle**: `App\Models\Asset` ### 6. Webhooks Les **webhooks** permettent d'envoyer des notifications HTTP lors d'événements dans le projet. **Événements supportés** : - Création de contenu - Mise à jour de contenu - Suppression de contenu - Publication de contenu **Caractéristiques** : - Filtrage par collection - Secret pour la signature - Logs des tentatives d'envoi - Statut activé/désactivé **Modèle**: `App\Models\Webhook` ### 7. Utilisateurs et permissions Le système utilise **Spatie Laravel Permission** pour la gestion des rôles et permissions. **Concepts** : - **Utilisateurs** : Comptes utilisateurs - **Rôles** : Groupes de permissions - **Permissions** : Droits d'accès granulaires **Permissions principales** : - Gestion de projets : `create_project`, `delete_project`, `access_project_settings` - Gestion de collections : `create_collection`, `update_collection`, `delete_collection` - Gestion de contenu : `create_content`, `update_content`, `delete_content`, `move_content_to_trash` - Gestion de médias : `upload_asset`, `update_asset`, `delete_asset`, `access_assets` - Gestion d'utilisateurs : `access_users`, `create_users`, `update_users`, `delete_users` - Et bien d'autres... **Modèle**: `App\Models\User`, `App\Models\Role` --- ## API REST ### Authentification L'API utilise Laravel Sanctum pour l'authentification. Deux modes d'accès sont disponibles : #### 1. API publique - Projet avec `public_api = true` - Aucune authentification requise - Accès en lecture seule #### 2. API privée - Projet avec `public_api = false` - Authentification via token Sanctum requis - Permissions basées sur les abilities du token (`create`, `update`, `delete`, `read`) ### Headers requis ``` project-id: {project-uuid} Authorization: Bearer {sanctum-token} # Si API privée ``` ### Endpoints principaux #### Informations du projet ``` GET /api/ ``` #### Collections ``` GET /api/collections # Liste des collections GET /api/collections/{slug} # Détails d'une collection ``` #### Contenu ``` GET /api/{collection} # Liste des entrées GET /api/{collection}/{uuid} # Détails d'une entrée POST /api/{collection} # Créer une entrée (token requis) PUT/PATCH /api/{collection}/{uuid} # Mettre à jour (token requis) DELETE /api/{collection}/{uuid} # Supprimer (token requis) ``` #### Assets ``` GET /api/files # Liste des fichiers GET /api/files/{identifier} # Détails d'un fichier GET /api/files/name/{filename} # Recherche par nom POST /api/files # Upload (token requis) DELETE /api/files/{identifier} # Supprimer (token requis) ``` ### Paramètres de requête #### Filtrage de contenu **État** : - `?state=published` (défaut) : Uniquement publié - `?state=only_draft` : Uniquement brouillons - `?state=with_draft` : Publié et brouillons **Locale** : - `?locale=fr` : Filtrer par locale **Pagination** : - `?paginate=20` : Pagination Laravel (20 par page) - `?limit=10&offset=0` : Limite et offset manuels **Tri** : - `?sort=created_at:DESC` : Trier par colonne - `?sort=field_name:ASC` : Trier par champ personnalisé **Exclusion de champs** : - `?exclude=field1,field2` : Exclure des champs de la réponse #### Filtrage avancé (where) Le paramètre `where` permet des requêtes complexes : **Opérateurs supportés** : - `eq` : Égal à - `not` : Différent de - `lt`, `lte`, `gt`, `gte` : Comparaisons numériques - `like` : Recherche textuelle - `in`, `not_in` : Dans une liste - `null`, `not_null` : Vérification de nullité - `between`, `not_between` : Entre deux valeurs **Exemples** : ```http # Filtre simple GET /api/posts?where[status][eq]=published # Filtre avec opérateur GET /api/posts?where[price][gte]=100 # Filtre sur champ personnalisé GET /api/posts?where[title][like]=tutorial # Filtre multiple (AND) GET /api/posts?where[status][eq]=published&where[price][gte]=100 # Filtre OR GET /api/posts?where[or][status][eq]=draft&where[or][status][eq]=published # Filtre sur relation GET /api/posts?where[author][name][eq]=John # Filtre avec IN GET /api/posts?where[tags][in]=News,Tech ``` **Comptage** : ``` GET /api/{collection}?count=1 ``` ### Format des réponses Les réponses utilisent des **API Resources** Laravel pour formater les données. **Exemple de réponse d'entrée de contenu** : ```json { "uuid": "550e8400-e29b-41d4-a716-446655440000", "status": "published", "locale": "fr", "published_at": "2025-01-15T10:30:00.000000Z", "created_at": "2025-01-15T10:30:00.000000Z", "updated_at": "2025-01-15T10:30:00.000000Z", "data": { "title": "Mon article", "content": "Contenu de l'article...", "author": { "uuid": "...", "data": { ... } }, "images": [ { "uuid": "...", "filename": "image.jpg", "url": "https://..." } ] } } ``` --- ## Interface d'administration L'interface d'administration est construite avec **Inertia.js** et **React**, offrant une expérience SPA moderne. ### Pages principales #### Dashboard - Vue d'ensemble des projets - Accès rapide aux projets récents #### Gestion de projets - Création/édition de projets - Paramètres de projet : - Informations générales - Localisation (locales) - Accès utilisateurs - Accès API (tokens, API publique) - Webhooks #### Gestion de collections - Création/édition de collections - Gestion des champs - Réorganisation par glisser-déposer - Templates de collections #### Gestion de contenu - Liste de contenu avec filtres - Édition de contenu avec formulaire dynamique - Recherche - Duplication - Corbeille (soft delete) #### Gestion de médias - Bibliothèque de médias - Upload de fichiers - Recadrage d'images - Métadonnées #### Gestion des utilisateurs - Liste des utilisateurs - Création/édition - Attribution de rôles - Gestion des permissions ### Composants UI L'interface utilise **Radix UI** et **Tailwind CSS** pour des composants accessibles et modernes : - Formulaires avec validation - Modales et dialogues - Tables avec tri et pagination - Éditeur de texte riche (TinyMCE) - Sélecteurs de fichiers - Calendriers - Et bien d'autres... --- ## Configuration ### Variables d'environnement Fichier `.env` : ```env # Application APP_NAME=PlatformAPI APP_ENV=local APP_KEY= APP_DEBUG=true APP_URL=http://localhost # Base de données DB_CONNECTION=mysql DB_HOST=127.0.0.1 DB_PORT=3306 DB_DATABASE=platformapi DB_USERNAME=root DB_PASSWORD= # Stockage FILESYSTEM_DISK=public AWS_ACCESS_KEY_ID= AWS_SECRET_ACCESS_KEY= AWS_DEFAULT_REGION= AWS_BUCKET= # Queue QUEUE_CONNECTION=database # Cache CACHE_DRIVER=file SESSION_DRIVER=file ``` ### Configuration des projets Chaque projet peut être configuré avec : - **Locales** : Langues supportées (ex: `['fr', 'en', 'de']`) - **Locale par défaut** : Locale principale - **Stockage** : Disque de stockage (`public`, `s3`, etc.) - **API publique** : Activer/désactiver l'accès public --- ## Développement ### Installation ```bash # Installer les dépendances PHP composer install # Installer les dépendances Node npm install # Copier le fichier d'environnement cp .env.example .env # Générer la clé d'application php artisan key:generate # Exécuter les migrations php artisan migrate # Seeder la base de données php artisan db:seed # Compiler les assets npm run build ``` ### Commandes de développement ```bash # Démarrer le serveur de développement (Laravel + Vite + Queue + Logs) composer dev # Démarrer avec SSR (Server-Side Rendering) composer dev:ssr # Tests composer test php artisan test # Linting npm run lint npm run format # Vérification TypeScript npm run types ``` ### Structure des tests Les tests utilisent **Pest PHP** : - Tests unitaires : `tests/Unit/` - Tests fonctionnels : `tests/Feature/` --- ## Fonctionnalités avancées ### Templates #### Templates de collections Permet de sauvegarder une collection avec ses champs comme template réutilisable. #### Templates de projets Permet de sauvegarder un projet complet (collections, champs) comme template. ### Clonage de projets Possibilité de cloner la structure d'un projet (sans le contenu). ### Webhooks Les webhooks sont déclenchés lors d'événements de contenu : - `content.created` - `content.updated` - `content.deleted` - `content.published` **Configuration** : - URL de destination - Secret pour signature - Collections ciblées - Événements à écouter - Inclure le payload dans la requête **Logs** : Chaque tentative d'envoi est loggée avec : - Statut (succès/échec) - Code de réponse HTTP - Message d'erreur éventuel - Timestamp ### Localisation Support multi-locale complet : - Définition de locales par projet - Locale par défaut - Entrées de contenu par locale - Filtrage par locale dans l'API ### Soft Deletes Les entrées de contenu et collections utilisent le soft delete : - Suppression réversible - Restauration possible - Suppression définitive optionnelle --- ## Sécurité ### Authentification - Laravel Sanctum pour l'API - Sessions pour l'interface web - Tokens avec abilities (permissions) ### Autorisation - Système de permissions granulaire (Spatie) - Vérification au niveau des routes - Vérification au niveau des contrôleurs - Middleware de vérification d'accès projet ### Validation - Form Requests Laravel - Validation côté serveur - Validation côté client (React Hook Form + Zod) ### Protection CSRF - Protection automatique Laravel - Tokens CSRF pour les formulaires --- ## Performance ### Optimisations - Eager loading des relations - Pagination des listes - Cache des requêtes fréquentes - Queue pour les tâches asynchrones (webhooks) ### Assets - Compilation Vite pour le frontend - Optimisation des images (Intervention Image) - Génération de miniatures - Support CDN (S3) --- ## Maintenance ### Commandes utiles ```bash # Nettoyer le cache php artisan cache:clear php artisan config:clear php artisan route:clear php artisan view:clear # Optimiser php artisan optimize php artisan config:cache php artisan route:cache # Queue php artisan queue:work php artisan queue:listen # Migrations php artisan migrate php artisan migrate:rollback php artisan migrate:fresh --seed ``` ### Logs Les logs sont disponibles dans : - `storage/logs/laravel.log` : Logs applicatifs - Logs de webhooks dans la base de données (`webhook_logs`) --- ## Contribution ### Standards de code - **PHP** : Laravel Pint (PSR-12) - **JavaScript/TypeScript** : ESLint + Prettier - **Tests** : Pest PHP ### Workflow 1. Créer une branche depuis `main` 2. Développer la fonctionnalité 3. Écrire les tests 4. Vérifier le linting 5. Créer une pull request --- ## Support et ressources ### Documentation Laravel - [Laravel Documentation](https://laravel.com/docs) - [Inertia.js Documentation](https://inertiajs.com/) - [React Documentation](https://react.dev/) ### Packages principaux - Laravel Framework 12 - Inertia.js Laravel - Spatie Laravel Permission - Intervention Image - Laravel Sanctum - Radix UI - Tailwind CSS --- ## Licence MIT License --- *Documentation générée le 2025-01-15*