eZ Component: DatabaseSchema, Requirements ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*:Author:* *:Revision:* *:Date:* Introduction ============ This document describes an API for direct schema manipulation. All the functionality needed for this API is already present in the component. Also the described use case can be solved with the current implementation, but requires knowledge about the internal implementation of the component. The proposed API allows to use the component for schema manipulation, but does not require knowledge about internal implementation. It also helps to avoid programming errors by exposing only methods instead of data structures. Current implementation ---------------------- Database schemas can be manipulated by applying ezcDbSchemaDiff objects on the schema. Instances of ezcDbSchemaDiff can be retrieved by loading an XML structure or by calculating the Diff of two schemes. The construction of an ezcDbSchemaDiff object "on the fly" seems not to be intended by the current implementation. An example of such a creation would be: new ezcDbSchemaDiff( array( $name => new ezcDbSchemaTable( array( // type len notNull default autoInc unsigned 'content_object_id' => new ezcDbSchemaField( 'integer', 0, TRUE, 0, FALSE, TRUE ), 'version' => new ezcDbSchemaField( 'integer', 0, TRUE, 0, FALSE, TRUE ), 'locale' => new ezcDbSchemaField( 'text', 255, TRUE, '', FALSE, TRUE ), 'name' => new ezcDbSchemaField( 'text', 255, TRUE, '', FALSE, TRUE ), 'creator_id' => new ezcDbSchemaField( 'text', 255, TRUE, '', FALSE, TRUE ), 'created' => new ezcDbSchemaField( 'timestamp', 0, TRUE, 0, FALSE, TRUE ), 'published' => new ezcDbSchemaField( 'timestamp', 0, FALSE, 0, FALSE, TRUE ) ), // Indexes array( 'primary' => new ezcDbSchemaIndex( array( 'content_object_id' => new ezcDbSchemaIndexField(), 'version' => new ezcDbSchemaIndexField(), 'locale' => new ezcDbSchemaIndexField() ), TRUE, TRUE // primary, unique ), 'name' => new ezcDbSchemaIndex( array( 'name' => new ezcDbSchemaIndexField() ), FALSE, FALSE // primary, unique ), ) ))); Problems with the current implementation: - The user needs many informations: class names, constructor parameters - Column types are specified with strings instead of constants. Therefor typos are not found as soon as possible. - The interface is very verbose. Requirements ============ The API for schema manipulation should fullfil the following requirements: less verbosity -------------- The API should provide default values for most options, so that the user needs to specify only those options, which deviate from the defaults. This is not fullfilled by the current implementation, even if the __constructor methods have default values. If an option at the end of the parameter list needs to be changed, then all other parameters must also be given. hiding the internal implementation ---------------------------------- The user now needs to access public properties of four or five different classes. This means, that client code becomes very sensible to changes of the internal implementation of DatabaseSchema. This could be avoided by providing one dedicated class ment to build a diff object. help to avoid errors -------------------- By providing constants for the different options, errors can be found already on PHP compile time instead of execution time. Constants should be given for example to indicate sorting order, column type and index type. easy to use ----------- The API should be intuitive and easy to use. It could help to name methods and properties according to SQL syntax. -- Thomas Koch, Software Developer http://www.koch.ro Young Media Concepts GmbH Sonnenstr. 4 CH-8280 Kreuzlingen Switzerland Tel +41 (0)71 / 508 24 86 Fax +41 (0)71 / 560 53 89 Mobile +49 (0)170 / 753 89 16 Web www.ymc.ch -- Components mailing list Components@lists.ez.no http://lists.ez.no/mailman/listinfo/components