Server : Apache System : Linux 145.162.205.92.host.secureserver.net 5.14.0-611.45.1.el9_7.x86_64 #1 SMP PREEMPT_DYNAMIC Wed Apr 1 05:56:53 EDT 2026 x86_64 User : tradze ( 1001) PHP Version : 8.1.34 Disable Function : NONE Directory : /home/tradze/www/dev-test/ |
# Laravel 8 Upgrade Guide
This project has been updated from Laravel 5.5 to Laravel 8. Below are the changes made and the steps you need to complete.
## Summary of changes
### 1. Composer & framework
- **Laravel** 5.5 → 8.x
- **PHP** requirement: ^7.3|^8.0
- **Packages updated or replaced:**
- **bican/roles** → **spatie/laravel-permission** (roles/permissions)
- **caffeinated/modules** & **caffeinated/menus** → custom module loader + **lavary/laravel-menu**
- **laravelcollective/html** ^6.2, **yajra/laravel-datatables-oracle** ^9.0, **laravel/socialite** ^5.0
- **laracasts/flash** ^3.0, **darryldecode/cart** ^4.2, **maatwebsite/excel** ^3.1
- **cviebrock/eloquent-sluggable** ^8.0, **intervention/image** ^2.7, **barryvdh/laravel-dompdf** ^1.0
- **braintree/braintree_php** ^6.0, **fideloper/proxy** ^4.4, **laravel/tinker** ^2.0
- **Removed** (no Laravel 8 support): **alexpechkarev/google-maps**, **alexpechkarev/postcode-anywhere**. You will need to replace these with alternatives (e.g. Google Maps API client, a postcode lookup package) and update any code using `GoogleMaps` and `PA` facades.
### 2. Routes
- **app/Http/routes.php** → **routes/web.php** (and **routes/api.php**).
- **Route::auth()** replaced with explicit login, logout, register, password reset routes.
- Module routes are loaded from **app/Modules/*/Http/routes.php** in `RouteServiceProvider::mapModuleRoutes()`.
### 3. Module system
- **Caffeinated Modules** removed. A custom loader is in place:
- **App\Providers\ModulesServiceProvider** discovers and registers module service providers.
- **App\Facades\Module** and **App\Services\ModuleService** provide `Module::isEnabled('name')` for compatibility.
- Each module’s main `*ServiceProvider` now extends `Illuminate\Support\ServiceProvider`; route registration is handled centrally (no per-module `RouteServiceProvider` registration).
### 4. Roles & permissions
- **Bican Roles** replaced with **Spatie Laravel Permission**.
- **User** model uses `Spatie\Permission\Traits\HasRoles` and a compatibility method `is($role)` (equivalent to `hasRole($role)`).
- All `Bican\Roles\Models\Role` usages replaced with `Spatie\Permission\Models\Role`.
- Route middleware `role`, `permission` now use Spatie’s middleware.
### 5. Kernel & middleware
- Global middleware: TrustProxies, PreventRequestsDuringMaintenance, TrimStrings, etc.
- **EncryptCookies** and **VerifyCsrfToken** base classes updated to Laravel 8 style.
- **AdminMenuMiddleware** uses **App\Facades\Module** and **Lavary\Menu\Facade**.
### 6. Exception handler
- **Handler** updated to type-hint **Throwable** and use Laravel 8 exception handling (e.g. `unauthenticated`).
### 7. Config
- **config/app.php**: Caffeinated and Bican providers/aliases removed; Spatie, ModulesServiceProvider, Lavary Menu and **Module** facade added. **Yajra** provider set to `Yajra\DataTables\DataTablesServiceProvider` (DataTables 9.x). Removed **log** key (logging is configured elsewhere in L8).
- **config/roles.php** is obsolete; Spatie uses **config/permission.php** after you publish it.
---
## Steps you must run (ask before running critical commands)
### 1. Backup and PHP version
- Backup the project and database.
- Ensure PHP is **7.3+** or **8.x**:
`php -v`
### 2. Install dependencies (critical – run only after you confirm)
From the project root:
```bash
composer update
```
If you see conflicts, try:
```bash
composer update --with-all-dependencies
```
**Do not run this until you are ready;** it will change `composer.lock` and vendor.
### 3. Publish Spatie permission config and migrations
After a successful `composer update`:
```bash
php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider"
```
This creates **config/permission.php** and migrations for Spatie’s tables.
### 4. Migrate from Bican to Spatie (roles/permissions)
Spatie uses different tables than Bican. You have two options:
**Option A – Fresh Spatie tables and reseed**
- Run Spatie migrations:
`php artisan migrate`
- Create roles (e.g. `developer`, `salon`, `therapist`, `customer`) and assign them to users in a seeder or tinker, using Spatie’s API (`Role::create()`, `$user->assignRole()`).
**Option B – Data migration from Bican**
- Keep Bican tables (e.g. `roles`, `role_user`) until you have a migration script that:
- Creates Spatie roles/permissions and fills `model_has_roles` from your current `role_user` (and similarly for permissions if you use them).
- Then run Spatie migrations and your migration script, and later drop old Bican tables.
### 5. Clear caches and regenerate autoload
```bash
composer dump-autoload
php artisan config:clear
php artisan route:clear
php artisan view:clear
php artisan cache:clear
```
### 6. Environment and config
- Ensure **.env** has `APP_KEY` set.
- If you use queues, broadcasting, or caching, check **config/queue.php**, **config/broadcasting.php**, **config/cache.php** for L8 changes.
### 7. Auth controller traits
- The main **App\Http\Controllers\Auth\AuthController** now uses **Illuminate\Foundation\Auth\AuthenticatesUsers** and **RegistersUsers** (Laravel 8) and defines **getLogin**, **getRegister**, **getLogout** for your existing routes.
- If **App\Modules\Users\Http\Controllers\Admin\AuthController** or **ApiRegisterController** still use **ThrottlesLogins** or **AuthenticatesAndRegistersUsers**, update them similarly or add the same compatibility methods.
### 8. Optional: Google Maps & Postcode
- Code that used **GoogleMaps** and **PA** (PostcodeAnywhere) will break until you:
- Install Laravel 8–compatible packages (or use HTTP clients directly), and
- Update controllers/services that used those facades.
### 9. Testing
- Run the application (e.g. `php artisan serve`) and test login, roles (`hasRole`, `is()`), and permission checks.
- Test modules that use `Module::isEnabled()` and the admin menu (Lavary Menu).
- Fix any remaining references to old packages (e.g. Bican, Caffeinated) or missing facades (GoogleMaps, PA).
---
## If you want to run critical commands
Before running **composer update** or **php artisan migrate** (or any command that changes dependencies or the database), say so and we can:
- Run **composer update** only after you confirm.
- Draft or adjust a migration script from Bican to Spatie if you choose Option B.
- Skip or delay migrations and only run non-destructive commands (e.g. **config:clear**, **route:clear**).
Tell me which command you want to run and I’ll execute it only after you confirm.