php-orbit 0.0.1
===============

php-orbit is a PHP module for CORBA bindings using ORBit in PHP4.
It is heavily based on the excellent Perl CORBA bindings CORBA::Orbit
from Owen Taylor <otaylor@redhat.com>

PHP is freely availble at
	http://www.php.net/
ORBit homepage at
	http://www.labs.redhat.com/orbit/
a nice page around ORBit at
	http://www.rumpfonline.de/orbit/
CORBA homepage at
	http://www.omg.org/
Information on CORBA::ORBit at
	http://people.redhat.com/otaylor/corba/mapping.html

Please contact me, I need some help! <chtephan@cs.pocnet.net>
--
Christophe

Status
======

The second release. Still needs lots of testing and fixing. Since I didn't
have a good documentation on the Zend/PHP engine... -> trial and error :-/
But it's basically working.

It is a CORBA client side implementation, you can load an IOR into a php
class by creating an new CORBA class and giving the IOR string to the
constructor:

$object = new CORBA($ior);

This should be done after loading an idl file. Therefore you need
a C preprocessor installed (libIDL issue). In the future I'd like to
see a way of dealing with interface descriptions in a persistant way
(so you won't need to parse the idl every time the php script is invoked)

--

// dl('orbit.so'); if used as DSO

orbit_load_idl('test.idl');

// Some exception handling:

function my_exception_handler($arg) {
  global $last_Exception;
  if (substr($arg->_class,0,6) == "CORBA.")
    die("CORBA system exception: ".$arg->text." status: ".$arg->status);
  else
    $last_Exception = $arg;
}
orbit_exception_handler("my_exception_handler"); // required

// Now call functions, get and set attributes, retrieve new object references:

$newobject = $object->get_child();
$object->do_something();
echo "This is the object's name attribute: ".$object->name;
$result = $newobject->calculate("Hello");
$array = array("Hello",1); // idl structure { string name, long count }
$object->get_struct($array);
$class = new StdClass;
$class->name = "Hellos";
$class->count = 2;
$object->get_struct($object); // can also take objects, the values
                              // are retrieved by name, not index
echo $newobject->do_something_with_my_child();

$x = serialize($newobject);
$newobject = unserialize($x); // the reference is kept

// some Typecode stuff

$tc = new CORBA_TypeCode("IDL:CORBA/String:1.0");

// or a typecode from the IDL

$tc2 = new CORBA_TypeCode("IDL:DemoInterface/DemoType:1.0");

// you can also serialize/unserialize them

// let's put a CORBA_Any, the following functions takes a CORBA::Any

$class->take_any(array($tc,"String"));

// you see, anys are: array(TypeCode,Value)

I NEED A BETTER DOCUMENTATION AND EXAMPLE CODE!!! Who wants to contribute?
:-)


Details
=======

Some more details:

- the "local interface repository" is done via the Interface Repository
  objects and structures found in ORBit,
  some fixing of Owens idl.c and interface.c (ORBit reference counting),
  so that the "local interface repository" (interface definitions,
  exceptions, typecodes) can be properly unloaded (I hope so)

- look at TYPEMAP for TypeCode mapping

- object references (for out and inout) must be passed as reference (&$arg)

- the PHP CORBA classes can be serialized and unserialized, the object
  reference will be held correctly (this rocks!)

- I don't think we need a server implementation (POA), so code removed
  or commented out

- did some fixing with system exceptions (ORBit returned CORBA_UNKNOWN,
  but a minor that indicated CORBA_NO_MEMORY?!?) FIXME

- using an (external) interface repository would be nice, but the
  ORBit code is not yet finished

- I am fiddling with ORBit internals, this is because my code is based
  on Owen's CORBA::ORBit which does this and because the ORBit code for
  dii and the Typecode handling in orb.c are still buggy - and of course:
  it's faster! ;-)

