diff options
Diffstat (limited to '')
| -rw-r--r-- | sca-cpp/branches/cpp-contrib/contrib/runtime/extensions/php/README | 276 |
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 + |