
                       PHP and DB XML

IMPORTANT: PHP4 support in DB XML is entirely experimental at this
time, and without committed support.  If you send a support request
for PHP, there is no commitment that the problem will be solved.

The DB XML team would like to eventually be able to support PHP4,
and solicits any assistance that can be provided from the DB XML
and PHP communities.  If you have problems, solutions, suggestions,
comments, please send email to:
  support@sleepycat.com


Those interested in PHP4 and DB XML, read on...

Current State of code
---------------------

The PHP4 wrapper code in this directory is first generated by SWIG
(www.swig.org), from files in <install_dir>/dist/swig, using
the script, <install_dir>/dist/s_swig.  The generated file,
config.m4 is then *modified*.  This means that if you regenerate
the code using SWIG, you will overwrite config.m4,
and you're on your own for building the module.  A copy of the 
modified config.m4 file is provided as config.m4.dbxml for recovery purposes.

config.m4, is modified to include statements
that help locate the shared libraries required for the module to
build, load and run.  After modification, the command, phpize,
is used to create an environment that can be used to build
the extension module.  The module is configured to be dynamically loaded
into PHP.  If you want to build this directly into your
php executable, you're in new territory.

The result of phpize is what is shipped in this directory, with
some trimming of unnecessary files.  The
phpize was done on Linux, using an installation of PHP 4.3.4.

The only files in this directory that are *not* automatically generated are:
  config.m4, config.m4.dbxml (these are modified based on generated files)
  dbxml_example.php

Therefore, you should not modify any other files unless
you really know what you are doing.

Building
--------

At this time, the build has only been done on Linux, using PHP 4.3.4.
However, with luck, it will build/run on other platforms.  If you
have a favorite, and can get something going, please let us know.

Building is simple.  In this directory:
  $  ./configure
  $  make
  $  make install (this may require root privilege, as it puts
          the resulting shared library into the local PHP installation's
	  extension directory).

There are 4 dependent libraries.  The configure script expects to find
them installed in these locations:
  DB XML:  /usr/local/BerkeleyDBXML.1.2
  Berkeley DB:  /usr/local/BerkeleyDB.4.2
  Pathan 1.2: /usr/local
  Xerces 2.4: /usr/local

You can specify alternate locations using:
  --with-dbxml_dir="path_to_dbxml_install"
  --with-berkeleydb="path_to_db_install"
  --with-pathan="path_to_pathan_install"
  --with-xerces="path_to_xerces_install"

These are the same as the "--with-*" directives used to build DB XML
itself.

If you have access to SWIG, and want to experiment with code generation
and building from scratch, by all means, do so, and let us know the
results.

Running
-------

A very simple example is include here, dbxml_example.php.  If everything
is installed correctly -- the PHP module, DB XML and other libraries,
and your LD_LIBRARY_PATH (for example) includes the necessary directories,
you can run the script:
   php dbxml_example.php
It should print out what it's doing.  It's short.

Again, this is only known to work on Linux at this time.
There has been no testing at all using PHP scripts 
behind a web server, as is intended with PHP.

Writing your own scripts
------------------------

It is assumed that if you have gotten this far, you are familiar
with PHP scripting.  Some interesting things to note on 
PHP Syntax using DB XML's SWIG-generated wrapper:
  o NULL is passed using the string, "NULL"
  o PHP doesn't support function overloads, so all arguments must
    be passed, even what would be defaults in C++ or other script.
  o Class instances are created using $instance = new MyClass(arguments);
  o Class functions are referenced by $instance->functionName();
  o PHP takes care of deletion of objects (there does not
    appear to be any way to delete in a script).
