Creating a simple PHP extension

To create a sample extension that allows manipulation of BigDecimals, use the following steps:

1. Open the Java™ perspective in Eclipse. (Window->Open perspective->Java)
2. Create a new IBM® WebSphere® sMash PHP application and name it bigdecimal.
3. Edit the dependencies in the config/ivy.xml file to remove the dependency to zero.core and save the file because PHP extensions do not require the core platform.

   

4. Select the bigdecimal project and create the Java class BigDecimalExtension.java using File->New->Class. Specify the extension name, package and make it extend com.ibm.phpj.xapi.ExtensionBaseImpl.

   

5. Open the class in the editor and paste the following code into the class:

   package bigDecimal;
   import java.math.BigDecimal;
   import com.ibm.phpj.xapi.ExtensionBaseImpl;
   import com.ibm.phpj.xapi.RuntimeContext;
   import com.ibm.phpj.xapi.annotations.XAPIExtension;
   import com.ibm.phpj.xapi.annotations.XAPIFunction;
   
   @XAPIExtension("BigDecimal")
   public class BigDecimalExtension extends ExtensionBaseImpl {
           @XAPIFunction("add_bigdecimal")
           public void add(RuntimeContext ctxt) {
                   BigDecimal arg1 = new BigDecimal(ctxt. 
                   getStringArgument(0).getString());
                   BigDecimal arg2 = new BigDecimal(ctxt. 
                   getStringArgument(1).getString());
                   BigDecimal result = arg1.add(arg2);
                   ctxt.setReturnValue(result.toString());
           }
   }
   

   The following list provides further information about this code snippet:

   • For a class to be considered to implement a PHP extension, it must extend ExtensionBaseImpl and be annotated with @XAPIExtension, as shown in the previous snippet.
   • For a method to be exposed as a PHP function, it must take an object of the com.ibm.phpj.RuntimeContext type as the only argument and be annotated with @XAPIFunction, as shown.
   • The default parameter passing convention is pass-by-value. Pass-by-value means a copy of the parameter is passed to the extension function. The alternative is pass-by-reference in which the extension function is passed a reference to the caller's variable and so can change it. An example passing and returning by reference is presented in another tutorial.
   • The arguments from the PHP script are accessed from the RuntimeContext object using the get<Type>Argument() method. The first argument is indexed at 0. So, to get the first argument as a String, use the getStringArgument(0) invocation. See the javadoc for getStringArgument for more information.
   • The value to be returned to the PHP script is set using using the RuntimeContext.setReturnArgument() method.
6. Save and close the file. Your extension is complete. The following section provides information about invoking it.

Using a PHP extension from a WebSphere sMash application

The following steps describe calling the add_bigdecimal extension function in the BigDecimalExtension.

1. Create or open an existing WebSphere sMash PHP application where an extension is to be used.
2. Edit the config/ivy.xml file to add a dependency on the bigdecimal project.

   

3. Edit the config/php.ini file to enable BigDecimalExtension using the directive extension = bigDecimal.BigDecimalExtension.
4. Use the add_bigdecimal function defined by BigDecimalExtension in a PHP script as you would any PHP function.

The following code sample.php illustrates the use of the function defined by BigDecimalExtension.

<?php    
echo "Add big decimal ".add_bigdecimal('111111111111111', '222222222222222');
?>