Conversion of types between PHP and Java

From PHP to Java

Automatic Type Conversion from PHP to Java

Automatic type conversion occurs when an XAPI extension uses the com.ibm.phpj.xapi.RuntimeContext.getArgument method to access its parameters and also when an array is copied out using the method com.ibm.phpj.xapi.XAPIArray.copyOut. The table below details the Java Type that will result for the various PHP types.

Explicit Type Conversion PHP to Java

XAPI supports explicit type conversion where the author of an XAPI extension function wishes to force the conversion of a PHP value into a particular Java type. This is achieved by calling a method if the form: com.ibm.phpj.xapi.RuntmeContext.get<Type>Argument(). For example getIntegerArgument or getDoubleArgument.

The following conversions are supported.

Note 1 To get a resource or array from XAPI, the argument passed from the script must be of that type. So for example, XAPI does not convert primitive values into an array if an extension calls getArrayArgument and the argument is an integer. If the argument is not an array then an XAPIException is thrown containing an *XAPIExceptionCode of XERR_UNKNOWN_ARGUMENT_TYPE. The same applies for resources and objects.

Conversion from PHP Array to Java Array

A PHP array can be copied into a Java Array of Objects (an Object[]) using the copyOutArray method on the com.ibm.phpj.xapi.XAPIArray object representing the PHP array. This method has the following behaviour:

• Each element in the PHP array is converted into an element in the Java array using the type conversion rules specified in Automatic Type Conversion from PHP to Java
• Keys in the PHP array are always ignored. This applies to both integer and string keys.
• The values in the java array are inserted in incrementing index positions based on the order in the PHP array. ** Note that this means that $phparray[4] will not necessarily map to javarrray[4].
• In order to preserve the key values or order the entries in the java array using different algorithms either iterate through the elements in an XAPIArray or use XAPIArray.copyOut to obtain a Map.

XAPIString Type

The XAPIString type is used to represent a PHP String to Java. This type is necessary because PHP5 permits any arbitrary sequence of bytes to be stored in a PHP String. Internally the PHP runtime for WebSphere sMash stores PHP strings as an array of bytes. Java Strings are not sequences of bytes, they are sequences of Java Characters which are Unicode characters. This means that converting from a PHP string directly to a Java String risks losing information or altering the meaning of the data. XAPIString provides methods to access the HP string either as a Java String or as a Java byte array. For more information see the Javadoc.

XAPIArray Type

The XAPIArray type is used to represent a PHP array to Java. It contains methods to iterate through the array, get and set elements and keys and to copy the Array into a Java array or map. For further information see the Javadoc.

From Java to PHP

Automatic Type conversion from Java to PHP

Automatic type conversion from Java to PHP occurs when an XAPI function returns a value to PHP using the com.ibm.phpj.xapi.RuntimeContext.setReturnValue method.

Conversion from Java Array to PHP array

• Note that arrays of primitive bytes byte[] are converted to PHP strings. This does not apply to Byte[] which is treated like any other Object array.
• Individual elements in the Object array are converted as per these rules, including nested arrays.
• The Java array of Objects is converted into a PHP array using the index into the java object as the integer key in the PHP array.
• The "order" in the PHP array is with incrementing integer key.
• Arrays of primitive types are converted into Java arrays by boxing the types and using these conversion rules (except byte[]).
• Multidimensional java arrays are supported, for example:

XAPIArray array = runtimeContext.createArray();
int[][] integerArray = { { 123, 456, 999 }, { 1, 2, 3 } };
array.copyInArray(integerArray);
assert (array.count(true) == 8);

• An element of a Java array can be a Map and is converted using the rules above.
• A Java array can be primitive types (int[], short[] etc) or boxed values (Integer[], Double[] etc)
• Consider the following code fragment. Notice the difference between putAtTail and copyInArray. putAtTail is inserting an array into another array. copyInArray however is extracting and copying the contents of the array into the destination array. That's why the node counts differ by one.

XAPIArray array = runtimeContext.createArray();
int[][] integerArray = { { 123, 456, 999 }, { 1, 2, 3 } };
array.putAtTail(integerArray);
assert (array.count(true) == 9);
array.clear();
array.copyInArray(integerArray);
assert (array.count(true) == 8);