This plugin extends the symfony model generator, based on Propel, to allow a schema to override another one. It also provides a new YAML syntax for defining database schemas, more explicit and more readable. This new syntax is completely backward compatible with symfony's current schema.yml syntax, so installing this plugin will not break your applications.

Developers

License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Other releases

Release 1.0.0 - 18/10/2007

Release 0.9.0 - 05/10/2007

Overview

This plugin extends the symfony model generator, based on Propel, to allow a schema to override another one. Using this plugin, you can add columns, change table names, or the database connection without modifying existing schemas.

It also provides a new optional YAML syntax for defining database schemas, more explicit and more readable than the current one. Finally, this alternative schema syntax adds a few new features to schemas, such as the ability to define a behavior from a schema.

Installation

To install the plugin for a symfony project, the usual process is to use the symfony command line:

Alternatively, if you don't have PEAR installed, you can download the latest package attached to this plugin's wiki page and extract it under your project's plugins/ directory.

Clear the cache to enable the autoloading to find the new classes:

$ php symfony cc

That's it, you are ready to override existing schemas and write schemas with the new syntax.

Customizing an existing schema

Once the plugin is installed, schemas can be customized by other schemas. This is great for plugin schemas, for instance, to allow users to override some of the plugin's schema settings (such as the connection, the table names, etc), or to allow one plugin to extend another plugin.

When building the model, the plugin will look for custom YAML files for each schema, following this rule:

The main difference is that you declare classes, not tables, using the table phpName as a key. If you don't define a tableName, the plugin will determine one automatically based on the phpName using sfInflector::underscore().

This alternative syntax is also more explicit, since you must create entries for classes and columns. But it gets rid of the ugly _attributes hack of the current syntax.

The connection parameter is optional. If it is not set, it will take propel as a default value.

Note that you can define foreign keys either with the usual foreignTable attribute, which expects a table name, or via the new foreignClass attribute, which expects a class name.

Last but not least, all the 'magic' of the current syntax is still there (auto definition of primary keys, foreign keys, i18n tables, etc.).

Once you have defined such a schema, rebuild the model as usual:

$ php symfony propel-build-model

The plugin will recognize the alternative syntax automatically. Note that you can have, in a project, schemas with mixed current and alternative syntax.

Behaviors

The alternative schema syntax allows you to define behaviors directly from the schema itself. To allow the support for these schema behaviors, you must change two lines in the 'Builder Settings' section of your project's propel.ini:

Of course, don't forget to rebuild the model after you modify your schema.

It is also possible to define behaviors in the current syntax if you enabled the custom builder in the propel.ini. Just add a leading underscore before the behaviors key and define behaviors the same a above:

Note: Incidentally, behaviors entered this way are registered both in the model and peer classes, which seems to solve some problems with behaviors (like #1229).

Mixed schemas

The schema customization works whatever the original schema syntax and whatever the custom schemas syntax. This means that you can customize an existing schema with the old syntax using a custom schema with the new syntax, and vice-versa. The plugin will do the conversion internally so that the merge is always possible.

Note that the schema merge is easier to understand when considering the alternative syntax for both the original and the custom schema. In fact, this is the internal format used by the plugin for the merge. The following listing is the same example as the one in the "Customizing an existing schema" section, except it uses the alternative schema syntax... and behaviors.

For clarity, it is recommended to use the alternative schema syntax as much as possible.

Checking that the plugin is installed

Alternative schemas can sometimes look like normal YAML schemas. If this plugin is not installed, the usual schema interpreter may try to transform a schema with the alternative syntax into an XML schema, but based on the usual syntax. This will most probably cause problems.

To avoid this, you should check that the plugin is installed before trying to interpret an alternative YAML schema. To do so, a good trick is to take advantage of the fact that YAML files are executed as PHP files before being converted to arrays. So add the following line on top of every alternative YAML schema:

<?php if(!is_callable(array('sfPropelDatabaseSchema', 'convertOldToNewYaml'))) throw new Exception('You must install the sfPropelAlternativeSchemaPlugin to use this schema') ?>

Todo

Refactor sfPropelDatabaseSchema to use the new schema syntax internally

Changelog

Trunk

2007-10-18 | 1.0.0 Stable

francois: Added support for behaviors in the old syntax, too

francois: Added new/old YAML syntax conversion. It is now possible to customize an old schema even if it doesn't use the alternative syntax.

francois: Added a fix for the too late initialization of behaviors in symfony when adding hooks to custom class

francois: Added a way to define behaviors from the schema

francois: Added a new foreignClass column attribute to define a foreign key from a phpName rather than from a tableName

francois: Added section about plugin check in README

francois: Fixed a problem with model class names beginning with a lowercase character