The latest update for Invoice Ninja v5 now requires PHP version 8.1 be installed to support new features, changes to the Laravel coding style and many other enhancements.
More on this release here at https://github.com/invoiceninja/invoiceninja/releases/tag/v5.5.0
As of the writing of this post, the current release for Invoice Ninja v5 is v5.5.1 and is available to update from the Invoice Ninja web dashboard for self-hosted instances.
This upgrade\update process is based on my production Invoice Ninja v5 build guide here on the LTS forums at https://staging-forum.lawrencesystems.com/t/invoice-ninja-v5-new-server-build/10081
For continuity of understanding, I need to define the environment, current build level and installed dependencies to clarify any questions on the OS or the LAMP stack. If you are using another OS, web server (NGINX, etc.,) or PHP version other then 8.0, you will need to adjust commands accordingly.
Environment:
Invoice Ninja self hosted version 5 (v5.4.9)
Instance Type: Dedicated virtual machine with dedicated instance resources running on XCP-ng v8.2.1 (current patch level)
Operating System: Debian 10 Buster (current patch level)
Dependencies
- PHP - Version 8.0 (current patch level)
- Apache 2 - Version 2.4.52 (Debian) (current patch level)
- MariaDB - Verion 15.1 Distrib 10.3.34-MariaDB, for debian-linux-gnu (current patch level)
Updating Invoice Ninja
Backup Warning: If you have not already done so, now is the time backup your instance before the update and upgrade as things will break due to the PHP v8.1 requirement.
From the Invoice Ninja web console, initiate the self-update. It will take a min or two to complete. My update took almost 2 mins to complete. As part of the Invoice Ninja update process, we always run the PHP artisan optimize from the terminal. When we run it this time we get an error messages
Error message 1 displayed during upgrade from Invoice Ninja web console
FormatException: SyntaxError: Unexpected end of JSON input
Error message 2 displayed during upgrade from Invoice Ninja web console
FormatException: SyntaxError: Unexpected token C in JSON at position 0
Error from the terminal when running artisan optimize (SSH from linux shown)
┌─[xxxxx@xxxxx]─[/var/www/html/invoiceninja]
└──╼ $sudo -u www-data php artisan optimize
Composer detected issues in your platform:
Your Composer dependencies require a PHP version ">= 8.1.0". You are running 8.0.21.
PHP Fatal error: Composer detected issues in your platform: Your Composer dependencies require
a PHP version ">= 8.1.0". You are running 8.0.21. in
/var/www/html/invoiceninja/vendor/composer/platform_check.php on line 24
Also when trying to open Invoice Ninja from a web browser we get a related error message
Composer detected issues in your platform: Your Composer dependencies require a PHP version ">= 8.1.0".
Upgrading PHP to version 8.1
Make sure the APT package manager is up to date
sudo apt update
Then we want to get a list of the currently installed PHP version and related installed PHP extensions. Finding the PHP version is easy using this command
php -v
The PHP version will be displayed, alternately the version of PHP can be determined from the web console before the update by going to About >> Health Check
From the terminal we need to also display all the related PHP extensions installed as they will need to be upgraded too. For this we use grep and sed with arguments to output the precise info we want as the output will be used to uninstall the older version of PHP later.
NOTE: Your output may vary from whats listed in the next steps, depending if there were additional PHP extensions installed for your instance and is why we are using this method to list all of the related items with your individual installation.
sudo dpkg -l | grep php8.0 | cut -f3 -d' ' | xargs | sed 's/8.0/8.0/g'
The output I got was
libapache2-mod-php8.0 php8.0-bcmath php8.0-cli php8.0-common php8.0-curl php8.0-fpm php8.0-gd php8.0-gmp php8.0-mbstring php8.0-mysql php8.0-opcache php8.0-readline php8.0-xml php8.0-zip
Copy this output into textpad as it will be used later to build the command to uninstall the older PHP version and related extensions
Saving the Current PHP Configuration
Next we need to look at the configuration of the current php.ini before the upgrade. To do this, use the editor from the terminal. As nano is installed by default and the installed version of PHP is v8, I want to look there.
NOTE: If using an earlier version of PHP (ex: php v 7.4) you will need to adjust the command below accordingly
sudo nano /etc/php/8.0/apache2/php.ini
The things I look for are:
upload_max_filesize = 256M
post_max_size = 8M
memory_limit = 256M
max_execution_time = 360
max_input_vars = 1000
max_input_time = 60
NOTE: If using nano the ^W is search function used within the editor. Copy the values for each of these settings as they will most likely need to be adjusted after upgrading PHP to version 8.1. Close the editor when completed
Installing PHP version 8.1 and related PHP extensions
To install PHP v8.1 we are going to use the command called earlier to output the php extensions but modify it to output the same extensions with the updated version.
NOTE: If using an earlier version of PHP (ex: php v 7.4) you will need to adjust the command below accordingly
sudo dpkg -l | grep php8.0 | cut -f3 -d' ' | xargs | sed 's/8.0/8.1/g'
The output was
libapache2-mod-php8.1 php8.1 php8.1-bcmath php8.1-cli php8.1-common php8.1-curl php8.1-fpm php8.1-gd php8.1-gmp php8.1-mbstring php8.1-mysql php8.1-opcache php8.1-readline php8.1-xml php8.1-zip
Again copy this out to textpad and add sudo apt install php8.1 php8.1-common to the output from earlier to build the install command
sudo apt install php8.1 php8.1-common libapache2-mod-php8.1 php8.1 php8.1-bcmath php8.1-cli php8.1-common php8.1-curl php8.1-fpm php8.1-gd php8.1-gmp php8.1-mbstring php8.1-mysql php8.1-opcache php8.1-readline php8.1-xml php8.1-zip
This will install the PHP 8.1 and necessary v8.1 PHP extensions. Next we need to disable the old version of PHP, enable PHP 8.1 and uninstall the old PHP version and old extensions
NOTE: The Following commands are Apache 2 specific, if using NGINX or something else, you will need to use the equivalent commands
You may get errors related to mpm_event or mpm_prefork, these can be ignored for now or disabled with the following command. (Command is Apache 2 specific)
sudo a2dismod mpm_event
Disable the old version of PHP with
a2dismod php8.0
Enable the new version of PHP with
a2enmod php8.1
Adjust php.ini to use the configuration info from the previous php.ini.
Again ^W search function in the nano editor is your friend to find the items that need adjustment
sudo nano /etc/php/8.1/apache2/php.ini
upload_max_filesize = 256M
post_max_size = 8M
memory_limit = 256M
max_execution_time = 360
;max_input_vars = 1000
max_input_time = 60
Uninstall PHP v8.0 and the Related Extensions
Remove the old version of PHP using the output generated earlier in the process listing (this example is PHP version 8.0)
sudo apt purge php8.0 libapache2-mod-php8.0 php8.0-bcmath php8.0-cli php8.0-common php8.0-curl php8.0-fpm php8.0-gd php8.0-gmp php8.0-mbstring php8.0-mysql php8.0-opcache php8.0-readline php8.0-xml php8.0-zip
Restart Apache 2
sudo systemctl restart apache2
There should be no errors, if there are, the configuration will need to be adjusted here before Apache will run again.
Optimize Invoice Ninja (done from the web install directory)
cd /var/www/html/invoiceninja
Then
sudo -u www-data php artisan optimize
If all goes well you will get a new response from the artisan optimize command
From the web browser, open a tab as any instances open may contain stale data (F5 “hard refresh” may not help)
Navigating to the About >> Health Check will show the updated version of PHP also