summaryrefslogtreecommitdiffstats
path: root/sca-cpp/branches/cpp-contrib/contrib/runtime/extensions/php/README
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--sca-cpp/branches/cpp-contrib/contrib/runtime/extensions/php/README276
1 files changed, 276 insertions, 0 deletions
diff --git a/sca-cpp/branches/cpp-contrib/contrib/runtime/extensions/php/README b/sca-cpp/branches/cpp-contrib/contrib/runtime/extensions/php/README
new file mode 100644
index 0000000000..ad96622516
--- /dev/null
+++ b/sca-cpp/branches/cpp-contrib/contrib/runtime/extensions/php/README
@@ -0,0 +1,276 @@
+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
+