Brand

DataStax PHP Driver

Attention: Viewing documentation for version
Download

Building PHP Extension

The PHP driver is implemented as a native PHP extension and leverages the C/C++ driver. The driver will build on most standard Unix-like and Microsoft Windows platforms.

Packages are available for the following platforms:

NOTE: The build procedures only need to be performed for driver development or if your system doesn’t have packages available for download and installation.

Compatibility

  • PHP 5.6, PHP 7.0, and PHP 7.1
    • 32-bit (x86) and 64-bit (x64)
    • Thread safe (TS) and non-thread safe (NTS)
  • Compilers: GCC 4.1.2+, Clang 3.4+, and MSVC 2012/2015

Dependencies

The PHP Extension depends on the following software:

Linux/Mac OS

The driver is known to build on CentOS/RHEL 6/7, Mac OS X 10.10/10.11 (Yosemite and El Capitan), Mac OS 10.12 (Sierra), and Ubuntu 14.04/16.04 LTS.

NOTE: The driver will also build on most standard Unix-like systems using GCC 4.1.2+ or Clang 3.4+.

Installing dependencies

Initial environment setup

CentOS/RHEL 6 (Yum)

CentOS/RHEL 6 ships with PHP v5.3.x as the default version of PHP; which is not supported. A supported version of PHP can be installed by performing the following:

yum install epel-release
rpm -Uvh https://mirror.webtatic.com/yum/el6/latest.rpm

Once completed PHP v5.6.x, v7.0.x, or v7.1.x can be installed:

yum install automake cmake gcc-c++ git libtool pcre-devel php71w-devel php71w-pear
CentOS/RHEL 7 (Yum)

CentOS/RHEL 7 ships with PHP v5.4.x as the default version of PHP; which is not supported. A supported version of PHP can be installed by performing the following:

yum install epel-release
rpm -Uvh https://mirror.webtatic.com/yum/el7/latest.rpm

Once completed PHP v5.6.x, v7.0.x, or v7.1.x can be installed:

yum install automake cmake gcc-c++ git libtool pcre-devel php71w-devel php71w-pear
Ubuntu 14.04 (APT)

Ubuntu 14.04 LTS (Debian 8) ships with PHP v5.5.x as the default version of PHP; which is not supported. A supported version of PHP can be installed by performing the following:

add-apt-repository ppa:ondrej/php
apt-get update

Once completed PHP v5.6.x, v7.0.x, or v7.1.x can be installed:

apt-get install build-essential cmake git libpcre3-dev php7.1-dev
Ubuntu 16.04 (APT)

Starting with Ubuntu 16.04 LTS (Debian 9) PHP v5.5.x has been removed as the default version of PHP and has been replaced with either PHP v7.0.x or PHP v7.1.x:

apt-get install build-essential cmake git libpcre3-dev php7.1-dev
Mac OS (Brew) 
brew update
brew upgrade
brew tap homebrew/homebrew-php
brew install autoconf automake libtool php71 --with-pear

GNU Multiple Precision Arithmetic

CentOS/RHEL (Yum) 
yum install gmp-devel
Ubuntu (APT) 
apt-get install libgmp-dev
Mac OS (Brew) 
brew install gmp

libuv

libuv v1.x should be used in order to ensure all features of the C/C++ driver and the PHP driver are available. When using a package manager for your operating system make sure you install v1.x; if available.

CentOS/RHEL and Ubuntu packages

Packages are available from our download server:

Mac OS (Brew) 
brew install libuv
Manually build and install

The following procedures should be performed if packages are not available for your system.

pushd /tmp
wget http://dist.libuv.org/dist/v1.13.1/libuv-v1.13.1.tar.gz
tar xzf libuv-v1.13.1.tar.gz
pushd libuv-v1.13.1
sh autogen.sh
./configure
make install
popd
popd

OpenSSL

CentOS (Yum) 
yum install openssl-devel
Ubuntu (APT) 
apt-get install libssl-dev
Mac OS (Brew) 
brew install openssl

NOTE: For Mac OS X 10.11 (El Capitan) and Mac OS 10.12 (Sierra) a link needs to be created in order to make OpenSSL available to the building libraries:

brew link --force openssl

C/C++ driver

CentOS/RHEL and Ubuntu packages

Packages are available from our download server and the latest version of the driver be used:

Manually build and install

The following procedures should be performed if packages are not available for your system.

