1# Building Ice for PHP 2 3This page describes how to build and install Ice for PHP from source. 4 5ZeroC provides [binary distributions][1] for many platforms, including 6Linux and Windows, so building Ice for PHP from source is usually 7unnecessary. 8 9* [PHP Build Requirements](#php-build-requirements) 10* [Building the PHP Extension](#building-the-php-extension) 11 * [Linux or macOS](#linux-or-macos) 12 * [Windows](#windows) 13* [Installing the PHP Extension](#installing-the-php-extension) 14 * [Linux or macOS](#linux-or-macos-1) 15 * [Windows](#windows-1) 16* [PHP Dependencies](#php-dependencies) 17* [PHP Source Files](#php-source-files) 18* [Running the PHP Tests](#running-the-php-tests) 19* [Web Server Permissions](#web-server-permissions) 20* [SELinux Notes for PHP](#selinux-notes-for-php) 21 22## PHP Build Requirements 23 24Ice was extensively tested using the operating systems and compiler versions 25listed on [supported platforms][2]. 26 27On Windows, the build requires a recent version of Visual Studio and the 28[Ice Builder for Visual Studio][3]. 29 30## Building the PHP Extension 31 32### Linux or macOS 33 34The build of Ice for PHP requires that you first build Ice for C++ in the `cpp` 35subdirectory. 36 37From the top-level source directory, edit `config/Make.rules` to establish 38your build configuration. The comments in the file provide more information. 39 40Our source code only supports building Ice for PHP as a dynamic PHP extension; 41the product of the build is a shared library that you must configure PHP to 42load. 43 44Change to the `php` source subdirectory: 45``` 46cd php 47``` 48 49Ensure that `php` and `php-config` for the version of PHP you wish to 50build against are first in your PATH. 51 52Run `make` to build the extension. 53 54### Windows 55 56Open a Visual Studio command prompt. For example, with Visual Studio 2015, you 57can open one of: 58 59- VS2015 x86 Native Tools Command Prompt 60- VS2015 x64 Native Tools Command Prompt 61 62Using the first Command Prompt produces `Win32` binaries by default, while 63the second Command Promt produces `x64` binaries by default. 64 65In the Command Prompt, change to the `php` subdirectory: 66``` 67cd php 68``` 69 70Now you're ready to build Ice for PHP: 71``` 72msbuild msbuild\ice.proj 73``` 74 75This builds the extension with `Release` binaries for the default platform. The 76extension will be placed in `lib\x64\Release\php_ice.dll` for the `x64` platform 77and `lib\Win32\Release\php_ice.dll` for the `Win32` platform. 78 79The default configuration builds the extension against the thread-safe PHP run 80time. You can build with the non-thread-safe run time using the `NTS-Release` or 81`NTS-Debug` configuration: 82``` 83msbuild msbuild\ice.proj /p:Configuration=NTS-Release 84``` 85 86The extension will be placed in `lib\x64\Release\php_ice_nts.dll` directory for 87the `x64` platform and `lib\Win32\Release\php_ice_nts.dll` for the `Win32` 88platform. 89 90The extension is built by default with namespaces enabled. You can build the PHP 91extension with namespaces disabled by setting the MSBuild property 92`PhpUseNamespaces` to `no`: 93``` 94msbuild msbuild\ice.proj /p:PhpUseNamespaces=no 95``` 96 97The PHP extension is build by default using PHP 7.1, the extension can be build with 98PHP 7.1, 7.2 or 7.3 by setting MSBuildProperty `BuildWithPhpVersion` to the desired 99version for example you can use the following command to build the extension with PHP 1007.2: 101 102``` 103msbuild msbuild\ice.proj /p:BuildWithPhpVersion=7.2 104``` 105 106The PHP extension depends on Ice for C++ components from the `cpp` subdirectory, 107and those are built if required. It is also possible to build the PHP extension 108using the Ice for C++ NuGet packages by setting the`ICE_BIN_DIST` msbuild 109property to `cpp`: 110``` 111msbuild msbuild\ice.proj /p:ICE_BIN_DIST=cpp 112``` 113 114## Installing the PHP Extension 115 116### Linux or macOS 117 118To install the Ice extension, you must move the extension's shared library into 119PHP's extension directory. This directory is determined by the PHP configuration 120directive `extension_dir`. You can determine the default value for this 121directive by running the command-line version of PHP with the `-i` option: 122``` 123php -i 124``` 125 126Review the output for a line like this: 127``` 128extension_dir => /usr/lib/php/modules => /usr/lib/php/modules 129``` 130 131Once you've copied the extension to PHP's extension directory, you will need to 132enable the extension in your PHP configuration. Your PHP installation likely 133supports the `/etc/php.d` configuration directory, which you can verify by 134examining the output of `php -i` and looking for the presence of 135`--with-config-file-scan-dir` in the "Configure Command" entry. If present, 136you can create a file in `/etc/php.d` that contains the directive to load the 137Ice extension. For example, create the file `/etc/php.d/ice.ini` containing 138the following line: 139``` 140extension = ice.so 141``` 142 143If PHP does not support the `/etc/php.d` directory, determine the path name of 144PHP's configuration file as reported by the `php -i` command: 145``` 146Configuration File (php.ini) Path => /etc/php.ini 147``` 148 149Open the configuration file and append the following line: 150``` 151extension = ice.so 152``` 153 154You can verify that PHP is loading the Ice extension by running the command 155shown below: 156``` 157php -m 158```` 159 160Look for `ice` among the installed modules. Note that your library search path 161(`LD_LIBRARY_PATH` on Linux or `DYLD_LIBRARY_PATH` on macOS) must include the 162directory containing the Ice shared libraries. 163 164Read the PHP Dependencies and PHP Source Files sections below for more 165information about installing the Ice extension. 166 167### Windows 168 169To install the Ice extension, you must move the extension's shared library into 170PHP's extension directory. This directory is determined by the PHP configuration 171directive `extension_dir`. You can determine the default value for this 172directive by running the command-line version of PHP with the `-i` option: 173``` 174php -i 175``` 176 177Review the output for a line like this: 178``` 179extension_dir => C:\Program Files\iis express\PHP\v7.1\ext\ => C:\Program Files\iis express\PHP\v7.1\ext\ 180``` 181 182Once you've copied the extension to the appropriate directory, you will need 183to enable the extension in your PHP configuration. First you must discover the 184location of PHP's configuration file (`php.ini`), which is also displayed by 185the `-i` option. Look for the following line: 186``` 187Loaded Configuration File => C:\Program Files\iis express\PHP\v7.1\php.ini 188``` 189 190Open `php.ini` and append the following directive: 191``` 192extension=php_ice_nts.dll 193``` 194 195Read the PHP Dependencies and PHP Source Files sections below for more 196information about installing the Ice extension. 197 198## PHP Dependencies 199 200PHP needs to locate the libraries for the Ice run-time libraries and its 201third-party dependencies. 202 203* Linux and macOS 204``` 205libIce 206libIceDiscovery 207libIceLocatorDiscovery 208libIceSSL 209libbz2 210``` 211 212* Windows 213``` 214bzip2.dll 215ice37.dll 216icediscovery37.dll 217icelocatordiscovery37.dll 218icessl37.dll 219``` 220 221In general, these libraries must reside in a directory of the user's PATH. 222For Web servers, the libraries may need to reside in a system directory. For 223example, on Linux you can add the directory containing the Ice run-time 224libraries to `/etc/ld.so.conf` and run `ldconfig`. 225 226For IIS configured to run PHP as FastCGI, the simplest solution is to copy the 227libraries next to the `php-cgi.exe` in `C:\Program Files\iis express\PHP\v7.1`. 228 229You can verify that the Ice extension is installed properly by examining the 230output of the `php -m` command, or by calling the `phpInfo()` function from a 231script. For example, you can create a file in the Web server's document 232directory containing the following PHP script: 233``` 234<?php 235phpInfo(); 236?> 237``` 238 239Then start a browser window and open the URL corresponding to this script. If 240the Ice extension is successfully installed, you will see an `ice` section 241among the configuration information. 242 243## PHP Source Files 244 245In addition to the binary Ice extension module and its library dependencies, 246you will also need to make the Ice for PHP source files available to your 247scripts. These files are located in the `lib` subdirectory and consist of the 248Ice run time definitions (`Ice.php`) along with PHP source 249files generated from the Slice files included in the Ice distribution. 250 251The Ice extension makes no assumptions about the location of these files, so you 252can install them anywhere you like. For example, you can simply include them in 253the same directory as your application scripts. Alternatively, if you prefer to 254install them in a common directory, you may need to modify PHP's `include_path` 255directive so that the PHP interpreter is able to locate these files. For example, 256you could append to `php.ini`: 257``` 258include_path=${include_path}";C\ice\php\lib" 259``` 260 261Another option is to modify the include path from within your script prior to 262including any Ice run-time file. Here is an example that assumes Ice is installed 263in 264`/opt`: 265``` 266// PHP 267ini_set('include_path', 268ini_get('include_path') . PATH_SEPARATOR . '/opt/Ice/php'); 269require 'Ice.php'; // Load the core Ice run time definitions. 270``` 271 272## Running the PHP Tests 273 274The test subdirectory contains PHP implementations of the core Ice test suite. 275Python is required to run the test suite. 276 277The test suites also require that the Ice for C++ tests be built in the `cpp` 278subdirectory of this source distribution. In addition, the scripts require 279that the CLI version of the PHP interpreter be available in your PATH. 280 281After a successful build, you can run the tests as follows: 282``` 283python allTests.py 284``` 285 286If you have built the extension using the Ice for C++ NuGet packages, you must 287also set the `ICE_BIN_DIST` environment variable to `cpp` for testing: 288``` 289set ICE_BIN_DIST=cpp 290python allTests.py 291``` 292 293If everything worked out, you should see lots of `ok` messages. In case of a 294failure, the tests abort with `failed`. 295 296## Web Server Permissions 297 298The Web server normally runs in a special user account that may not necessarily 299have access to the Ice extension, its dependent libraries and PHP source files, 300and other resources such as Ice configuration and your application scripts. It 301is very important that you review the permissions of these files and verify 302that the Web server has sufficient access. 303 304On Linux, Apache typically runs in the `apache` account, so you will either 305need to change the owner or group of the libraries and other resources, or 306modify their permissions to make them sufficiently accessible. 307 308## SELinux Notes for PHP 309 310SELinux augments the traditional Unix permissions with a number of new features. 311In particular, SELinux can prevent the httpd daemon from opening network 312connections and reading files without the proper SELinux types. 313 314If you suspect that your Ice for PHP application does not work due to SELinux 315restrictions, we recommend that you first try it with SELinux disabled. 316As root, run: 317``` 318# setenforce 0 319``` 320 321to disable SELinux until the next reboot of your computer. 322 323If you want to run httpd with Ice for PHP and SELinux enabled, there are two 324steps you need to take. First, allow httpd to open network connections: 325``` 326# setsebool httpd_can_network_connect=1 327``` 328 329Add the `-P` option to make this setting persistent across reboots. 330 331Second, make sure any `.ice` file used by your PHP scripts can be read by httpd. 332The enclosing directory also needs to be accessible. For example: 333``` 334# chcon -R -t httpd_sys_content_t /opt/MyApp/slice 335``` 336 337[1]: https://zeroc.com/distributions/ice 338[2]: https://doc.zeroc.com/display/Rel/Supported+Platforms+for+Ice+3.7.2 339[3]: https://github.com/zeroc-ice/ice-builder-visualstudio 340