Configuration

Ice Extension for PHP : 24.3 Configuration

24.3 Configuration

This section describes how to configure IcePHP, including its configuration directives and the run time functions used to activate a configuration. For installation instructions, please refer to the INSTALL file included in the IcePHP distribution.

24.3.1 Profiles

IcePHP allows any number of PHP applications to run independently in the same PHP interpreter, without risk of conflicts caused by Slice definitions that happened to use the same identifiers. IcePHP uses the term profile to describe an application’s configuration, including its Slice definitions and Ice configuration properties.

24.3.2 Default Profile

A default profile is supported, which is convenient during development, or when only one Ice application is running in a PHP interpreter. Table 24.1 describes the PHP configuration directives¹ for the default profile.

Table 24.1. PHP configuration directive for the default profile.
Name	Description
ice.config	Specifies the pathname of an Ice configuration file.
ice.options	Specifies command-line options for Ice configuration properties. For example, ‑‑Ice.Trace.Network=1. This is a convenient alternative to an Ice configuration file if only a few configuration properties are required.
ice.profiles	Specifies the pathname of a profile configuration file. See Section 24.3.3.
ice.slice	Specifies preprocessor options and the pathnames of Slice files to be loaded. In addition to the common options such as -I and -D, IcePHP supports the -w option to suppress warnings about interfaces that are declared but not defined, and dictionaries whose types are not supported.

Here is a simple example:

ice.options="‑‑Ice.Trace.Network=1 ‑‑Ice.Warn.Connections=1"
ice.slice="‑I/myapp/include /myapp/include/MyApp.ice"

24.3.3 Named Profiles

If a file name is specified by the ice.profiles configuration directive, the file is expected to have the standard INI-file format. The section names identify profiles, where each profile supports the ice.config, ice.options and ice.slice directives defined in Section 24.3.2. For example:

[Profile1]
ice.config=/profile1/ice.cfg
ice.slice=/profile1/App.ice

[Profile2]
ice.config=/profile2/ice.cfg
ice.slice=/profile2/App.ice

This file defines two named profiles, Profile1 and Profile2, having separate Ice configurations and Slice definitions.

24.3.4 Profile Functions

Two global functions are provided for profile activities:

Ice_loadProfile(/* string */ $name = null);
Ice_dumpProfile();

The Ice_loadProfile function must be invoked by a script in order to make the Slice types available and to configure the script’s communicator. If no profile name is supplied, the default profile is loaded. A script is not allowed to load more than one profile.

For example, here is a script that loads Profile1 shown in Section 24.3.3:

<?php
Ice_loadProfile("Profile1");
...
?>

For troubleshooting purposes, the Ice_dumpProfile function can be called by a script. This function displays all of the relevant information about the profile loaded by the script, including the communicator’s configuration properties as well as the PHP mappings for all of the Slice definitions loaded by the profile.

Finally, if a script needs to determine the version of the Ice run time, it can call the version function:

$icever = Ice_version();

24.3.5 Slice Semantics

The expense of parsing Slice files is incurred once, when the PHP interpreter initializes the IcePHP extension. For this reason, we recommend that the IcePHP extension be statically configured into the PHP interpreter, either by compiling the extension directly into the interpreter, or configuring PHP to load the extension dynamically at startup. For the same reason, we discourage the use of IcePHP in a CGI context, in which a new PHP interpreter is created for every HTTP request. Furthermore, we strongly discourage scripts from dynamically loading the IcePHP extension using PHP’s dl function.

24.3.6 Using IceSSL

An IcePHP application can establish an SSL connection to an Ice server if it is properly configured to use the IceSSL plug-in. Since IcePHP uses the Ice for C++ run time, you should consult the C++ sections of Chapter 38 for detailed instructions on installing and configuring IceSSL.

A typical IceSSL configuration uses several properties, therefore it is often more convenient to define an external configuration file via the ice.config directive:

ice.config=/opt/MyApp/ice.cfg

The file ice.cfg might contain the configuration properties shown below:

Ice.Plugin.IceSSL=IceSSL:createIceSSL
IceSSL.DefaultDir=/opt/MyApp/certs
IceSSL.CertAuthFile=ca.pem
IceSSL.CertFile=client.pem
IceSSL.KeyFile=key.pem
...

An IcePHP application can only use the IceSSL features that are available via configuration properties; the plug-in’s programmatic interface is not currently supported in PHP.

As a final note, you should carefully consider the security implications of using SSL given that all of the scripts executed by the same instance of a PHP interpreter share the same communicator and therefore the same IceSSL configuration.

These directives are typically defined in the php.ini file, but can also be defined using web-server specific directives.