Upgrade to PHP 8.1

# Estimated Upgrade Time: 1.5 Hours

We attempt to make the shift from PHP 7.2 to PHP 8.1 as simple as possible. Some services have undergone significant changes as a result of third-party API providers. We have compiled a list of all services that have experienced noticeable changes, which you can find below. While it’s not necessary to update all of these services, if you are using any of them, we recommend that you review the relevant section to expedite the development of your dream API.

Switch to PHP 8.1

This section will demonstrate an example of how to migrate from PHP 7.4 to PHP 8.1 on Ubuntu 20.04.

First, we need to add PPA:

sudo add-apt-repository ppa:ondrej/php -y

Then install PHP 8.1 and the required dependencies:

sudo apt-get install -y php8.1-common \
php8.1-xml \
php8.1-cli \
php8.1-fpm \
php8.1-curl \
php8.1-mysqlnd \
php8.1-sqlite \
php8.1-soap \
php8.1-mbstring \
php8.1-zip \
php8.1-bcmath \
php8.1-dev \
php8.1-ldap \
php8.1-pgsql \
php8.1-interbase \
php8.1-gd \
php8.1-sybase

After successful installation we need to manually switch to PHP 8.1:

sudo update-alternatives --set php /usr/bin/php8.1 \
sudo update-alternatives --set phar /usr/bin/phar8.1 \
sudo update-alternatives --set phar.phar /usr/bin/phar.phar8.1 \

Then select the version of PHP you need by using:

sudo update-alternatives --config php

Configure NGINX

If you are using FastCGI Process Manager (FPM) with NGINX or Apache, you will need to update your DreamFactory installation’s host configuration. To update the configuration for NGINX, you will need to modify the version of PHP specified in the Nginx server configuration file, which can be located at /etc/nginx/sites-available/default.

-fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;
+fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;

Now we want to update our DreamFactory instance to the latest version. Use git pull command from the DreamFactory root directory. After that run the composer install command. Finally restart fpm and nginx:

sudo service php8.1-fpm restart && service nginx restart

Table of contents

Free Plan

Cassandra

Likelihood Of Impact: High

To use the Cassandra service, you need to recompile the driver and install the client library if you haven’t already.

Download and extract the client library for Apache Cassandra. From the downloaded repository, run the following commands:

sudo apt install -y --no-install-recommends libgmp-dev libpcre3-dev libssl-dev libuv1-dev cmake

mkdir build       &&\
pushd build       &&\
cmake ..          &&\
make              &&\
sudo make install &&\
popd

Download the DataStax PHP Driver for Apache Cassandra. Make sure that you are on the 1.3.x branch. From the downloaded repository, run the following command:

# Currently, we are using a specific version of the repository that is still functional, 
# as the recent efforts to enhance the installation process do not work properly.
git checkout 1cf12c5ce49ed43a2c449bee4b7b23ce02a37bf0 &&\
pushd ext         &&\
phpize            &&\
popd              &&\
mkdir build       &&\
pushd build       &&\
../ext/configure  &&\
make              &&\
sudo make install &&\
popd

Make sure cassandra.so is built.

find /usr/lib/php/20210902/cassandra.so

If cassandra.so exists, connect it to PHP’s modules.

echo 'extension=cassandra.so' | sudo tee /etc/php/8.1/mods-available/cassandra.ini
sudo phpenmod -v 8.1 -s ALL cassandra

Couchbase

Likelihood Of Impact: High

With the new release of DreamFactory, we removed the Couchbase from the list of supported services. There is a possibility that support for Couchbase may be reinstated in future releases.

Email

Likelihood Of Impact: Low

The Mandrill & SparkPost mail drivers have been removed from Laravel 6. These services are technically not been supported by DreamFactory since its migration to Laravel 6. From now on, these services will no longer be displayed in the “Services” tab.

Firebird

Likelihood Of Impact: High

If you are using Firebird with major version 3, then it must be at least version 3.0.4. This is due to usage of the LOCALTIMESTAMP parameter.

To use the Firebird service, you need to install/recompile a driver compatible with PHP 8.1. Use --with-pdo-firebird to install the PDO Firebird extension or install php81-interbase package from ppa:ondrej/php.

GitHub

Likelihood Of Impact: Medium

DreamFactory provided the ability to authenticate through the REST API using an account password or personal access token to perform authenticated API operations on GitHub.com. Beginning November 13th, 2020, GitHub announced that they will no longer accept account passwords when authenticating via the REST API and will require the use of token-based authentication. So if you have a registered DreamFactory GitHub service, ensure to specify a personal access token. For more information, please follow the link.

Mongo logs

Likelihood Of Impact: Low

DreamFactory supports a very simple solution for logging all requests. All records requested in the API will be written to the database. The implication is that DreamFactory relies on MongoDB PHP driver. You can easily install the required dependency with pecl. After that run this two commands:

