eZ components - DatabaseSchema
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. contents:: Table of Contents

Introduction
============

The File components currently contains one class that provides a few often used
filesystem operations that are missing from PHP.

Class overview
==============

This section gives you an overview on all classes, that are intended to be
used directly.

ezcDbSchema
  Contains the structure of a database. A ezcDbSchema object can be created out
  of files containing a description, or directly from the database. A
  ezcDbSchema can also be written to a file in different formats and converted
  to SQL DDL. It is also possible to create a database structure directly from
  an ezcDbSchema object.

ezcDbSchemaComparator
  This class provide an interface for comparing two database schema definitions
  that are stored in the ezcDbSchema class.

ezcDbSchemaDiff
  The ezcDbSchemaDiff::compareSchemas() method returns an object of
  this class. The object can be converted to SQL DDL, stored in a file or can
  be directly applied to a database.

ezcDbSchemaHandlerManager
  This class can be used to register different handlers for reading and writing
  ezcDbSchema and ezcDbSchemaDiff objects. Its functions to create a reader or
  writer are used by the ezcDbSchema and ezcDbSchemaDiff classes to do the real
  work.

ezcDbSchemaValidator
  Provides one method that allows you to validate a ezcDbSchema class. It
  checks whether indexes are on existing columns and if the types are used are
  correct. It provides an easy API so that other validation checks can be
  easily added.

Usage
=====

Creating a Database Schema Definition
-------------------------------------

Databases can be generated from two different types of sources. The first
source is the file, where there are multiple format handlers available. There
is a format for reading/writing XML files, and one for reading/writing files
that store the ezcDbSchema structure in a PHP array. 

The second source are databases directly. With the ezcDbSchema::createFromDb()
method you can create an ezcDbSchema object directly from an already existing
database connection.

.. include:: tutorial_example_01.php
   :literal:

This example shows how to create a database schema from the two different
sources. With the first parameter to ezcDbSchema::createFromFile() you tell the
method which type to use ('xml' or 'array'). The second parameter is the file
that you are reading the schema definition from.

The ezcDbSchema::createFromDb() method has only one parameter. This parameter
is an ezcDbHandler object that was created with the ezcDbFactory.

In both cases the methods will return an object of the class ezcDbSchema. The
documentation for ezcDbSchemaHandlerManager documents the supported types of
readers and writers. The ezcDbSchema->getSchema() method returns the schema as
an array of ezcDbSchemaTable objects. The ezcDbSchemaTable object then contains
in two member variables an array of ezcDbSchemaField objects to describe the
fields and an array of ezcDbSchemaIndex objects to describe the indices.

Modifying a Database Schema Definition
--------------------------------------

Once a ezcDbSchema has been created its tables and fields can be manipulated in
different ways. Tables can be created, edited and deleted. Fields can be added
to tables, can be edited and deleted. See example below:

.. include:: tutorial_example_05.php
   :literal:

Saving a Database Schema Definition
-----------------------------------

Once a ezcDbSchema has been created it can be manipulated in whatever way you
prefer. After manipulation there are different possibilities to save the
database schema. The ezcDbSchema->writeToFile() method stores an ezcDbSchema
object to a file on disk. Again you can use the xml and array formats. This you
can see in the first part of this example:

.. include:: tutorial_example_02.php
   :literal:

The second and third methods both deal with a database directly. The second
method in the example uses the database connection $db for creating a schema.
The method will not touch any other table besides the ones in the schema
definition. The schemas that are defined will be overwritten. 

The third method merely uses the database connection to determine which SQL DLL
dialect to use while creating the SQL that can be used to create the schema in
the database.

Comparing Database Schemas
--------------------------

The ezcDbSchemaComparator class provides the
ezcDbSchemaComparator::compareSchemas() method to compare two different
ezcDbSchema objects. The result of this operation is an ezcDbSchemaDiff object.
The next example illustrates this:

.. include:: tutorial_example_03.php
   :literal:

First we create the two different schemas. One from the database, and one from
a file. In line 10 we utilize the ezcDbSchemaComparator::compareSchemas()
function to compare the two schemas. This process returns the differences as
the $diffSchema variable.

Again there are multiple ways of doing something "useful" with the generated
differences. These three methods are explained with the inline comments in the
above example.

Validating Schemas
------------------

The last feature that the DatabaseSchema component offers is the validation of
schemas. The ezcDbSchemaValidator::validate() method accepts an ezcDbSchema
object and returns an array of strings describing eventual problems with the
schema. The next example shows this:

.. include:: tutorial_example_04.php
   :literal:



..
   Local Variables:
   mode: rst
   fill-column: 79
   End: 
   vim: et syn=rst tw=79