# Guide de migration Laravel 8 → Laravel 10

## Contexte

Le projet utilise actuellement **Laravel 8.40+** dont le support a pris fin en **janvier 2023**.
Ce guide détaille les étapes nécessaires pour migrer vers **Laravel 10** (LTS jusqu'en février 2025).

---

## Pré-requis

- **PHP 8.1+** (Laravel 10 requiert PHP 8.1 minimum)
- Sauvegarde complète de la base de données et du code

---

## Étape 1 : Mettre à jour `composer.json`

### Dépendances à modifier

| Package                      | Actuel   | Cible   | Notes                  |
| ---------------------------- | -------- | ------- | ---------------------- |
| `php`                        | `^8.0`   | `^8.1`  | Requis par Laravel 10  |
| `laravel/framework`          | `^8.40`  | `^10.0` | Mise à jour majeure    |
| `laravel/tinker`             | `^2.5`   | `^2.8`  | Compatible L10         |
| `guzzlehttp/guzzle`          | `^7.0.1` | `^7.2`  | Compatible L10         |
| `league/flysystem-aws-s3-v3` | `^1.0`   | `^3.0`  | API modifiée en v3     |
| `nwidart/laravel-modules`    | `8.2`    | `^10.0` | Vérifier compatibilité |
| `vinkla/hashids`             | `^9.1`   | `^10.0` | Vérifier compatibilité |
| `barryvdh/laravel-dompdf`    | `^0.9.0` | `^2.0`  | API inchangée          |

### Dépendances à supprimer

| Package                  | Raison                                                    |
| ------------------------ | --------------------------------------------------------- |
| `fideloper/proxy`        | Intégré dans Laravel 9+ (`TrustProxies` middleware natif) |
| `fruitcake/laravel-cors` | Intégré dans Laravel 10 (`HandleCors` middleware natif)   |

### Dépendances dev à modifier

| Package                | Actuel   | Cible                                          |
| ---------------------- | -------- | ---------------------------------------------- |
| `facade/ignition`      | `^2.5`   | Remplacer par `spatie/laravel-ignition` `^2.0` |
| `nunomaduro/collision` | `^5.0`   | `^7.0`                                         |
| `phpunit/phpunit`      | `^9.3.3` | `^10.0`                                        |

### Dépendances à risque (vérifier avant)

| Package                               | Problème potentiel                                                                                          |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `examyou/rest-api` (dev-master)       | Package privé, vérifier support Laravel 10                                                                  |
| `examyou/lara-installer` (dev-master) | Package privé, vérifier support Laravel 10                                                                  |
| `trebol/entrust` `^2.0`               | Fork de Zizaco Entrust, potentiellement abandonné. Considérer `spatie/laravel-permission` comme alternative |
| `tymon/jwt-auth` `^1.0`               | Vérifier que `^2.0` est disponible et compatible                                                            |

---

## Étape 2 : Fichiers de configuration

### Middleware HTTP (`app/Http/Kernel.php`)

**Supprimer :**
```php
// Supprimer cette ligne (fideloper/proxy)
\Fideloper\Proxy\TrustProxies::class,

// Supprimer cette ligne (fruitcake/cors)
\Fruitcake\Cors\HandleCors::class,
```

**Remplacer par :**
```php
\Illuminate\Http\Middleware\TrustProxies::class,
\Illuminate\Http\Middleware\HandleCors::class,
```

### Exception Handler (`app/Exceptions/Handler.php`)

Laravel 10 simplifie le handler. Vérifier la compatibilité.

### Configuration CORS (`config/cors.php`)

Le fichier reste compatible, mais vérifier que les paths sont corrects.

---

## Étape 3 : Changements de code

### 1. Retours typés des routes

Laravel 10 encourage les retours typés. Pas de breaking change, mais bonne pratique :

```php
// Avant
public function index()

// Après (recommandé)
public function index(): JsonResponse
```

### 2. Dates et Carbon

En Laravel 10, les dates utilisent des objets immuables par défaut :
```php
// Vérifier les usages de Carbon::now()->subDays() etc.
// Pas de changement requis si vous utilisez Carbon standard
```

### 3. Suppression de `$dates` property

La propriété `$dates` sur les modèles est dépréciée. Utiliser `$casts` à la place :

```php
// Avant
protected $dates = ['created_at', 'updated_at'];

// Après
protected $casts = [
    'created_at' => 'datetime',
    'updated_at' => 'datetime',
];
```

---

## Étape 4 : Procédure de migration

```bash
# 1. Créer une branche dédiée
git checkout -b upgrade/laravel-10

# 2. Mettre à jour composer.json manuellement (cf. tableau ci-dessus)

# 3. Supprimer vendor et lock
rm -rf vendor composer.lock

# 4. Installer les dépendances
composer install

# 5. Si erreurs de compatibilité, résoudre une par une

# 6. Republier les assets de configuration
php artisan vendor:publish --tag=laravel-config

# 7. Vider les caches
php artisan config:clear
php artisan cache:clear
php artisan view:clear
php artisan route:clear

# 8. Lancer les tests
php artisan test

# 9. Tester manuellement toutes les fonctionnalités
```

---

## Étape 5 : Alternative - Remplacement de Entrust

Si `trebol/entrust` n'est plus maintenu, migrer vers `spatie/laravel-permission` :

```bash
composer require spatie/laravel-permission
```

**Modifications requises :**
- Adapter les modèles `Role` et `Permission`
- Mettre à jour le middleware d'autorisation
- Adapter les seeders de permissions
- Modifier les vérifications `$user->hasPermission()` → `$user->hasPermissionTo()`

---

## Risques

| Risque                             | Impact   | Mitigation                              |
| ---------------------------------- | -------- | --------------------------------------- |
| Packages `examyou/*` incompatibles | Bloquant | Contacter le mainteneur ou forker       |
| `trebol/entrust` abandonné         | Élevé    | Migrer vers `spatie/laravel-permission` |
| Flysystem v1 → v3                  | Moyen    | Adapter les appels S3 si utilisés       |
| Tests échouent                     | Moyen    | Corriger un par un                      |

---

## Recommandation

1. **Court terme** : Rester sur Laravel 8 avec les correctifs de sécurité manuels
2. **Moyen terme** : Migrer vers Laravel 10 en résolvant les dépendances tierces
3. **Long terme** : Envisager Laravel 11 (sortie mars 2024) avec la nouvelle structure simplifiée