contrib/runtime/extensions/php/README - tuscany-sca-cpp - Git at Google

 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
	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