The C/C++ driver is made available as a submodule; if preferred the source is also available here.

Updating source tree to build submodule 
git update --init lib\cpp-driver
Building and installing the C/C++ driver 
mkdir build
pushd build
cmake ..
make
make install
popd

Refer to the official build documentation for more detailed instructions.

Building and Installing the PHP extension

PECL

The PHP Extension Community Library (PECL) is a repository for PHP extensions. A database package which can ease building and installing the PHP extension can be installed with the following:

pecl install cassandra

Manually build and install

The following procedures should be performed if packages or PECL is not available for your system.

pushd ext
phpize
popd
mkdir build
pushd build
../ext/configure
make
make install
popd

Enabling the PHP extension

To determine where the php.ini file is located on your system run the following command:

php -r "echo php_ini_loaded_file();"

Edit the php.ini file and add the following line to enable the extension:

; DataStax PHP Driver for Apache Cassandra
extension=cassandra.so

To verify the extension is being loaded the following command can be executed:

php -i | grep -A 10 "^cassandra$"

Enabling testing framework

In order to execute the Behat test suite and PHPUnit unit and integration tests Composer must downloaded and installed:

curl -sS https://getcomposer.org/installer | php
php composer.phar install

Windows

We provide a self-contained batch script for building the PHP driver and all of its dependencies. In order to run it, you have to install the build dependencies and clone the repository with the DataStax PHP driver for Apache Cassandra.

Obtaining build dependencies

  • Download and install Bison
    • Make sure Bison is in your system PATH and not installed in a directory with spaces (e.g. %SYSTEMDRIVE%\GnuWin32)
  • Download and install CMake
    • Make sure to select the option “Add CMake to the system PATH for all users” or “Add CMake to the system PATH for current user”
  • Download and install Git
    • Make sure to select the option “Use Git from Windows Command Prompt” or manually add the git executable to the system PATH.
  • Download and install ActiveState Perl
    • Make sure to select the option “Add Perl to PATH environment variable”
  • Download and install Python v2.7.x
    • Make sure to select/install the feature “Add python.exe to Path”

Building the driver

The batch script detects installed versions of Visual Studio to simplify the build process on Windows and select the correct version of Visual Studio for the PHP version the driver is being built for.

First you will need to open a “Command Prompt” to execute the batch script. Running the batch script without any arguments will build the driver for PHP v7.1 and for the current system architecture (e.g. x64).

To perform advanced build configuration, execute the batch script with the --HELP argument to display the options available.

Usage: VC_BUILD.BAT [OPTION...]

    --DEBUG                           Enable debug build
    --RELEASE                         Enable release build (default)
    --DISABLE-CLEAN                   Disable clean build
    --ENABLE-THREAD-SAFETY            Enable thread safety
    --ENABLE-PACKAGES [version]       Enable package generation (5.6, 7.0, 7.1) (*)
    --ENABLE-TEST-CONFIGURATION       Enable test configuration build
    --PHP-VERSION [version]           PHP version 5.6, 7.0, and 7.1 (**)
    --X86                             Target 32-bit build (***)
    --X64                             Target 64-bit build (***)

    C/C++ Driver Options
      --USE-BOOST-ATOMIC              Use Boost atomic

    --HELP                            Display this message

*   Minimum supported officially released PHP binary installations
**  Defaults to PHP v7.1 if --PHP-VERSION is not used
*** Default target architecture is determined based on system architecture

Enable testing

Ensure the driver is built with –ENABLE-TEST-CONFIGURATION in order to execute the Behat test suite and PHPUnit unit and integration tests.

Manual/PHP step-by-step windows build

The PHP driver extension can also be built using the Build your own PHP on Windows instructions followed by the Building PECL extensions instruction where the driver can be statically linked into the PHP executable or as an import (DLL) library. This process requires that the binary dependencies of the PHP driver extension be included in thephpdev\vc##\x##\deps directory along with the standard PHP library dependencies. Use --enable-cassandra to build library into the PHP executable and --enable-cassandra=shared for import (DLL) library.

The PHP driver extension dependencies not included with the standard PHP library can be download here.

Note: The binary libraries downloaded/used must be compatible with the MSVC compiler and the PHP driver extension.

Testing PHP Extension

Features

Linux/Mac OS 

bin/behat

Windows 

bin\behat.bat

Unit and integration tests

Linux/Mac OS 

bin/phpunit

Windows 

bin\phpunit.bat