eZ Components - PersistentObjectDatabaseSchemaTiein
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. contents:: Table of Contents

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

The PersistentObjectDatabaseSchemaTiein component allows you to generate 
template PersistentObject definition files from a database structure or a
DatabaseSchema schema file. You will most likely have to adjust the
PersistentObject definitions afterwards.

For more information regarding PersistentObject definition files, please refer
to the API documentation for ezcPersistentObjectDefinition. Details on
DatabaseSchema files can be found in the documentation for ezcDbSchema.

Synopsis
========

::

    $ php rungenerator.php -s <string> -f <string> [-h] [--] <target_directory>

The component contains an executable script, which can be called using the PHP
command line interpreter (CLI). You have to provide two options:

-s / --source <string>
  This option determines the source DatabaseSchema file from which to generate
  the PersistentObject definitions.
-f / --format <string>
  This option determines the format of the provided source schema file.
  Examples are 'xml' and 'array'. For a full list of valid formats, please
  refer to the `DatabaseSchema API`_ documentation.

.. _`DatabaseSchema API`: classtrees_DatabaseSchema.html

There is also a help option available that can be accessed with -h or 
--help. 

The 'target_directory' argument specifies the directory where the
PersistentObject definitions are stored. Make sure that script can write to
this target directory. 
 

Usage
=====

Run the script from the main eZ Components source directory using the following
command::

    $ php PersistentObjectDatabaseSchemaTiein/rungenerator.php

By default, you will see a short help description on how to use this tool. 

You need a valid DatabaseSchema file for your database structure to generate 
PersistentObject definitions. You can generate a DatabaseSchema file from
your database with the DatabaseSchema component. For detailed
information, please refer to the `DatabaseSchema API`_ documentation.

Once you have a valid DatabaseSchema file, you should create a directory
where your PersistentObject definitions will be stored. Then you can use the
rungenerator.php script to create the template definition files. Use the following
command::

    $ php PersistentObjectDatabaseSchemaTiein/rungenerator.php \
        -s path/to/schema.file -f array path/to/persistentobject/definition/dir/

You have to replace the paths according to the example. The -s parameter
defines where the DatabaseSchema definition file can be found. The -f option
indicates the format of the schema file. In this case, it is a PHP array
definition; another common format is XML. The last part of the command line
call specifies the target directory to store the generated PersistentObject
definitions.

Customizing definitions
=======================

The generator script assumes that the names of your PersistentObject classes
and their properties map exactly to the same table and column names of your database
structure. For example, a table called ez_persistent_objects with the column
persistent_object_id results in a class ez_persistent_objects and the property
persistent_object_id. 

If you want a different mapping, you can edit the generated
PersistentObject files manually. The class to table name mapping is done
through the properties of the main ezcPersistentObjectDefinition object. The
"table" property should be correct as it is taken from the database definition.
Adjust the "class" property according to your needs.

*Note*: If you change the class name of a PersistentObject definition, you have
to rename the file name accordingly. The file name for a PersistentObject
definition must be the same as the class name, completely in lowercase.

The same procedure applies to the property definition of your
persistent objects. The column name for object property mapping is defined by the
ezcPersistentObjectProperty class. The "columnName" property of the definition
objects should be correct as it is taken from your database schema
file. You can adjust the "propertyName" properties according to your needs.

The generator script guesses the PHP types of your PersistentObject properties.
It uses the following mapping:

:integer:   ezcPersistentObjectProperty::PHP_TYPE_INT
:timestamp: ezcPersistentObjectProperty::PHP_TYPE_INT
:float:     ezcPersistentObjectProperty::PHP_TYPE_FLOAT
:decimal:   ezcPersistentObjectProperty::PHP_TYPE_FLOAT
:text:      ezcPersistentObjectProperty::PHP_TYPE_STRING
:time:      ezcPersistentObjectProperty::PHP_TYPE_STRING
:date:      ezcPersistentObjectProperty::PHP_TYPE_STRING
:blob:      ezcPersistentObjectProperty::PHP_TYPE_STRING
:clob:      ezcPersistentObjectProperty::PHP_TYPE_STRING

If the mappings are incorrect, you can adjust the "propertyType" properties of
your ezcPersistentObjectProperty definitions.


More information
================

For more information, see the API documentation of
ezcPersistentObjectDefinition_, ezcPersistentObjectProperty_,
ezcDbSchema_ and ezcDbschemaPersistentWriter_.

.. _ezcPersistentObjectDefinition: PersistentObject/ezcPersistentObjectDefinition.html
.. _ezcPersistentObjectProperty: PersistentObject/ezcPersistentObjectProperty.html
.. _ezcDbSchema: DatabaseSchema/ezcDbSchema.html
.. _ezcDbSchemaPersistentWriter: DatabaseSchema/ezcDbschemaPersistentWriter.html


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