|
|
sfPropel15Plugin - 0.9.2Replaces symfony's core Propel plugin by the latest version of Propel, in branch 1.5. |
|
Replaces symfony's core Propel plugin by the latest version of Propel, in branch 1.5.
Install the plugin via the subversion repository:
> svn co http://svn.symfony-project.com/plugins/sfPropel15Plugin/trunk plugins/sfPropel15Plugin
from the project root directory or by using the command:
> ./symfony plugin:install sfPropel15Plugin
Right after the installation of the plugin, you should update plugin assets:
> ./symfony plugin:publish-assets
Disable the core Propel plugin and enable the sfPropel15Plugin instead:
class ProjectConfiguration extends sfProjectConfiguration { public function setup() { $this->enablePlugins('sfPropel15Plugin'); } }
Change the path of the symfony behaviors in the config/propel.ini file of your project:
propel.behavior.symfony.class = plugins.sfPropel15Plugin.lib.behavior.SfPropelBehaviorSymfony propel.behavior.symfony_i18n.class = plugins.sfPropel15Plugin.lib.behavior.SfPropelBehaviorI18n propel.behavior.symfony_i18n_translation.class = plugins.sfPropel15Plugin.lib.behavior.SfPropelBehaviorI18nTranslation propel.behavior.symfony_behaviors.class = plugins.sfPropel15Plugin.lib.behavior.SfPropelBehaviorSymfonyBehaviors propel.behavior.symfony_timestampable.class = plugins.sfPropel15Plugin.lib.behavior.SfPropelBehaviorTimestampable
Propel 1.5 is a backwards compatible evolution of Propel 1.4 (the version bundled with symfony 1.3 and 1.4), which adds some very interesting features. Among these features, you will find the new Propel Query API, which is essentially a Criteria on steroids:
// find the 10 latest books published by authror 'Leo' $books = BookQuery::create() ->useAuthorQuery() ->filterByFirstName('Leo') ->endUse() ->orderByPublishedAt('desc') ->limit(10) ->find($con);
Propel 1.5 also supports many-to-many relationships, collections, on-demand hydration, new core behaviors (see below), better Oracle support, and is now licensed under the MIT license.
Check out the WHATS_NEW page in the Propel trac to see the full list of changes.
Propel 1.5 bundles most common behaviors in a new, robust buildtime implementation. These core behaviors provide faster runtime execution and the ability to modify the data model:
sfPropel15Plugin allows you to register core propel behaviors right from your schema.yml. For instance, to create a tree structure from a Section model:
propel:
section:
_attributes: { phpName: Section }
_propel_behaviors:
- nested_set
id: ~
title: { type: varchar(100), required: true primaryString: true }
Tip: Check the doc/schema.txt file in this plugin source code for a complete reference of the YAML schema format.
You can also register a behavior for all your models right in the propel.ini configuration file. sfPropel15Plugin already enables the symfony and symfony_i18n behaviors to support symfony's behavior system and model localization features, but you can easily add your owns:
propel.behavior.default = symfony,symfony_i18n,alternative_coding_standards,auto_add_pk
The plugin comes bundled with a new admin generator theme named 'admin15'. This theme is backwards compatible with sfPropelPlugin's admin generator theme, and provides additional features based on the new Propel 1.5 query objects:
doSelectJoinXXX() methods to hydrate related objects. The with setting is much more poxwerful that the previous peer_method and peer_count_method settings, and much easier to use.query_methods parameter. This allows to hydrate an additional column wit hno additional query, or to pre-filter the list to hide rows that the user shouldn't see.link_module setting in the foreign key field configuration, and you're good to go:generator.yml format was extended to allow widget and validator customization directly in YAML, without the need to edit a form object. You can also safely omit a field from a display list in a form definition, without any risk to loose data.type: plain attribute, just like in the old days of symfony 1.2. This is very useful for columns managed by the model, like created_at and updated_at columns.The new options for the admin15 generator theme are fully documented, and illustrated by real life examples, in the doc/admin_generator.txt file in this plugin source code.
sfWidgetFormPropelChoice widgetThe sfWidgetFormPropelChoice widget now uses the new Query API. You can customize the list of choices more easily by executing custom query methods, using the new query_methods option. For instance, if the Section model uses the nested_set behavior, you probably want to display a section selection widget in hierarchical order. This is easily achived by execiting the orderByBranch() query method, and you can register it as follows:
class ContentForm extends BaseContentForm { public function configure() { $this->widgetSchema['section'] = new sfWidgetFormPropelChoice(array( 'model' => 'Section', 'query_methods' => array('orderByBranch') 'add_empty' => true, )); } }
In practice, you won't need to build a custom Criteria object to achieve a custom list choice - but it still works:
class ContentForm extends BaseContentForm { public function configure() { $query = SectionQuery::create() ->filterByIsVisible(true); $this->widgetSchema['section'] = new sfWidgetFormPropelChoice(array( 'model' => 'Section', 'criteria' => $query, 'add_empty' => true, )); } }
Both the sfValidatorPropelChoice and the sfValidatorPropelUnique were updated to use the new PropelQuery objects, and to accept a query_methods option similat to the one of sfWidgetFormPropelChoice. So if you display a selection of items using a query method, you can validate this selection, too:
class ContentForm extends BaseContentForm { public function configure() { $this->widgetSchema['section']->setOption('query_methods', array('published')); $this->validatorSchema['section']->setOption('query_methods', array('published')); } }
The two widgets and the validator are fully documented in the doc/form.txt file in this plugin source code.
