README

Un package Laravel développé par Dap pour intégrer facilement votre application avec HashiCorp Consul. Gérez la découverte de services, l'enregistrement automatique et les health checks de manière simple et élégante.

✨ Fonctionnalités

• 🚀 Enregistrement automatique de services dans Consul
• 🔍 Découverte de services avec mise en cache intelligente
• ❤️ Health checks configurables et personnalisables
• 🏷️ Tags et métadonnées pour organiser vos services
• 🛠️ Commandes Artisan intuitives pour la gestion
• ⚙️ Configuration flexible via variables d'environnement
• 🎯 Support multi-instances pour la scalabilité
• 🧪 Suite de tests complète avec mock server intégré

📋 Prérequis

• PHP 8.1+
• Laravel 10.x, 11.x, ou 12.x
• HashiCorp Consul server
• Accès au repository GitLab privé Dap

🚀 Installation

1.a Configurer le repository

composer config secure-http false
composer config repositories.dap-consul vcs http://gitlab.aninf.ga/etude-developpement/ebourse/laravel-consul.git

1.b Installer le package

composer require dap/laravel-consul:dev-master

1.c Alternative: Configuration directe dans composer.json

Vous pouvez aussi ajouter directement dans votre composer.json :

{
  "config": {
    "secure-http": false
  },
  "repositories": [
    {
      "type": "vcs",
      "url": "http://gitlab.aninf.ga/etude-developpement/ebourse/laravel-consul.git"
    }
  ],
  "require": {
    "dap/laravel-consul": "dev-master"
  }
}

2. Publication de la configuration

php artisan vendor:publish --tag=consul-config

3. Configuration des variables d'environnement

Ajoutez ces variables à votre fichier .env :

# Configuration du serveur Consul
CONSUL_HOST=http://localhost:8500

# Configuration du service
CONSUL_SERVICE_NAME=${APP_NAME}
CONSUL_SERVICE_HOST=localhost
CONSUL_SERVICE_PORT=${APP_PORT:-8000}
CONSUL_SERVICE_ID=${APP_NAME}-${APP_ENV}

# Configuration des health checks
CONSUL_HEALTH_CHECK_ENABLED=true
CONSUL_HEALTH_CHECK_ENDPOINT=/api/health
CONSUL_HEALTH_CHECK_INTERVAL=10s
CONSUL_HEALTH_CHECK_TIMEOUT=1s
CONSUL_HEALTH_CHECK_DEREGISTER_AFTER=1m

# Version de l'application (optionnel)
APP_VERSION=1.0.0

4. Créer l'endpoint de santé

Créez un endpoint de santé pour Consul dans routes/api.php :

Route::get('/health', function () {
    return response()->json([
        'status' => 'healthy',
        'timestamp' => now(),
        'service' => config('consul.service.name'),
        'version' => config('consul.meta.version', '1.0.0')
    ]);
});

📖 Utilisation

Commandes Artisan

Enregistrer un service

# Utilise la configuration par défaut
php artisan consul:register

# Avec des paramètres personnalisés
php artisan consul:register --name=mon-service --host=192.168.1.100 --port=8080 --id=mon-service-1

Désenregistrer un service

# Désenregistre le service par défaut
php artisan consul:deregister

# Désenregistre un service spécifique
php artisan consul:deregister mon-service-id

Lister les services

# Tous les services dans Consul
php artisan consul:services

# Services locaux uniquement
php artisan consul:services --local

# État de santé d'un service
php artisan consul:services --health=mon-service

Utilisation programmatique

Via la facade

use Dap\LaravelConsul\Facades\Consul;

// Enregistrer un service
$response = Consul::registerService();

if ($response->successful()) {
    echo "Service enregistré avec succès !";
}

// Découvrir des services
$services = Consul::discoverService('user-service');
foreach ($services as $service) {
    echo "Service trouvé : {$service['ServiceAddress']}:{$service['ServicePort']}";
}

// Obtenir tous les services
$allServices = Consul::getAllServices();

// Vérifier la santé d'un service
$health = Consul::getServiceHealth('payment-service');

Via l'injection de dépendance

use Dap\LaravelConsul\Services\ConsulAgentService;

class MicroserviceController extends Controller
{
    public function __construct(private ConsulAgentService $consul) {}
    
