PHP Extension for C++ SCA README
================================

Overview
--------

The PHP extension for C++ SCA allows PHP scripts to be used to implement SCA components. 
This is achieved by using the C++ SCA extension API to drive script execution through the 
PHP embedding SAPI. In its current incarnation the PHP Extension requires that a full SCDL 
description is provided for each PHP component, i.e. we are not yet making use of the meta data
provided by the annotations that can appear in PHP SCA components. 

There are various styles of PHP script that are supported. The examples here are taken from 
the PHPCalculator sample and if you look at the SCDL files provided with the sample you can 
see the component type and composite files that tie these components into the working system

SCA Service
-----------

/**
 * @service
 * @binding.ws
 */
class Divide {

    /**
     * @reference 
     * @binding.tuscany cppDivideService
     */
    public $another_divide;

    /**
     * Division
     *
     * @param float $num1 (the first number)
     * @param float $num2 (the second number)
     * @return float The result
     */
    function div($num1, $num2) {
        return $this->another_divide->div($num1, $num2);
    }

}

PHP Class
---------

class Multiply {
    function mul($num1, $num2) {
        $result = $num1 * $num2;    

        $log_proxy = SCA::getService("log_service");
        $log_proxy->log_message($result);
        
        return $result;
    }    
}

PHP Function
------------

function sub($num1, $num2){
    $result = $num1 - $num2;    

    $log_proxy = SCA::getService("log_service");
    $log_proxy->log_message($result);
        
    return $result;
}  

PHP Script
----------

$num1 = $_REQUEST[0];
$num2 = $_REQUEST[1];

$result = $num1 + $num2;    

$log_proxy = SCA::getService("log_service");
$log_proxy->log_message($result);

echo $result;

TODO
----
* I struggled for a long time with a missing symbol problem loading sdo.so at runtime on linux.
  I got round this by creating a standalone Makefile for the CalculatorClient exe. All the 
  shared objects that are loaded are compiled with the normal automake toolchain still but this
  solves the problem. I need to investigate in detail what's going on here. Having someone
  else try building with the full automake configuration would be insteresting
* The problem from above does appear when running SCA behind axis hence I am unable to test with
  remote clients
* The SCA_SDO build generates sdo.so and the Tuscany PHP Extension tries to load libsdo.so.
  One side needs fixing. For now I just copy the library  
* SDO passing in and out of components is coded but not tested
* Returning values from plain PHP scripts (scripts without classes and functions) is not 
  operating correctly
* Error handling needs looking at. Many situations are not trapped and those
  that are may not be reported correctly
* Reorganize the extension code so that Tuscany SCA can be loaded by PHP running in Apache 
  and accessed through SCA references. This will play the same role as SCA running hosted
  in Axis2C and will open up the service bindings implemented in PHP SCA_SDO. 
* Implement meta data exchange between the PHP SCA implementation and the Tuscany C++ SCA
  implementations so that selected parts of the SCDL definition can be omitted.
* There is a threading issue with the way that we are firing up the PHP embedding SAPI 
  TSRM should solve it fails on the embedding initialization for some reason. 