echo 'extension=mongodb.so' | sudo tee /etc/php/8.1/mods-available/mongodb.ini
sudo phpenmod -s ALL mongodb

Apache Hive

Likelihood Of Impact: High

In order to use the service, you will need to have both the PDO and ODBC PHP extensions installed, which are available for download from this PPA with the names php8.1-pdo and php8.1-odbc, respectively. Additionally, the MapR ODBC Driver must be installed, which you can obtain by downloading from this link or through the Amazon cloud, as we do. To install MapR ODBC Driver run:

cd /opt \
&& sudo curl --fail -O https://odbc-drivers.s3.amazonaws.com/apache-hive/maprhiveodbc_2.6.1.1001-2_amd64.deb \
&& sudo dpkg -i maprhiveodbc_2.6.1.1001-2_amd64.deb \
&& test -f /opt/mapr/hiveodbc/lib/64/libmaprhiveodbc64.so \
&& rm maprhiveodbc_2.6.1.1001-2_amd64.deb

Please note that it’s crucial to install the extension using a specific path. So the full path to the driver must be - /opt/mapr/hiveodbc/lib/64/libmaprhiveodbc64.so

Azure Active Directory

Likelihood Of Impact: Low

Microsoft announced that Azure AD Graph will continue to function until June 30, 2023. Based on that we migrated towards Microsoft Graph. For more information, please follow the link.

IBM Db2

Likelihood Of Impact: High

DreamFactory services that work with IBM databases use software that can be loaded from ibm.com. This section is appointed for a self-hosted environment. To make DreamFactory work with the IBM Db2, you need to take the following steps:

Sign in to your IBM account or create a new one. Download the client driver package:

https://epwt-www.mybluemix.net/software/support/trial/cst/programwebsite.wss?siteId=853&h=null&p=null

Extract the downloaded file. From the “dsdriver” subdirectory, generate “db2profile” and “db2cshrc” script files:

sudo -s \
&& tar -xvf ibm_data_server_driver_package_linuxx64_v11.5.tar.gz -C /opt/ \
&& cd /opt/dsdriver \
&& apt install -y ksh \
&& ./installDSDriver

Sets the environment variables:

source db2profile (for the Bash or Korn shell)
source db2cshrc (for the C shell)

Clone the PDO_IBM source code from GitHub. Please note that this must be done from the same terminal since db2profile | db2cshrc sets the environment variables in the current terminal session.

git clone https://github.com/php/pecl-database-pdo_ibm /opt/PDO_IBM && \
cd /opt/PDO_IBM

From the cloned repository run:

export CPATH=/opt/dsdriver/include

phpize \
&& ./configure --with-pdo-ibm=/opt/dsdriver \
&& make \
&& make install \
&& exit

Check for the presence of pdo_ibm.so:

find "/usr/lib/php/20210902/pdo_ibm.so"

If pdo_ibm.so exists, connect it to PHP’s modules.

echo 'extension=pdo_ibm.so' | sudo tee /etc/php/8.1/mods-available/pdo_ibm.ini && \
sudo phpenmod -v 8.1 -s ALL pdo_ibm

IBM Informix

Likelihood Of Impact: High

DreamFactory services that work with IBM databases use software that can be loaded from ibm.com. This section is appointed for a self-hosted environment. To make DreamFactory work with the IBM Informix, you need to take the following steps:

Sign in to your IBM account or create a new one. Download the Informix Client SDK.

Download Informix Client SDK ➜ IBM Informix Client SDK downloads ➜ Fill out the form ➜ Select appropriate version ➜ Download tar file

SDK may require to install libncurses.so.5.

sudo add-apt-repository universe
sudo apt update
sudo apt install libncurses5 libncurses5:i386

Extract and install the SDK.

sudo -s
tar -xvf your_archive
./installclientsdk

Now we have two options to install pdo_informix.so: using pecl or building it manually. We prefer the second method since we didn’t succeed with pecl.

Download the PDO_INFORMIX archive and extract it. From extracted PDO_INFORMIX-1.3.x folder run:

phpize \
&& ./configure --with-pdo-informix=/opt/IBM/Informix_Client-SDK \
&& make \
&& make install \
&& exit

If you decide to test your luck, and install PDO_INFORMIX using pecl:

sudo pecl install PDO_INFORMIX

Set the environment variables in .profile. Open the file for editing with:

sudo nano ~/.profile

Add the following lines to the bottom of the file.

export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:/opt/IBM/Informix_Client-SDK/lib:/opt/IBM/Informix_Client-SDK/lib/esql" 
export INFORMIXDIR="/opt/IBM/Informix_Client-SDK"

Make sure pdo_informix.so is built.

find /usr/lib/php/20210902/pdo_informix.so

If pdo_informix.so exists, connect it to PHP’s modules.

echo 'extension=pdo_informix.so' | sudo tee /etc/php/8.1/mods-available/pdo_informix.ini && \
sudo phpenmod -v 8.1 -s ALL pdo_informix