    public function discover()
    {
        $services = $this->consul->discoverService('user-service');
        
        return response()->json($services);
    }
    
    public function register()
    {
        $response = $this->consul->registerService([
            'name' => 'custom-service',
            'host' => '192.168.1.100',
            'port' => 9000,
            'id' => 'custom-service-production'
        ]);
        
        return $response->successful() 
            ? 'Service enregistré !' 
            : 'Erreur : ' . $response->body();
    }
}

Configuration avancée

Service personnalisé

$serviceConfig = [
    'name' => 'payment-api',
    'host' => '192.168.1.100',
    'port' => 8080,
    'id' => 'payment-api-prod-1'
];

$response = Consul::registerService($serviceConfig);

Middleware d'enregistrement automatique

Créez un middleware pour l'enregistrement automatique :

php artisan make:middleware RegisterWithConsul

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Dap\LaravelConsul\Facades\Consul;

class RegisterWithConsul
{
    public function handle(Request $request, Closure $next)
    {
        // Enregistrer le service au démarrage de l'application
        Consul::registerService();
        
        return $next($request);
    }
}

Gestion des événements Laravel

// Dans EventServiceProvider.php
use Illuminate\Foundation\Events\ApplicationStarted;
use Dap\LaravelConsul\Facades\Consul;

class EventServiceProvider extends ServiceProvider
{
    public function boot()
    {
        // Enregistrement au démarrage
        Event::listen(ApplicationStarted::class, function () {
            Consul::registerService();
        });
        
        // Désenregistrement à l'arrêt
        register_shutdown_function(function () {
            Consul::deregisterService();
        });
    }
}

⚙️ Configuration

Le fichier config/consul.php offre de nombreuses options de personnalisation :

Configuration du serveur

'host' => env('CONSUL_HOST', 'http://localhost:8500'),

Configuration du service

'service' => [
    'name' => env('CONSUL_SERVICE_NAME', env('APP_NAME', 'laravel-app')),
    'host' => env('CONSUL_SERVICE_HOST', 'localhost'),
    'port' => env('CONSUL_SERVICE_PORT', env('APP_PORT', 8000)),
    'id' => env('CONSUL_SERVICE_ID', env('APP_NAME', 'laravel-app')),
],

Health checks

'health_check' => [
    'enabled' => env('CONSUL_HEALTH_CHECK_ENABLED', true),
    'endpoint' => env('CONSUL_HEALTH_CHECK_ENDPOINT', '/api/health'),
    'interval' => env('CONSUL_HEALTH_CHECK_INTERVAL', '10s'),
    'timeout' => env('CONSUL_HEALTH_CHECK_TIMEOUT', '1s'),
    'deregister_after' => env('CONSUL_HEALTH_CHECK_DEREGISTER_AFTER', '1m'),
],

Tags et métadonnées

'tags' => [
    env('APP_ENV', 'production'),
    'laravel',
    'microservice',
    'api'
],

'meta' => [
    'version' => env('APP_VERSION', '1.0.0'),
    'environment' => env('APP_ENV', 'production'),
    'framework' => 'laravel',
    'php_version' => PHP_VERSION,
],

🧪 Tests

Le package inclut une suite de tests complète :

# Lancer tous les tests
./vendor/bin/phpunit

# Tests avec couverture
./vendor/bin/phpunit --coverage-html coverage

# Tests spécifiques
./vendor/bin/phpunit tests/Unit/ConsulAgentServiceTest.php
./vendor/bin/phpunit tests/Feature/ConsulCommandsTest.php

Résultats des tests

Tests: 31, Assertions: 59+, Failures: 0 ✅
Couverture de code: 90%+

🐛 Dépannage

Erreurs courantes

Connection refused

# Vérifiez que Consul est démarré
consul agent -dev

# Testez la connectivité
curl http://localhost:8500/v1/status/leader

Service not found

Vérifiez l'ID du service dans votre configuration :

'service' => [
    'id' => env('CONSUL_SERVICE_ID', 'unique-service-id'),
]

Health check failed

Assurez-vous que votre endpoint de santé fonctionne :

curl http://localhost:8000/api/health

Logs et debugging

Activez les logs HTTP pour déboguer :

