Securing your code is a journey, not just a destination.
Keeping projects up-to-date with the latest features and security patches is essential for maintaining performance and safeguarding against vulnerabilities. As technology evolves, so do the threats that target our codebases. Therefore, upgrading the framework and library used in our project to the latest versions becomes more than just a routine task; it becomes a critical aspect of our ongoing commitment to code security.
This post is not intended to be a comprehensive tutorial as there are already many resources available for that purpose. Rather, it serves as a personal log of the challenges I encountered during the upgrade of my Laravel applications for my own reference, with the hope of helping others overcome similar challenges.
Review Laravel Upgrade Guides
Laravel provides detailed upgrade guides and release notes for each version on their official documentation website. Review the upgrade guides relevant to your current version and the version you intend to upgrade to. Pay attention to any breaking changes or deprecated features.
Backup Your Codebase
Before making any changes, ensure you have a backup of your entire codebase. This includes your application code, configuration files, database, and any other relevant files. Use Git to create a new branch for the upgrade process:
git checkout -b upgrade-to-laravel-x.x
Update Laravel Dependencies
Update the following dependencies in your application's composer.json file. (Recommended)
"laravel/framework": "^10.0",
then run:
# Update all packages listed in composer.json to their latest compatible versions.
composer update
# Alternatively, update only the laravel/framework package along with its dependencies.
composer update laravel/framework --with-dependencies
Note: It's generally recommended to upgrade Laravel version by version, especially when upgrading from a major release (e.g., Laravel 8 to Laravel 9). This approach allows you to manage and address significant changes, breaking changes, or deprecations incrementally, reducing the risk of compatibility issues or unexpected behaviour.
Review Changes in Laravel/Laravel GitHub
Visit the Laravel/Laravel GitHub repository and navigate to the release notes or compare versions page (e.g., https://github.com/laravel/laravel/compare/9.x...10.x).
Pay attention to changes in configuration files, providers, and alterations in dependencies listed in package.json.
Upgrade Third-Party PHP/Laravel Packages
Additionally, ensure that all third-party packages and dependencies used in your application are compatible with the new Laravel version. Consult the documentation or repositories of these packages for information on compatibility. Review your application's codebase thoroughly to identify any deprecated or removed features, methods, or functions. Make the necessary adjustments to align your code with the latest Laravel conventions and practices.
Update JavaScript Packages
Next, turn your attention to updating npm JavaScript packages. Open your package.json file, and modify the version numbers of the desired packages to their latest compatible versions. Then, run the npm update command to apply the updates.
npm install vite@latest
npm install laravel-vite-plugin@latest
npm update
npm update antd antd-img-crop country-flag-icons
Test Your Application
After completing the package upgrades, thoroughly test your application to ensure that all functionalities remain intact. Pay close attention to any areas that were directly affected by the package upgrades, such as UI components or API integrations.
Resolve Dependency Conflicts
In some cases, upgrading npm packages may lead to dependency conflicts. Use tools like npm audit to identify and resolve any security vulnerabilities and follow npm's guidance to address dependency conflicts effectively.
Handling Compilation Errors with skipLibCheck
Occasionally, after upgrading the dependencies in our application's package.json, we encounter compilation errors in our code, specifically related to TypeScript errors in third-party libraries.
In such situations, we can utilise the skipLibCheck option in TypeScript's configuration. This option allows us to bypass type checking for declaration files (*.d.ts) in the node_modules directory during compilation, effectively suppressing errors originating from third-party libraries.
To implement this, simply add the following code to your tsconfig.json file, typically located at the root directory of your TypeScript project:
"compilerOptions": {
# ...
"skipLibCheck": true,
}
Resolving SSL Errors Upon Updating to Vite 5
After running npm run dev for my Laravel + Inertia application, I encountered a blank screen. Upon checking the browser console, I noticed my JavaScript file was blocked with the following failure message:
The connection for this site is not secure. my-app.test uses an unsupported protocol. ERR_SSL_VERSION_OR_CIPHER_MISMATCH
Referring to the Vite migration guide at vitejs.dev, I discovered that the outdated https settings in my vite.config.js were the root cause of the issue.
export default defineConfig({
plugins: [
laravel({
input: ['resources/css/app.css', 'resources/js/app.tsx'],
refresh: true,
detectTls: 'my-app.test',
}),
react()
],
server: {
// REMOVE this
// https: true
},
});
The guide recommended removing the https: true setting from my Vite configuration, as it will start a Vite HTTPS server without a certificate.
Monitor for Errors
Post-upgrade, monitor your application for any errors or unexpected behaviour. Utilize logging and monitoring tools to identify and address any issues promptly.