Upgrade Laravel App from PHP 8.2 to 8.3 without Downtime

Hey, Laravel developers! Upgrading your Laravel application from PHP 8.2 to PHP 8.3 is a crucial step to leverage new features, performance improvements, and security updates. But how do you ensure this upgrade happens without downtime, especially for a live application? I’ve been through this process and know the importance of keeping your app running smoothly.

In this guide, I’ll walk you through a step-by-step approach to upgrade your Laravel app (compatible with Laravel 12) to PHP 8.3, using a zero-downtime deployment strategy.

With practical code snippets and tips, you’ll master this upgrade with confidence.

Why Upgrade to PHP 8.3?

PHP 8.3 introduces features like typed class constants, dynamic class constant fetching, and improved error handling, making it a worthwhile upgrade for Laravel applications. Benefits include:

  1. Performance: Faster execution with JIT enhancements.
  2. Security: Latest patches and deprecated feature removals.
  3. Compatibility: Ensures Laravel 12 and third-party packages stay supported.
  4. Developer Experience: New syntax for cleaner code.

Prerequisites

Before starting, ensure:

  1. Laravel app running on PHP 8.2 (Laravel 10, 11, or 12).
  2. Access to a staging environment for testing.
  3. Git for version control.
  4. Composer installed (fix “‘composer’ is not recognized”).
  5. Server with SSH access and a web server (e.g., Nginx).
  6. Backup of your database and codebase.
  7. Terminal access (Command Prompt, PowerShell, or WSL2 on Windows).

Step-by-Step Guide: Upgrade Laravel App to PHP 8.3 without Downtime

Upgrade Laravel App from PHP 8.2 to 8.3 without Downtime

This guide assumes a Laravel 12 app and uses a blue-green deployment strategy to achieve zero downtime. We’ll test in a staging environment, update dependencies, and deploy seamlessly.

Step 1: Set Up a Staging Environment

Clone Your Repository:

git clone <your-repo-url> staging-app
cd staging-app

Install Dependencies:

composer install

If you encounter “‘composer’ is not recognized,” add Composer to PATH:

Add C:\Users\<YourUsername>\AppData\Roaming\Composer\vendor\bin to System PATH (see your previous article).

Verify: composer --version.

Configure Environment:
Copy .env from production (update database credentials for staging):

cp .env.example .env

Generate app key:

php artisan key:generate

Run Migrations:

php artisan migrate --force

Test Staging:
Start the server:

php artisan serve

Verify the app works at http://localhost:8000.

 

Step 2: Update PHP to 8.3 in Staging

Install PHP 8.3 (Ubuntu example; adjust for your OS):

sudo apt update
sudo add-apt-repository ppa:ondrej/php -y
sudo apt install php8.3 php8.3-cli php8.3-fpm php8.3-mysql php8.3-curl php8.3-xml php8.3-mbstring php8.3-zip

For Windows, download PHP 8.3 from php.net and update PATH.

Verify PHP Version:

php -v

Expected output:

PHP 8.3.0 (cli) (built: Nov 21 2023 14:15:30)

Update Nginx (if applicable):
Edit /etc/nginx/sites-available/your-site to use PHP 8.3 FPM:

fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;

Restart Nginx:

sudo service nginx restart

 

Step 3: Update Composer Dependencies

Update composer.json:
Modify composer.json to support PHP 8.3:

"require": {
    "php": "^8.3",
    "laravel/framework": "^12.0"
}

Check third-party packages for PHP 8.3 compatibility (e.g., laravel/passport, spatie/laravel-ignition).

Run Composer Update:

composer update

If errors occur, check package compatibility on Packagist or GitHub. Remove problematic dependencies temporarily and add back one-by-one:

composer require package-name --with-all-dependencies

Clear Caches:

php artisan cache:clear
php artisan config:cache
php artisan route:cache
php artisan view:clear

Test Application:
Run tests:

php artisan test

Manually test critical features (e.g., authentication, API endpoints).

 

Step 4: Prepare for Zero-Downtime Deployment

Use a blue-green deployment to switch between two environments without downtime. Here’s a simplified script for a Linux server.

Set Up Directory Structure:
On your production server:

mkdir -p /opt/laravel/releases
mkdir -p /opt/laravel/storage

Create Deployment Script (deploy.sh):

#!/bin/bash
set -e
TAG=$1
GIT_REMOTE_URL='your-repo-url'
BASE_DIR=/opt/laravel
RELEASE_DIR=$BASE_DIR/releases/$TAG
NGINX_DIR=/var/www/public

