Instantiating a client

The omixed server is allows the design, generation, population, and management remote databases entirely via web services.  The PHP client is one of many clients written for it.

The omixed PHP library is designed to make accessing the omixed web-service interfaces as simple as possible for the PHP programmer.  It manages both SOAP and REST requests to the server, and encapsulates the more complicated results in a easy-to-use objects.

The client assumes that the server is accessible on port 8080 via http.  If the server is accessible on another port and/or you want to connect via https, you can can invoke the OmixedClient like this:

$client = new OmixedClient("www.omixed.org", "8081", "https");

At this point the client is initialised, but not logged in.  To login, you can use its connect() method.

$client = new OmixedClient("www.omixed.org");
$sessionID = $client->connect("omixed","guest","guest");

The connect method will return a session ID if successful.  If not successful, an exception should be thrown.

If you are building web applications ontop of Apache using this PHP library, you don’t want to be calling connect() on every new page, as this would generate a new server session.  So there needs to be a mechanism to allow a php script to reuse an existing session (assuming it hasn’t timed out).

Two methods are important here: do_not_disconnect_on_destruct() and re_connect().  By default, the client will disconnect() the connection when the object is destroyed, making reconnection using the same sessionID impossible.  To override that behaviour, calling do_not_disconnect_on_destruct() will prevent the the destructor from calling disconnect().

//////////////////////////////////////////////////
// on a login page
//////////////////////////////////////////////////

// get_user_input() is a fictional function (it's not part of the library!)
$host = get_user_input("host");
$resource = get_user_input("resource");
$user = get_user_input("user");
$pass = get_user_input("pass");

// login as normal
$client = new OmixedClient($host);
$sessionID = $client->connect($resource,$user,$pass);

// prevent the client destructor from disconnecting
$client->do_not_disconnect_on_destruct();

// save the user inputs to the session
$_SESSION['login']["host"] = $host;
$_SESSION['login']["resource"] = $resource;
$_SESSION['login']["user"] = $user;
$_SESSION['login']["pass"] = $pass;

If do_not_disconnect_on_destruct() is called, then you can use re_connect() later to reestablish a functional client instance, able to call the server with the session ID set up by a previous instance.

////////////////////////////////////////
// on another, post-login page
//////////////////////////////////////////////////

// gather the session information
$logins = array(
    "host" => $_SESSION['login']["host"],
    "resource" => $_SESSION['login']["resource"],
    "user name" => $_SESSION['login']["user"],
    "password" => $_SESSION['login']["pass"],
    "sessionID" => $_SESSION['login']["sessionID"]
);

// login using re_connect()
$client = new OmixedClient($logins["host"]);
$client->re_connect($logins["resource"],$logins["user name"], $logins["password"],  $logins["sessionID"]);

// don't forget to prevent this new client instance from disconnecting!
$client->do_not_disconnect_on_destruct();