28.7 Mapping for User-Defined Types

Slice supports user-defined types: enumerations, structures, sequences, and dictionaries.

28.7.1 Mapping for Enumerations

PHP does not have an enumerated type, so Slice enumerations are mapped to constants in a PHP class: the name of the Slice enumeration becomes the name of the PHP class; for each enumerator, the class contains a constant with the same name as the enumerator (see Section 28.3 for more information on identifiers). For example:

enum Fruit { Apple, Pear, Orange };

The generated PHP class looks as follows:

class Fruit
{
    const Apple = 0;
    const Pear = 1;
    const Orange = 2;
}

Since enumerated values are mapped to integers, application code is not required to use the generated constants. When an enumerated value enters the Ice run time, Ice validates that the given integer is within the expected range for the enumeration. However, to minimize the potential for defects in your code, we recommend using the generated constants instead of literal integers.

28.7.2 Mapping for Structures

A Slice structure maps to a PHP class containing a public variable for each member of the structure. The class also provides a constructor whose arguments correspond to the data members. This allows you to instantiate and initialize the class in a single statement (instead of having to first instantiate the class and then assign to its members). Each argument provides a default value appropriate for the member’s type. You can also declare different default values for members of primitive and enumerated types, as discussed in Section 4.9.2. For example, here is our Employee structure from Section 4.9.4 once more:

struct Employee {
    long number;
    string firstName;
    string lastName;
};

The PHP mapping generates the following definition for this structure:

class Employee
{
    public function __construct($number=0, $firstName='',
                                $lastName='');

    public function __toString();

    public $number;
    public $firstName;
    public $lastName;
}

The mapping includes a definition for the __toString magic method, which returns a string representation of the structure.

28.7.3 Mapping for Sequences

Slice sequences are mapped to native PHP indexed arrays. The first element of the Slice sequence is contained at index 0 (zero) of the PHP array, followed by the remaining elements in ascending index order.

Consider this example:

sequence<Fruit> FruitPlatter;

You can create an instance of FruitPlatter as shown below:

// Make a small platter with one Apple and one Orange
//
$platter = array(Fruit::Apple, Fruit::Orange);

The Ice run time validates the elements of an array to ensure that they are compatible with the declared type and raises InvalidArgumentException if an incompatible type is encountered.

28.7.4 Mapping for Dictionaries

Slice dictionaries map to native PHP associative arrays. The PHP mapping does not currently support all Slice dictionary types, however, because native PHP associative arrays support only integer and string key types. A Slice dictionary whose key type is an enumeration or one of the primitive types boolean, byte, short, int, or long is mapped as an associative array with an integer key.¹ A Slice dictionary with a string key type is mapped as associative array with a string key. All other key types cause a warning to be generated.

Here is the definition of our EmployeeMap from Section 4.9.4:

dictionary<long, Employee> EmployeeMap;

You can create an instance of this dictionary as shown below:

$e1 = new Employee;
$e1‑>number = 42;
$e1‑>firstName = "Stan";
$e1‑>lastName = "Lipmann";

$e2 = new Employee;
$e2‑>number = 77;
$e2‑>firstName = "Herb";
$e2‑>lastName = "Sutter";

$em = array($e1‑>number => $e1, $e2‑>number => $e2);

The Ice run time validates the elements of a dictionary to ensure that they are compatible with the declared type; InvalidArgumentException exception is raised if an incompatible type is encountered.

Boolean values are treated as integers, with false equivalent to 0 (zero) and true equivalent to 1 (one).