Locate the ext/php directory inside the LIXA source
tree and enter it; you should find an executable shell script named
download_and_patch.sh inside it:
tiian@mojan:~/lixa/ext/php$ ls -la download_and_patch.sh
-rwxr-xr-x 1 tiian tiian 4855 2012-03-31 23:37 download_and_patch.sh
You need a running Internet connection before command execution because it will try to download the PHP tarball for you from http://docs.php.net/
Command download_and_patch.sh can do most operation for you, but you can perform the same manually. Try to execute the script from a terminal session:
| [Shell terminal session] |
tiian@mojan:~/lixa/ext/php$ ./download_and_patch.sh
PHP 5.4.1 will be downloaded...
Checking if wget command is available... wget is /usr/bin/wget
Checking if patch command is available... patch is /usr/bin/patch
Checking if bunzip2 is available... bunzip2 is /bin/bunzip2
--2012-04-29 22:47:03-- http://docs.php.net/get/php-5.4.1.tar.bz2/from/docs.php.net/mirror
Resolving docs.php.net... 213.175.195.123
Connecting to docs.php.net|213.175.195.123|:80... connected.
HTTP request sent, awaiting response... 302 Found
Location: http://docs.php.net/distributions/php-5.4.1.tar.bz2 [following]
--22:19:05-- http://docs.php.net/distributions/php-5.4.1.tar.bz2
=> `php-5.4.1.tar.bz2'
Connecting to docs.php.net|213.175.195.123|:80... connected.
HTTP request sent, awaiting response... 200 OK
Length: 11145742 (11M) [application/octet-stream]
Salvataggio in: "php-5.4.1.tar.bz2"
100%[======================================>] 11.145.742 681K/s in 15s
2012-04-29 22:47:18 (743 KB/s) - "php-5.4.1.tar.bz2" salvato [11145742/11145742]
Deflating PHP source code...
Creating LIXA extension directory...
mkdir: directory "php-5.4.1/ext/lixa" created
"config.m4" -> "php-5.4.1/ext/lixa/config.m4"
"lixa.c" -> "php-5.4.1/ext/lixa/lixa.c"
"php_lixa.h" -> "php-5.4.1/ext/lixa/php_lixa.h"
mkdir: directory "php-5.4.1/ext/lixa/tests" created
"tests/Makefile" -> "php-5.4.1/ext/lixa/tests/Makefile"
"tests/Makefile.am" -> "php-5.4.1/ext/lixa/tests/Makefile.am"
"tests/Makefile.in" -> "php-5.4.1/ext/lixa/tests/Makefile.in"
"tests/lixa_001.phpt" -> "php-5.4.1/ext/lixa/tests/lixa_001.phpt"
"tests/lixa_002.phpt" -> "php-5.4.1/ext/lixa/tests/lixa_002.phpt"
"tests/lixa_011.phpt" -> "php-5.4.1/ext/lixa/tests/lixa_011.phpt"
"tests/lixa_012.phpt" -> "php-5.4.1/ext/lixa/tests/lixa_012.phpt"
"tests/lixa_021.phpt" -> "php-5.4.1/ext/lixa/tests/lixa_021.phpt"
"tests/lixa_022.phpt" -> "php-5.4.1/ext/lixa/tests/lixa_022.phpt"
"tests/lixa_023.phpt" -> "php-5.4.1/ext/lixa/tests/lixa_023.phpt"
Checking if the downloaded PHP source code can be patched...
File lixa-php-5.4.1-patch.diff exists, trying patch command...
patching file php-5.4.1/ext/mysqli/mysqli_api.c
patching file php-5.4.1/ext/mysqli/mysqli_nonapi.c
patching file php-5.4.1/ext/mysqli/php_mysqli_structs.h
patching file php-5.4.1/ext/pgsql/pgsql.c
Patching PHP source code...
patching file php-5.4.1/ext/mysqli/mysqli_api.c
patching file php-5.4.1/ext/mysqli/mysqli_nonapi.c
patching file php-5.4.1/ext/mysqli/php_mysqli_structs.h
patching file php-5.4.1/ext/pgsql/pgsql.c
PHP source code successfully patched!
Removing php-5.4.1/configure and some stuff...
"php-5.4.1/configure" removed
Creating new configure script...
Forcing buildconf
Removing configure caches
buildconf: checking installation...
buildconf: autoconf version 2.65 (ok)
rebuilding configure
rebuilding main/php_config.h.in
Checking configure recognize LIXA extension...
--with-lixa=FILE Include LIXA support. File is the path to lixa-config program
--enable-lixa-swig Generate LIXA wrapper using SWIG
************************************************************************
PHP source code in directory php-5.4.1 is ready for build and deploy;
use --with-lixa=/opt/lixa/bin/lixa-config (or different path if you
not using LIXA default path) to enable LIXA extension for PHP
use --enable-lixa-swig if you want to generate LIXA PHP wrapper from
scratch using SWIG software (this should not be necessary most times)
************************************************************************
|
Script download_and_patch.sh is configured with a default PHP version, but it may happen you need to download, patch, build and install a different version. Pass the desired PHP version as the first argument to command download_and_patch.sh:
./download_and_patch.sh 5.4.3
These are the steps performed by the script:
download PHP tarball using wget from http://docs.php.net/
if bunzip2 is installed,
.tar.bz2 will be downloaded;
if gunzip is installed,
.tar.gz will be downloaded;
extract tarball locally
create php-X.Y.Z/ext/lixa directory and
populate it with config.m4 lixa.c lixa.php
php_lixa.h
patch PHP Zend source code
clean-up PHP build environment (rm -vf configure autom4te.cache/*)
reset PHP build environment (./buildconf --force)
check PHP build is LIXA enabled (./configure --help | grep lixa)
You are now ready to run configure specifying all the desired values; you should refer to official Zend documentation “Installation and Configuration” and “PHP at the Core: A Hacker's Guide to the Zend Engine” to retrieve all the information necessary to build your own PHP engine starting from the source code.
The command shown in the below table is an example for a test environment; you would probably need something different (HTTP server modules and so on...).
| [Shell terminal session] |
tiian@mojan:~/lixa/ext/php$ cd php-5.4.1 tiian@mojan:~/lixa/ext/php/php-5.4.1$ nice ./configure --enable-debug \ > --enable-maintainer-zts --enable-cgi --enable-cli --enable-shared \ > --with-mysqli=/usr/bin/mysql_config --with-pgsql \ > --with-oci8=/usr/lib/oracle/xe/app/oracle/product/10.2.0/server \ > --with-lixa=/opt/lixa/bin/lixa-config \ > --prefix=/opt/php-5.4-lixa |
In case you might want to generate LIXA PHP wrapper source code
using SWIG you
should add --enable-lixa-swig to
configure command line, but most times this
should not be necessary.
Most times the wrapper supplied with LIXA distribution works fine and you don't have to generate a fresh one. Sometimes, a locally generated wrapper does not work due to some SWIG issue.
The --enable-lixa-swig option is basically
designed for LIXA maintainers.
LIXA software must be compiled and installed with all the Resource Managers you want to use from PHP. If you did not configure and install LIXA for MySQL, you would not be able to use MySQL from PHP as a Resource Manager coordinated by LIXA Transaction Manager. The same is true for PostgreSQL, Oracle, and so on...
Use command /opt/lixa/bin/lixa-config -r to discover which Resource Managers can be used by your installed LIXA software.
After configure you must proceed with make and make install; please refer to “Installation on Unix systems” for the details related to PHP installation. This is what should happen with make:
| [Shell terminal session] |
tiian@mojan:~/lixa/ext/php$ cd php-5.4.1 tiian@mojan:~/lixa/ext/php/php-5.4.1$ nice make [...] Generating phar.php Generating phar.phar PEAR package PHP_Archive not installed: generated phar will require PHP's phar extension be enabled. directorytreeiterator.inc directorygraphiterator.inc pharcommand.inc clicommand.inc invertedregexiterator.inc phar.inc Build complete. Don't forget to run 'make test'. |
and with make install
| [Shell terminal session] |
tiian@ubuntu:~/lixa/ext/php/php-5.4.1$ sudo nice make install [sudo] password for tiian: Installing PHP CLI binary: /opt/php-5.4-lixa/bin/ Installing PHP CLI man page: /opt/php-5.4-lixa/php/man/man1/ Installing PHP CGI binary: /opt/php-5.4-lixa/bin/ Installing build environment: /opt/php-5.4-lixa/lib/php/build/ Installing header files: /opt/php-5.4-lixa/include/php/ Installing helper programs: /opt/php-5.4-lixa/bin/ program: phpize program: php-config Installing man pages: /opt/php-5.4-lixa/php/man/man1/ page: phpize.1 page: php-config.1 Installing PEAR environment: /opt/php-5.4-lixa/lib/php/ [PEAR] Archive_Tar - installed: 1.3.7 [PEAR] Console_Getopt - installed: 1.3.0 [PEAR] Structures_Graph- installed: 1.0.4 [PEAR] XML_Util - installed: 1.2.1 [PEAR] PEAR - installed: 1.9.4 Wrote PEAR system config file at: /opt/php-5.4-lixa/etc/pear.conf You may want to add: /opt/php-5.4-lixa/lib/php to your php.ini include_path /home/tiian/lixa/ext/php/php-5.4.1/build/shtool install -c ext/phar/phar.phar /opt/php-5.4-lixa/bin ln -s -f /opt/php-5.4-lixa/bin/phar.phar /opt/php-5.4-lixa/bin/phar Installing PDO headers: /opt/php-5.4-lixa/include/php/ext/pdo/ |
If everything went right you would build a PHP environment patched for LIXA. It should behaves exactly as a standard PHP environment until you start to use LIXA specific features.
LIXA PHP integration supplies some basic case tests you can execute to verify the build and install process went right.
Move to PHP source root directory and execute the LIXA related tests as shown below:
| [Shell terminal session] |
tiian@mojan:~/lixa/ext/php/php-5.4.1$ TEST_PHP_EXECUTABLE=/opt/php-5.4-lixa/bin/php /opt/php-5.4-lixa/bin/php run-tests.php ext/lixa/tests/ ===================================================================== PHP : /opt/php-5.4-lixa/bin/php PHP_SAPI : cli PHP_VERSION : 5.4.1 ZEND_VERSION: 2.4.0 PHP_OS : Linux - Linux mojan 2.6.32-41-generic #88-Ubuntu SMP Thu Mar 29 13:08:43 UTC 2012 i686 INI actual : /home/tiian/src/lixa/ext/php/php-5.4.1 More .INIs : CWD : /home/tiian/src/lixa/ext/php/php-5.4.1 Extra dirs : VALGRIND : Not used ===================================================================== Running selected tests. PASS LIXA T.M. availability - basic test: the T.M. is up and running [ext/lixa/tests/lixa_001.phpt] PASS LIXA T.M. trivial commit - basic test: a trivial commit transaction [ext/lixa/tests/lixa_002.phpt] PASS LIXA mysqli availability - basic test: MySQL is reachable with mysqli [ext/lixa/tests/lixa_011.phpt] PASS LIXA mysqli integration - a simple transaction using LIXA and MySQL (mysqli driver) [ext/lixa/tests/lixa_012.phpt] PASS LIXA PostgreSQL availability - basic test: PostgreSQL is reachable [ext/lixa/tests/lixa_021.phpt] PASS LIXA pgsql integration - a simple transaction using LIXA and PostgreSQL (pgsql driver) [ext/lixa/tests/lixa_022.phpt] PASS LIXA pgsql mysqli integration - a simple transaction using LIXA, PostgreSQL (pgsql driver) and MySQL (mysqli driver) [ext/lixa/tests/lixa_023.phpt] ===================================================================== Number of tests : 7 7 Tests skipped : 0 ( 0.0%) -------- Tests warned : 0 ( 0.0%) ( 0.0%) Tests failed : 0 ( 0.0%) ( 0.0%) Expected fail : 0 ( 0.0%) ( 0.0%) Tests passed : 7 (100.0%) (100.0%) --------------------------------------------------------------------- Time taken : 2 seconds ===================================================================== |
Pay attention you must specify the PHP installation path twice in command TEST_PHP_EXECUTABLE=/opt/php-5.4-lixa/bin/php /opt/php-5.4-lixa/bin/php run-tests.php ext/lixa/tests/
If you were interested in executing the whole PHP test suite, you would use command make test: the PHP environment would execute all the PHP tests, LIXA supplied too.
Some case tests need specific third party Resource Managers configuration: the same configuration required to run LIXA PHP examples (see the section called “Using LIXA extension for PHP”) is required for the test cases as well.
If you were building a Zend LIXA patched PHP engine, you should pay attention to some specific issues:
it's not mandatory, but it's strongly
suggested you will use a specific verbose installation path
(--prefix=/opt/php-5.4-lixa in the
above example)
to enable LIXA support you must specify something like
--with-lixa=/opt/lixa/bin/lixa-config
(if you didn't install LIXA in default path, you would specify
a different path for lixa-config utility
program)
“mysqli” extension provided by Zend engine can be used with LIXA only if standard MySQL client library is wrapped by mysqli (this is not the defaul behavior in the latest releases of Zend PHP)[1].
You can use something like this to force the usage of standard
MySQL client library instead of “Native Driver”
provided by Zend:
--with-mysqli=/usr/bin/mysql_config
[1] MySQL “Native Driver” can not be used with LIXA because it should be managed as a distinct Resource Manager, not as a standard MySQL one