- exception handling: a user function is called, that must be registered
  with orbit_exception_handler(function) and which takes the exception as
  argument.
  The exception is contained in a standard class, _class contains the
  "class name", which is like the package name in CORBA::ORBit, but
  the delimiter is a dot (configurable in phorb.h), just like in java.
  So system exceptions always start with "CORBA."
  In system exceptions $arg->text contains the error message, and
  $arg->status the completion status (which is a string at the moment)

- if the module is compiled as a php shared module you will get
  segmentation faults when unloading the moule / ending php.
  This has to do with g_atexit in libIIOP and I also think PHP
  Needs fixing (note: the cvs head version has a skip_atexit or so,
  need to handle that)

- all CORBA classes are mapped to a PHP class named "CLASS".
  "Loading and unloading" php classes in realtime are not (yet?)
  possible in PHP :-(

- TypeCodes are a class named CORBA_TypeCode

- the "delimiter" in class names is a dot just like in java,
  it is used in exceptions

- user exceptions store their arguments directly in the exception object
  passed to the user handler function, reffered by their name.
  The class name is in attribute _class.


Background history
==================

I'm working for six months at a little "internet factory", that primarily
produces dynamic web sites and internet shops in germany.
(Web Commerce http://www.w-commerce.de/ <team@w-commerce.de>)
Our customers have the possibilty to modify their web sites through a
web interface called "Edith". This is a nice web interface to modify
the tables in the database. The forms are dynamically created via
the meta data stored in the database itself, so that the programming
of a new project becomes easier. There are some data types like strings,
list boxes, multiple list boxes, uploads, checkboxes, ...
The index can be searched, new elements inserted and so on.
The bad thing is that it is written in ColdFusion and the code is a whole
mess (since we don't have the time to work on it and it historically grew
with each project)
So we decided to work on a whole new concept with some external help (like
me) and split the logic from the web site and make everything more flexible
BTW: We are currently moving away from NT/ColdFusion/Access and moving
towards Linux/Apache/Mysql/PHP (we hope IBM will also release its WebShere
Commerce Suite for Linux soon).
The new concept will consist of a java server that handles all requests
(that arrive via CORBA) and communicate with a database server via JDBC.
The server will support a sort of a plugin system so you will be able to
register different data types or import/export filters or even a content
management system.
So we have a 4 tier web application serving system:
Browser ---HTTP--- Apache&PHP ---CORBA--- Java ---JDBC--- mySQL/Oracle
We decided to use CORBA as communication language since it's flexible,
easy to use and network transparent (although it will only serve the
local web server at the beginning). Since we like PHP we didn't want to
switch to JSP or something on the web server so I decided to start
writing a PHP CORBA interface and here we are.
I don't know how the project will evolve (it's not sure that it will be
finished) sind I will start studying physics in fall.


Installation
============

- you need: autoconf, automake, libtool (newer versions should work)
            ORBit >= 0.5 (older versions should also work) and libIDL
            PHP 4.0.1pl2

- If you have PHP already installed and want to compile it as a
  php shared module (WARNING: extremely buggy, see comment above):

  * run phpize in current directory
  * run ./configure --with-orbit=/path --with-glib=/path
  * run make
  * run make install

  You should obtain an orbit.so

- You can compile it into php itself: (DON'T REDISTRIBUTE THESE TOGETHER!!!)

  * copy this directory into php-4.0.1.pl2/ext and RENAME IT TO "orbit"
  * run buildconf in php-4.0.1.pl2/
  * run php ./configure with --with-orbit=/path --with-glib=/usr
  * run make
  * as usual

- Good luck!


Documentation
=============

Sorry, none yet. Look at the OMG CORBA homepage or Owen's informations
(and this README and the (not yet existing) test files)


LICENSE
=======

I decided to put it under the LGPL just like Owen but I don't exactly
know how to deal with the PHP license (or even QPL (Zend Engine)argh)
But I plan to include it into the main php tree, so I think I'll have to
put php_orbit.c and co under the PHP license and leave the rest under LGPL.
Does this work? I don't think this is a conflict.

Needs to be overthought!