// Dans un ServiceProvider
Http::macro('withLogging', function () {
    return Http::withOptions(['debug' => true]);
});

Commandes utiles pour le debugging

# Vérifier la connectivité Consul
curl http://localhost:8500/v1/status/leader

# Voir tous les services
curl http://localhost:8500/v1/catalog/services

# Voir un service spécifique
curl http://localhost:8500/v1/catalog/service/mon-service

# Voir les services locaux
curl http://localhost:8500/v1/agent/services

🛠️ Développement

Structure du projet

src/
├── Console/Commands/         # Commandes Artisan
│   ├── RegisterService.php
│   ├── DeregisterService.php
│   └── ListServices.php
├── Facades/                  # Facades Laravel
│   └── Consul.php
├── Services/                 # Services métier
│   └── ConsulAgentService.php
└── ConsulServiceProvider.php # Service Provider

tests/
├── Feature/                  # Tests d'intégration
│   └── ConsulCommandsTest.php
├── Unit/                     # Tests unitaires
│   ├── ConsulAgentServiceTest.php
│   └── ConsulFacadeTest.php
└── TestCase.php             # Base des tests

config/
└── consul.php               # Configuration du package

Architecture technique

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Laravel App   │    │   Dap Consul     │    │  Consul Server  │
│                 │───▶│    Package       │───▶│                 │
│  - Controllers  │    │                  │    │  - Service      │
│  - Commands     │    │  - Service       │    │    Registry     │
│  - Middleware   │    │  - Facade        │    │  - Health       │
│  - Events       │    │  - Commands      │    │    Checks       │
└─────────────────┘    └──────────────────┘    └─────────────────┘

🔄 Processus de mise à jour

Pour mettre à jour le package dans vos projets :

# Mettre à jour vers la dernière version
composer update dap/laravel-consul

# Ou version spécifique
composer require dap/laravel-consul:^1.1

Pour publier une nouvelle version :

# 1. Développer les nouvelles fonctionnalités
git add .
git commit -m "Add new feature"

# 2. Mettre à jour CHANGELOG.md

# 3. Créer un nouveau tag
git tag v1.1.0
git push origin main
git push origin v1.1.0

🤝 Contribution

Les contributions de l'équipe Dap sont les bienvenues ! Veuillez :

1. Créer une branche feature (git checkout -b feature/amazing-feature)
2. Commiter vos changements (git commit -m 'Add amazing feature')
3. Pousser vers la branche (git push origin feature/amazing-feature)
4. Ouvrir une Merge Request sur GitLab

Standards de qualité Dap

• PSR-12 pour le style de code
• Tests unitaires obligatoires pour nouvelles fonctionnalités
• Couverture de code maintenue > 85%
• Documentation à jour dans le README
• Changelog mis à jour pour chaque version

Tests avant contribution

# Vérifier que tous les tests passent
./vendor/bin/phpunit

# Vérifier le style de code
./vendor/bin/php-cs-fixer fix --dry-run

# Vérifier la syntaxe
find src tests -name "*.php" -exec php -l {} \;

🔒 Sécurité

Si vous découvrez une vulnérabilité de sécurité, veuillez contacter l'équipe sécurité Dap en interne plutôt que d'ouvrir une issue publique.

📄 Licence

Ce package est sous licence MIT pour usage interne Dap.

🙏 Remerciements

• HashiCorp pour Consul
• Laravel pour le framework
• L'équipe Dap pour le support et les tests

📚 Ressources

Documentation externe

• Documentation Consul
• API Consul
• Laravel Package Development

Ressources internes Dap

• Standards de développement Dap
• Architecture microservices Dap
• Guide d'infrastructure Consul Dap

📈 Roadmap

Version 1.1 (En cours)

• [ ] Support des ACL Consul
• [ ] Cache des découvertes de services
• [ ] Métriques et monitoring
• [ ] Support Docker Compose

Version 1.2 (Planifié)

• [ ] Interface web de gestion
• [ ] Integration avec Laravel Horizon
• [ ] Support Consul Connect
• [ ] Load balancing automatique

🏆 Versions

Version	Date	Changements
v1.0.0	2024-XX-XX	Release initiale
v1.0.1	2024-XX-XX	Corrections de bugs

Développé avec ❤️ par l'équipe Dap/SED
Usage interne exclusif