Previous Next
Using AXMLS
Getting Started

Adodb-xmlschema, or AXMLS, is a set of classes that allow the user to quickly and easily build or upgrade a database on almost any RDBMS using the excellent ADOdb database library and a simple XML formatted schema file. Our goal is to give developers a tool that's simple to use, but that will allow them to create a single file that can build, upgrade, and manipulate databases on most RDBMS platforms.

Installing axmls

The easiest way to install AXMLS to download and install any recent version of the ADOdb database abstraction library. To install AXMLS manually, simply copy the adodb-xmlschema.inc.php file and the xsl directory into your adodb directory.

Using AXMLS in Your Application

There are two steps involved in using AXMLS in your application: first, you must create a schema, or XML representation of your database, and second, you must create the PHP code that will parse and execute the schema.

Let's begin with a schema that describes a typical, if simplistic user management table for an application.

<?xml version="1.0"?>
<schema version="0.2">

  <table name="users">
    <desc>A typical users table for our application.</desc>
    <field name="userId" type="I">
      <descr>A unique ID assigned to each user.</descr>
      <KEY/>
      <AUTOINCREMENT/>
    </field>
    
    <field name="userName" type="C" size="16"><NOTNULL/></field>
    
    <index name="userName">
      <descr>Put a unique index on the user name</descr>
      <col>userName</col>
      <UNIQUE/>
    </index>
  </table>
  
  <sql>
    <descr>Insert some data into the users table.</descr>
    <query>insert into users (userName) values ( 'admin' )</query>
    <query>insert into users (userName) values ( 'Joe' )</query>
  </sql>
</schema>			

Let's take a detailed look at this schema.

The opening <?xml version="1.0"?> tag is required by XML. The <schema> tag tells the parser that the enclosed markup defines an XML schema. The version="0.2" attribute sets the version of the AXMLS DTD used by the XML schema.

All versions of AXMLS prior to version 1.0 have a schema version of "0.1". The current schema version is "0.2".

<?xml version="1.0"?>
<schema version="0.2">
  ...
</schema>

Next we define one or more tables. A table consists of a fields (and other objects) enclosed by <table> tags. The name="" attribute specifies the name of the table that will be created in the database.

<table name="users">

    <desc>A typical users table for our application.</desc>
    <field name="userId" type="I">
      <descr>A unique ID assigned to each user.</descr>
      <KEY/>
      <AUTOINCREMENT/>
    </field>
    
    <field name="userName" type="C" size="16"><NOTNULL/></field>
    
</table>

This table is called "users" and has a description and two fields. The description is optional, and is currently only for your own information; it is not applied to the database.

The first <field> tag will create a field named "userId" of type "I", or integer. (See the ADOdb Data Dictionary documentation for a list of valid types.) This <field> tag encloses two special field options: <KEY/>, which specifies this field as a primary key, and <AUTOINCREMENT/>, which specifies that the database engine should automatically fill this field with the next available value when a new row is inserted.

The second <field> tag will create a field named "userName" of type "C", or character, and of length 16 characters. The <NOTNULL/> option specifies that this field does not allow NULLs.

There are two ways to add indexes to a table. The simplest is to mark a field with the <KEY/> option as described above; a primary key is a unique index. The second and more powerful method uses the <index> tags.

<table name="users">
  ...
    
  <index name="userName">
    <descr>Put a unique index on the user name</descr>
    <col>userName</col>
    <UNIQUE/>
  </index>
    
</table>

The <index> tag specifies that an index should be created on the enclosing table. The name="" attribute provides the name of the index that will be created in the database. The description, as above, is for your information only. The <col> tags list each column that will be included in the index. Finally, the <UNIQUE/> tag specifies that this will be created as a unique index.

Finally, AXMLS allows you to include arbitrary SQL that will be applied to the database when the schema is executed.

<sql>
  <descr>Insert some data into the users table.</descr>
  <query>insert into users (userName) values ( 'admin' )</query>
  <query>insert into users (userName) values ( 'Joe' )</query>
</sql>

The <sql> tag encloses any number of SQL queries that you define for your own use.

Now that we've defined an XML schema, you need to know how to apply it to your database. Here's a simple PHP script that shows how to load the schema.

<?PHP
/* You must tell the script where to find the ADOdb and
 * the AXMLS libraries.
 */
require( "path_to_adodb/adodb.inc.php");
require( "path_to_adodb/adodb-xmlschema.inc.php" );

/* Configuration information. Define the schema filename,
 * RDBMS platform (see the ADODB documentation for valid
 * platform names), and database connection information here.
 */
$schemaFile = 'example.xml';
$platform = 'mysql';
$dbHost = 'localhost';
$dbName = 'database';
$dbUser = 'username';
$dbPassword = 'password';

/* Start by creating a normal ADODB connection.
 */
$db = ADONewConnection( $platform );
$db->Connect( $dbHost, $dbUser, $dbPassword, $dbName );

/* Use the database connection to create a new adoSchema object.
 */
$schema = new adoSchema( $db );

/* Call ParseSchema() to build SQL from the XML schema file.
 * Then call ExecuteSchema() to apply the resulting SQL to 
 * the database.
 */
$sql = $schema->ParseSchema( $schemaFile );
$result = $schema->ExecuteSchema();
?>

Let's look at each part of the example in turn. After you manually create the database, there are three steps required to load (or upgrade) your schema.

First, create a normal ADOdb connection. The variables and values here should be those required to connect to your database.

$db = ADONewConnection( 'mysql' );
$db->Connect( 'host', 'user', 'password', 'database' );

Second, create the adoSchema object that load and manipulate your schema. You must pass an ADOdb database connection object in order to create the adoSchema object.

$schema = new adoSchema( $db );

Third, call ParseSchema() to parse the schema and then ExecuteSchema() to apply it to the database. You must pass ParseSchema() the path and filename of your schema file.

$schema->ParseSchema( $schemaFile ); 
$schema->ExecuteSchema(); 

Execute the above code and then log into your database. If you've done all this right, you should see your tables, indexes, and SQL.

You can find the source files for this tutorial in the examples directory as tutorial_shema.xml and tutorial.php. See the class documentation for a more detailed description of the adoSchema methods, including methods and schema elements that are not described in this tutorial.

Previous Next
Using AXMLS

Documentation generated on Tue, 27 Jul 2004 20:05:45 -0400 by phpDocumentor 1.3.0RC3