LDAP & Active Directory

Likelihood Of Impact: Low

DreamFactory uses Lightweight Directory Access Protocol to lookup information or devices within a network. Therefore, to continue working with these services, you need to install the LDAP extension for the new version of PHP. For a quick setup, see the ‘Installing the PHP extension’ section.

MQTT

Likelihood Of Impact: Low

Previously, the MQTT service relied on the Mosquitto-PHP extension, which in turn relies upon the libmosquitto library. From now on, this service no longer depends on the system’s needs and contains everything you need to work in itself.

Oracle

Likelihood Of Impact: High

To use the Oracle service, you need to install the new version of the oci8 extension compatible with PHP 8.1. You can seamlessly install the required extension version you need via pecl. But before installation, you need to go through a few more steps:

Download the desired Instant Client and the corresponding SDK Package. We will show the example of RPM packages.

https://www.oracle.com/database/technologies/instant-client/downloads.html

Install the necessary dependencies.

sudo apt install -y alien libaio1

Install the Oracle client packages. This may take a few minutes.

sudo alien -i oracle-instantclient-basic-21.9.0.0.0-1.el8.x86_64.rpm
sudo alien -i oracle-instantclient-devel-21.9.0.0.0-1.el8.x86_64.rpm

Now we are good to install the oci8 extension. The latest version is compatible with PHP 8.1 at present, but you may need to specify the version explicitly.

sudo pecl install oci8 (php 8.1 exactly what we need)
sudo pecl install oci8-2.2.0 (php 7)

Once complete, make sure that OCI is loaded:

php -m | grep oci8

#oci8

If you do not see oci8 in PHP’s modules, ensure that the configuration file and the OCI shared library file are plugged in.

Check for the presence of osi8.so:

find "/usr/lib/php/20210902/oci8.so"

If osi8.so exists, connect it to PHP’s modules.

echo 'extension=oci8.so' | sudo tee /etc/php/8.1/mods-available/oci8.ini && \
sudo phpenmod -v 8.1 -s ALL oci8

SAP SQL Anywhere

Likelihood Of Impact: High

All you need is to install the Sybase module from PPA. See how to add PPA to your Apt repositories. This package provides php8.1-pdo-dblib, which is what we need.

sudo apt install php8.1-sybase

Once complete, make sure that the driver is installed successfully. Confirm both PDO and the pdo_dblib extensions are present:

php -m
...
#PDO
#pdo_dblib
...

Snowflake

Likelihood Of Impact: High

To use the Snowflake service, you need to recompile the pdo_snowflake driver using the new PHP version. After completion, make sure the module is installed into the proper extensions directory. See official guide: https://github.com/snowflakedb/pdo_snowflake

Microsoft SQL Server

Likelihood Of Impact: High

To use a Microsoft SQL Server database, you should ensure that you have the sqlsrv and pdo_sqlsrv PHP extensions installed as well as any dependencies they may require such as the Microsoft SQL ODBC driver.

Install ODBC libraries for UNIX from the Microsoft repository.

sudo apt install -y unixodbc-dev

If you are encountering issues with the unixodbc-dev package, it may be due to a recent release. As a workaround, you can lock the package version to a stable one (e.g. v2.3.7) until a fix is released. For more details, refer to the relevant issue.

Install sqlsrv and pdo_sqlsrv from pecl.

sudo pecl install sqlsrv
sudo pecl install pdo_sqlsrv

Check for the presence of sqlsrv and pdo_sqlsrv:

find "/usr/lib/php/20210902/sqlsrv.so"
find "/usr/lib/php/20210902/pdo_sqlsrv.so"

If we get both SO files, connect it to PHP’s modules.

echo 'extension=sqlsrv.so' | sudo tee /etc/php/8.1/mods-available/sqlsrv.ini
sudo phpenmod -v 8.1 -s ALL sqlsrv

echo 'extension=pdo_sqlsrv.so' | sudo tee /etc/php/8.1/mods-available/pdo_sqlsrv.ini
sudo phpenmod -v 8.1 -s ALL pdo_sqlsrv

Finally, install the Microsoft ODBC driver for SQL Server following the official guide, or using the Microsoft repository.

Installing the PHP extension

Installation of the necessary dependencies can be quite an agonizing process, so concerned people make this process as painless as possible. Ondřej Surý maintains the repository with PHP packages and is a very well-respected contributor to the PHP community. See how you can install the required PHP dependencies in three easy steps.

First add ppa:ondrej/php to our APT repositories.

sudo add-apt-repository ppa:ondrej/php

Update list of available packages.

sudo apt update

Install the required dependency. In this example, we will demonstrate the installation of LDAP extension.

sudo apt install php8.1-ldap

Last modified February 22, 2023: DP-460 Upgrade to PHP 8.1 / Laravel 9 (dc236d8)