Dependencies 
------------
PHP5.2.0 source code - - (http://php.net/)
   The binary release of PHP doesn't ship with the header files required to build 
   against the PHP embedding SAPI and runtime libraries. So go get the PHP source
   code and build PHP. PHP will need to be configured correctly in order to 
   work properly when embedded in C++ SCA. Here are some sample configuration 
   statements but they will need to be tailored for you specific environment:
   
   Winodws
   -------
   cscript configure.js --with-extra-includes=win32build\include;
                          libxml2-2.6.26.threads\include;
                          iconv-1.9.1.win32\include;
                          libcurl-7.15.4-nossl\include 
                        --with-extra-libs=win32build\lib;
                          libxml2-2.6.26.threads\lib;                       
                          iconv-1.9.1.win32\lib;
                          libcurl-7.15.4-nossl\lib 
                        --enable-debug 
                        --enable-soap  
                        --enable-apache2handler=shared 
                        --enable-embed 
                        --with-curl=C:\simon\apps\libcurl-7.15.4-nossl 

   Note. This configure line is artificially broken across sever lines to aid
   readability here. You will need to join it all back together on one line to 
   run it. 

   Linux
   -----
   ./configure --enable-debug \
               --enable-soap \
               --enable-fastcgi \
               --with-zlib \
               --enable-embed \
               --with-tsrm-pthreads \
               --enable-maintainer-zts 
   Note. debug, pthreads, maintainer-zts, fastcgi are not absolute requirements but just
         represent the environment I was testing with when I wrote this. 
   
SCA_SDO PECL extension AVOCET branch source code - (http://pecl.php.net/package/SCA_SDO)
   Provides the SCA framework for PHP and the necessary mediation code to translate
   between Tuscany SCA and PHP SCA.  Go get the AVOCET branch from PECL cvs 

   export CVSROOT=:pserver:cvsread@cvs.php.net/repository
   cvs export -r AVOCET pecl/sdo
   
   The process to build this code varies quite considerably between windows and Linux.
   Take a look at the instructions in the SCA_SDO manual, follow the documentation link
   from the projects PECL page (http://uk2.php.net/sdo/).
   
   Once built you will need to copy the library sdo.so to 
   libsdo.so so that the Tuscany PHPExtension can load it given the makefile 
   configuration as it stands. For example, on linux
   
   ln -s sdo.so libsdo.so
      

Building on windows
-------------------

The Visual C++ Express solution provided with C++ SCA includes a project
to build the PHP extension. This project relies on being able to access the 
PHP include files from the source code directory and the PHP lib files from the
binary install. Make sure your environment is set as follows before you start
Visual C++ Express (if you do this after you start Visual C++ Express it will 
not pick up the changes)

PHP_HOME = the root directory of the PHP 5.2.0 source code install
PATH = ensure that the root directory of the PHP 5.2.0 binary install appears 

PHP_SCA_SDO_HOME = the directory in which the SCA_SDO pecl extension source is installed

These changes come over and above the environment changes you need to make
to build the core C++ SCA software. I have the following set in my environment but
of course the details depend on where you have the various bits of software installed. 

AXIS2C_HOME=c:\axis2c-bin-0.96-win32
LIBXML2_HOME=c:\libxml2-2.6.26.ein32
ICONV_HOME=c:\iconv-1.9.2.win32
ZLIB_HOME=c:\zlib-1.2.3.win32
TUSCANY_SCACPP=c:\sca\deploy
TUSCANY_SDOCPP=c:\sdo\deploy

Now compile the PHP extension. Compiling with VC++ Express requires some care

1/ Ensure that the PHP include files are configured correctly for 
   compiling against C++ SCA in Visual C++ express
  
  See - http://bugs.php.net/bug.php?id=39130

  Comment out two lines in $(PHP_HOME)/main/config.w32.h:
  #define _USE_32BIT_TIME_T 1
  #define HAVE_STDLIB_H 1
  

Building on Linux 
-----------------

The PHP extension comes with a set of automake files so that the PHP extension is built
at the same time as all of the other extensions assuming that appropriate environment
variables are set. The build.sh script that can be found under the top level sca directory
checks whether the PHP_LIB and PHP_INCLUDE variables are set and if so enables compilation
of the PHP extension automatically by adding --enable-php to the configure line. 

There are a number of environment variables that the build depends on. I find setting the 
following variables useful. 

# the location of libxm2 
export LIBXML2_LIB=/usr/lib
export LIBXML2_INCLUDE=/usr/include/libxml2

# the location of PHP
export PHP_LIB=/usr/local/lib
export PHP_INCLUDE=/usr/local/include/php

# the location of the PHP SCA_SDO extension source
# the lib location depends oh the configuration options used
# when building PHP so beware
export PHP_SCA_SDO_INCLUDE=where ever you install the SCA_SDO package source
export PHP_SCA_SDO_LIB=$PHP_LIB/php/extensions/no-debug-zts-20060613/

# the location of axis2
export AXIS2C_HOME=/usr/local/axis2c-bin-0.96-linux

# the install directories for the tuscany sca and sdo projects
export TUSCANY_SDOCPP=/usr/local/tuscany/cpp/sdo/deploy
export TUSCANY_SCACPP=/usr/local/tuscany/cpp/sca/deploy

Once these are set running sca/build.sh should compile and install the PHP extension. 

Testing the PHP Extension
-------------------------

In order to run the PHP extension successfully as an embedded component of the 
C++ SCA runtime the PHP environment must be configured correctly. This configuration
is provided by the php.ini file. The location of this file depends on your installation
of PHP but by default is as follows. 

/usr/local/bin            - PHP executables
/usr/local/lib/php.ini    - the ini file that tell PHP where to look for scripts and 
                            extension libraries
/usr/local/lib/php        - PHP runtime installation, extension files and tests

As is usually the case your milage may vary but wherever PHP is installed you will find 
a similar set of directories. To force PHP to look in the correct place use the following
setting

# tell PHP specifically where to find php.ini rather than relying on the default
set PHPRC=/usr/local/lib

The php.ini file must be configured to load the SCA_SDO extension so you would expect to 
see the following modifications to the file.

; around line 528 you need to set the variable that tells PHP where to 
; load extension libraries from. This varies depending on how PHP has been 
; compiled and installed, for example,
extension_dir = "/usr/local/lib/php/extensions/no-debug-zts-20060613/"

; around line 512 you need to set the variable that tells PHP where to 
; load included scripts from. There are windows and unix versions. Here
; is a Unix example
include_path=".:/usr/local/lib/php:/usr/local/lib/php/PEAR:/usr/local/tuscany/cppsca/samples/PHPCalculator/deploy/sample.calculator"

; around line 673 you will find the end of the list of enabled extensions. We need to turn
; on SDO so add the following line. sdo.so should be found in "extension_dir". 
extension=sdo.so