# Create release directory
mkdir -p $RELEASE_DIR
mkdir -p $BASE_DIR/storage
cd $RELEASE_DIR

# Fetch code
git clone $GIT_REMOTE_URL .
git checkout $TAG

# Install dependencies
composer install -o --no-interaction --no-dev

# Link storage and .env
ln -sf $BASE_DIR/.env .
rm -rf storage && ln -sf $BASE_DIR/storage .

# Run migrations
php artisan migrate --force --no-interaction

# Optimize
php artisan optimize
php artisan cache:clear
php artisan route:cache
php artisan view:clear
php artisan config:cache

# Update symlink
rm -f $NGINX_DIR/laravel
ln -sf $RELEASE_DIR $NGINX_DIR/laravel

Save as deploy.sh and make executable:

chmod +x deploy.sh

Tag Your Release:
In your staging repo:

git tag v1.0.3
git push origin v1.0.3

 

Step 5: Deploy to Production

Backup Production:

Backup database: mysqldump -u user -p database > backup.sql.

Backup codebase: tar -czf backup.tar.gz /var/www/laravel.

Run Deployment:
Copy deploy.sh to the server and execute:

./deploy.sh v1.0.3

This creates a new release directory, installs dependencies, runs migrations, and updates the symlink to switch traffic instantly.

Verify Deployment:
Check your app’s URL (e.g., https://your-app.com).
Monitor logs:

tail -f storage/logs/laravel.log

Rollback (if needed):
If issues occur, switch the symlink back:

ln -sf /opt/laravel/releases/previous-release /var/www/public/laravel

 

Step 6: Post-Deployment Checks
  1. Test Critical Features: Verify authentication (e.g., Laravel Passport), APIs, and forms.
  2. Monitor Performance: Use tools like New Relic to check for regressions.
  3. Update CI/CD: Adjust pipelines (e.g., GitHub Actions) to use PHP 8.3.

 

Best Practices for Zero-Downtime Upgrades

  • Test Thoroughly: Always test in staging first.
  • Automate Deployments: Use tools like Envoyer or Laravel Vapor for streamlined deployments.
  • Monitor Logs: Enable logging to catch errors early.
  • Incremental Updates: Update packages one-by-one to isolate issues.
  • Backup Regularly: Automate backups before deployments.
  • Leverage Authentication: Secure your app with Laravel 12 authentication.

 

Troubleshooting Common Issues

  • “‘composer’ is not recognized”: Add Composer to PATH.
  • Dependency Errors: Check Packagist for PHP 8.3-compatible versions. Run composer update -vvv for verbose output.
  • Migration Failures: Ensure database schema is compatible. Test migrations in staging.
  • Nginx Errors: Verify PHP 8.3 FPM path in Nginx config.

 

Conclusion

Upgrading your Laravel app from PHP 8.2 to 8.3 without downtime is achievable with a blue-green deployment strategy. By testing in staging, updating dependencies, and using a scripted deployment, you ensure a seamless transition.

This guide, tailored for Laravel 12, leverages PHP 8.3’s benefits. Apply these steps, and your app will run faster, safer, and without interruption. Start your upgrade today, and keep your Laravel app at its best!

Frequently Asked Questions(FAQs)

Q1: Why upgrade to PHP 8.3 for Laravel?
A: PHP 8.3 offers performance, security, and new features like typed constants, ensuring compatibility with Laravel 12.

Q2: How do I achieve zero downtime during deployment?
A: Use blue-green deployment to switch between release directories via symlinks, keeping the app live.

Q3: What if Composer fails during the upgrade?
A: Ensure Composer is in PATH and check package compatibility. Run composer update -vvv for details.

Q4: Can I rollback if the upgrade fails?
A: Yes, switch the symlink to the previous release directory to revert instantly.

Q5: How do I test my Laravel app after upgrading?
A: Run php artisan test, verify authentication (e.g., Passport), and test critical features manually.

 


You might also like:

techsolutionstuff

Techsolutionstuff | The Complete Guide

I'm a software engineer and the founder of techsolutionstuff.com. Hailing from India, I craft articles, tutorials, tricks, and tips to aid developers. Explore Laravel, PHP, MySQL, jQuery, Bootstrap, Node.js, Vue.js, and AngularJS in our tech stack.

RECOMMENDED POSTS

FEATURE POSTS