Skip to content
This repository
Newer
Older
100644 235 lines (173 sloc) 12.001 kb
8e6722e5 » willdurand
2011-08-10 Updated README
1 sfPropelORMPlugin
2 =================
a0ecb20c » fzaninotto
2011-02-16 [1.6] Markdown is more natural and easier to read than RST, reverting…
3
8e6722e5 » willdurand
2011-08-10 Updated README
4 Replaces symfony's core Propel plugin by the latest version of Propel, in branch 1.6.
a0ecb20c » fzaninotto
2011-02-16 [1.6] Markdown is more natural and easier to read than RST, reverting…
5
8e6722e5 » willdurand
2011-08-10 Updated README
6 ## Installation
7
8 ### The Git way
9
10 Clone the plugin from Github:
11
12 git clone git://github.com/propelorm/sfPropelORMPlugin.git plugins/sfPropelORMPlugin
13 cd plugins/sfPropelORMPlugin
d2372a07 » willdurand
2011-08-20 Fixed git typo
14 git submodule update --init
8e6722e5 » willdurand
2011-08-10 Updated README
15
16 If you use Git as a VCS for your project, it should be better to add the plugin as a submodule:
17
18 git submodule add git://github.com/propelorm/sfPropelORMPlugin.git plugins/sfPropelORMPlugin
b52f1fea » willdurand
2011-08-22 Updated README
19 git submodule update --init --recursive
8e6722e5 » willdurand
2011-08-10 Updated README
20
21 As both Phing and Propel libraries are bundled with the plugin, you have to initialize submodules for the plugin.
22
23 ### The SVN way
a0ecb20c » fzaninotto
2011-02-16 [1.6] Markdown is more natural and easier to read than RST, reverting…
24
25 Install the plugin via the subversion repository:
26
8e6722e5 » willdurand
2011-08-10 Updated README
27 svn checkout http://svn.github.com/propelorm/sfPropelORMPlugin.git plugins/sfPropelORMPlugin
28
29 Install `Phing` and `Propel`:
30
b52f1fea » willdurand
2011-08-22 Updated README
31 svn checkout http://phing.mirror.svn.symfony-project.com/tags/2.3.3/classes/phing lib/vendor/phing
32 svn checkout http://svn.github.com/propelorm/Propel.git lib/vendor/propel
a0ecb20c » fzaninotto
2011-02-16 [1.6] Markdown is more natural and easier to read than RST, reverting…
33
b52f1fea » willdurand
2011-08-22 Updated README
34 ### Final step
35
36 Disable the core Propel plugin and enable the `sfPropelORMPlugin` instead:
a3edbd5d » lucasaba
2011-08-22 Ads cleanliness to the code
37
38 ``` php
b52f1fea » willdurand
2011-08-22 Updated README
39 // config/ProjectConfiguration.class.php
a3edbd5d » lucasaba
2011-08-22 Ads cleanliness to the code
40
41 class ProjectConfiguration extends sfProjectConfiguration
42 {
43 public function setup()
44 {
b52f1fea » willdurand
2011-08-22 Updated README
45 // If you're following the SVN way, uncomment the next two lines
46 //sfConfig::set('sf_phing_path', sfConfig::get('sf_root_dir').'/lib/vendor/phing');
47 //sfConfig::set('sf_propel_path', sfConfig::get('sf_root_dir').'/lib/vendor/propel');
a0977c18 » toaotc
2012-03-29 added missing propel generator config path for SVN way
48 //sfConfig::set('sf_propel_generator_path', sfConfig::get('sf_root_dir').'/lib/vendor/propel/generator/lib');
b52f1fea » willdurand
2011-08-22 Updated README
49
50 $this->enablePlugins('sfPropelORMPlugin');
a3edbd5d » lucasaba
2011-08-22 Ads cleanliness to the code
51 }
b52f1fea » willdurand
2011-08-22 Updated README
52 }
a3edbd5d » lucasaba
2011-08-22 Ads cleanliness to the code
53 ```
54
b52f1fea » willdurand
2011-08-22 Updated README
55 **Optional:** update references to the `propel` and `phing` folders in the test project.
a0ecb20c » fzaninotto
2011-02-16 [1.6] Markdown is more natural and easier to read than RST, reverting…
56
8e6722e5 » willdurand
2011-08-10 Updated README
57 ``` php
b52f1fea » willdurand
2011-08-22 Updated README
58 // plugins/sfPropelORMPlugin/test/functional/fixtures/config/ProjectConfiguration.class.php
a0ecb20c » fzaninotto
2011-02-16 [1.6] Markdown is more natural and easier to read than RST, reverting…
59
8e6722e5 » willdurand
2011-08-10 Updated README
60 class ProjectConfiguration extends sfProjectConfiguration
61 {
4878b506 » willdurand
2011-08-18 Fixed README
62 public function setup()
63 {
b52f1fea » willdurand
2011-08-22 Updated README
64 $this->enablePlugins(array('sfPropelORMPlugin'));
65 $this->setPluginPath('sfPropelORMPlugin', realpath(dirname(__FILE__) . '/../../../..'));
66
059da3ea » willdurand
2011-08-22 Fixed tests
67 // SVN way
68 //sfConfig::set('sf_propel_path', SF_DIR.'/../lib/vendor/propel');
69 //sfConfig::set('sf_phing_path', SF_DIR.'/../lib/vendor/phing');
70
71 // Git way
72 sfConfig::set('sf_propel_path', realpath(dirname(__FILE__) . '/../../../../lib/vendor/propel'));
73 sfConfig::set('sf_phing_path', realpath(dirname(__FILE__) . '/../../../../lib/vendor/phing'));
4878b506 » willdurand
2011-08-18 Fixed README
74 }
8e6722e5 » willdurand
2011-08-10 Updated README
75 ```
a0ecb20c » fzaninotto
2011-02-16 [1.6] Markdown is more natural and easier to read than RST, reverting…
76
4878b506 » willdurand
2011-08-18 Fixed README
77 Right after the installation of the plugin, you should update plugin assets:
78
79 php symfony plugin:publish-assets
80
a0ecb20c » fzaninotto
2011-02-16 [1.6] Markdown is more natural and easier to read than RST, reverting…
81 Change the path of the symfony behaviors in the `config/propel.ini` file of your project:
82
8e6722e5 » willdurand
2011-08-10 Updated README
83 ``` ini
84 // config/propel.ini
85
86 propel.behavior.symfony.class = plugins.sfPropelORMPlugin.lib.behavior.SfPropelBehaviorSymfony
87 propel.behavior.symfony_i18n.class = plugins.sfPropelORMPlugin.lib.behavior.SfPropelBehaviorI18n
88 propel.behavior.symfony_i18n_translation.class = plugins.sfPropelORMPlugin.lib.behavior.SfPropelBehaviorI18nTranslation
89 propel.behavior.symfony_behaviors.class = plugins.sfPropelORMPlugin.lib.behavior.SfPropelBehaviorSymfonyBehaviors
90 propel.behavior.symfony_timestampable.class = plugins.sfPropelORMPlugin.lib.behavior.SfPropelBehaviorTimestampable
91 ```
a0ecb20c » fzaninotto
2011-02-16 [1.6] Markdown is more natural and easier to read than RST, reverting…
92
93 (Re)Build the model:
94
8e6722e5 » willdurand
2011-08-10 Updated README
95 php symfony propel:build --all-classes
96
a0ecb20c » fzaninotto
2011-02-16 [1.6] Markdown is more natural and easier to read than RST, reverting…
97
8e6722e5 » willdurand
2011-08-10 Updated README
98 ## What's New In Propel 1.6
a0ecb20c » fzaninotto
2011-02-16 [1.6] Markdown is more natural and easier to read than RST, reverting…
99
8e6722e5 » willdurand
2011-08-10 Updated README
100 Propel 1.6 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:
a0ecb20c » fzaninotto
2011-02-16 [1.6] Markdown is more natural and easier to read than RST, reverting…
101
8e6722e5 » willdurand
2011-08-10 Updated README
102 ``` php
103 // find the 10 latest books published by authror 'Leo'
104 $books = BookQuery::create()
105 ->useAuthorQuery()
106 ->filterByFirstName('Leo')
107 ->endUse()
108 ->orderByPublishedAt('desc')
109 ->limit(10)
110 ->find($con);
111 ```
a0ecb20c » fzaninotto
2011-02-16 [1.6] Markdown is more natural and easier to read than RST, reverting…
112
8e6722e5 » willdurand
2011-08-10 Updated README
113 Propel 1.6 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.
a0ecb20c » fzaninotto
2011-02-16 [1.6] Markdown is more natural and easier to read than RST, reverting…
114
115
8e6722e5 » willdurand
2011-08-10 Updated README
116 ## Core Propel Behaviors
a0ecb20c » fzaninotto
2011-02-16 [1.6] Markdown is more natural and easier to read than RST, reverting…
117
8e6722e5 » willdurand
2011-08-10 Updated README
118 Propel 1.6 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:
a0ecb20c » fzaninotto
2011-02-16 [1.6] Markdown is more natural and easier to read than RST, reverting…
119
8e6722e5 » willdurand
2011-08-10 Updated README
120 - [timestampable](http://www.propelorm.org/wiki/Documentation/1.6/Behaviors/timestampable)
121 - [sluggable](http://www.propelorm.org/wiki/Documentation/1.6/Behaviors/sluggable)
122 - [soft_delete]([http://www.propelorm.org/wiki/Documentation/1.6/Behaviors/soft_delete)
123 - [nested_set](http://www.propelorm.org/wiki/Documentation/1.6/Behaviors/nested_set)
124 - [sortable](http://www.propelorm.org/wiki/Documentation/1.6/Behaviors/sortable)
125 - [concrete_inheritance](http://www.propelorm.org/wiki/Documentation/1.6/Inheritance#ConcreteTableInheritance)
126 - [query_cache](http://www.propelorm.org/wiki/Documentation/1.6/Behaviors/query_cache)
9d248d4b » GromNaN
2011-08-19 typo
127 - [alternative_coding_standards](http://www.propelorm.org/wiki/Documentation/1.6/Behaviors/alternative_coding_standards)
8e6722e5 » willdurand
2011-08-10 Updated README
128 - [auto_add_pk](http://www.propelorm.org/wiki/Documentation/1.6/Behaviors/auto_add_pk)
a0ecb20c » fzaninotto
2011-02-16 [1.6] Markdown is more natural and easier to read than RST, reverting…
129
8e6722e5 » willdurand
2011-08-10 Updated README
130 `sfPropelORMPlugin` allows you to register core propel behaviors right from your `schema.yml`. For instance, to create a tree structure from a `Section` model:
a0ecb20c » fzaninotto
2011-02-16 [1.6] Markdown is more natural and easier to read than RST, reverting…
131
8e6722e5 » willdurand
2011-08-10 Updated README
132 ``` yaml
133 propel:
134 section:
135 _attributes: { phpName: Section }
136 _propel_behaviors:
137 - nested_set
138 id: ~
139 title: { type: varchar(100), required: true primaryString: true }
140 ```
a0ecb20c » fzaninotto
2011-02-16 [1.6] Markdown is more natural and easier to read than RST, reverting…
141
8e6722e5 » willdurand
2011-08-10 Updated README
142 **Tip**: Check the [`doc/schema.md`](https://raw.github.com/propelorm/sfPropelORMPlugin/master/doc/schema.md) file in this plugin source code for a complete reference of the YAML schema format.
a0ecb20c » fzaninotto
2011-02-16 [1.6] Markdown is more natural and easier to read than RST, reverting…
143
8e6722e5 » willdurand
2011-08-10 Updated README
144 You can also register a behavior for all your models right in the `propel.ini` configuration file. `sfPropelORMPlugin` 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:
a0ecb20c » fzaninotto
2011-02-16 [1.6] Markdown is more natural and easier to read than RST, reverting…
145
8e6722e5 » willdurand
2011-08-10 Updated README
146 ``` ini
147 propel.behavior.default = symfony,symfony_i18n,alternative_coding_standards,auto_add_pk
148 ```
a0ecb20c » fzaninotto
2011-02-16 [1.6] Markdown is more natural and easier to read than RST, reverting…
149
8e6722e5 » willdurand
2011-08-10 Updated README
150 ## Admin Generator Extensions
a0ecb20c » fzaninotto
2011-02-16 [1.6] Markdown is more natural and easier to read than RST, reverting…
151
8e6722e5 » willdurand
2011-08-10 Updated README
152 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.6 query objects:
a0ecb20c » fzaninotto
2011-02-16 [1.6] Markdown is more natural and easier to read than RST, reverting…
153
154 ### List view enhancements
155
156 - **Easy related objects hydration**: You don't need to write custom `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.
157 - **Custom query methods**: You can refine the query executed to display the list view by by setting the `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.
158 - **All columns are sortable**: Virtual columns and foreign key columns are now sortable in the list view. You'll need to set the sort method to use for that, but it's a one-liner. No more lists with column headers that can't be clicked for sorting!
159 - **Easy links to filtered lists**: A link to a fitlered list view is very easy to write with the new theme. Just add GET parameter, the same way you used to do with the admin generator in symfony 1.2, and it works
160 - **Links to another admin module**: To make a foreign key column link to the edit view of the related object in another module, you no longer need to create a partial. Just define the `link_module` setting in the foreign key field configuration, and you're good to go:
161 - **Easy custom filters**: Adding custom filters becomes very easy once you can take advantage of the generated Propel query classes. This allows your, for instance, to setup a full-text search input in two minutes, replacing many text filters by a single one for better usability.
c9ca969d » garak
2011-09-01 added reference to sortable links
162 - **Automatic sortable links**: If a module is generated on a model with sortable behavior, actions for moving records up and down are automatically added.
a0ecb20c » fzaninotto
2011-02-16 [1.6] Markdown is more natural and easier to read than RST, reverting…
163
164 ### Filter and Edit forms enhancement
165
166 - **YAML widget customization**: The `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.
167 - **Plain text field**: If you want to display some data in a form without allowing the user to edit it, use the `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.
168
8e6722e5 » willdurand
2011-08-10 Updated README
169 The new options for the `admin15` generator theme are fully documented, and illustrated by real life examples, in the [`doc/admin_generator.md`](https://raw.github.com/propelorm/sfPropelORMPlugin/master/doc/admin_generator.md) file in this plugin source code.
a0ecb20c » fzaninotto
2011-02-16 [1.6] Markdown is more natural and easier to read than RST, reverting…
170
8e6722e5 » willdurand
2011-08-10 Updated README
171 ## Form Subframework Modifications
a0ecb20c » fzaninotto
2011-02-16 [1.6] Markdown is more natural and easier to read than RST, reverting…
172
0ba5f543 » rozwell
2011-05-03 Removed trailing spaces
173 - **Updated `sfWidgetFormPropelChoice` widget**: The 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.
a0ecb20c » fzaninotto
2011-02-16 [1.6] Markdown is more natural and easier to read than RST, reverting…
174 - **Updated Propel validators**: Both the `sfValidatorPropelChoice` and the `sfValidatorPropelUnique` were updated to use the new PropelQuery objects, and to accept a `query_methods` option similar to the one of `sfWidgetFormPropelChoice`.
175 - **Plain text widget and validator**: This new widget allows a field to be displayed in a form, without letting the use change it.
176 - **Easy Relation Embed**: Editing related objects together with the main objects (e.g., editing `Comments` in a `Post` form) is a piece of cake. The new `sfFormPropel::embedRelation()` method does all the work to fetch related objects, build the forms for each of them, and embed the related object forms into the main form. Embdeded relation forms allow to **edit**, **add**, and **delete** a related objects with no additional code.
177
8e6722e5 » willdurand
2011-08-10 Updated README
178 ``` php
179 class ArticleForm extends BaseArticleForm
180 {
76a8cf15 » willdurand
2011-08-18 Fixed indentation in README
181 public function configure()
182 {
8e6722e5 » willdurand
2011-08-10 Updated README
183 $this->embedRelation('Book');
76a8cf15 » willdurand
2011-08-18 Fixed indentation in README
184 }
8e6722e5 » willdurand
2011-08-10 Updated README
185 }
186 ```
187
188 The Propel widgets, validators, and form classes are fully documented in the [`doc/form.md`](https://raw.github.com/propelorm/sfPropelORMPlugin/master/doc/form.md) file in this plugin source code.
189
190 ## Routing Modifications
191
192 The plugin offer two new routing classes, `sfPropelORMRoute` and `sfPropelORMRouteCollection`. These classes are used by default in the models build with the propel admin generator. They behave just like the previous `sfPropelRoute` class - except they don't use the `methods` option anymore. Instead, use the `query_methods` option to execute a list of arbitrary query methods when calling `getObject()` and `getObjects()`.
193
194 ``` yaml
195 author:
196 class: sfPropelORMRouteCollection
197 options:
198 model: author
199 module: author
200 prefix_path: /author
201 column: id
202 query_methods:
203 object: [filterByIsPublished]
204 list: [filterByIsPublished, orderByLastName]
205 with_wildcard_routes: true
206 ```
a0ecb20c » fzaninotto
2011-02-16 [1.6] Markdown is more natural and easier to read than RST, reverting…
207
09f08af2 » rozwell
2011-05-03 query methods:
208 Array of additional parameters are also possible for `query_methods`:
209
8e6722e5 » willdurand
2011-08-10 Updated README
210 ``` yaml
211 author:
212 class: sfPropelORMRouteCollection
213 options:
214 model: author
215 module: author
216 prefix_path: /author
217 column: id
218 query_methods:
219 object:
220 filterByIsPublished: [false]
221 list:
222 filterByIsPublished: []
223 orderBy: [LastName]
224 with_wildcard_routes: true
225 ```
226
227 `sfPropelORMRoute` also makes your code a little easier to read in the action. Instead of calling `getObject()`, you can actually call a getter using the class name of the object's route:
228
229 ``` php
230 public function executeShow(sfWebRequest $request)
231 {
232 // using sfPropelORMRoute with 'Author' as model
233 $this->author = $this->getRoute()->getAuthor();
234 }
235 ```
Something went wrong with that request. Please try again.