Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 317 lines (237 sloc) 14.366 kB
8e6722e @willdurand Updated README
willdurand authored
1 sfPropelORMPlugin
2 =================
a0ecb20 @fzaninotto [1.6] Markdown is more natural and easier to read than RST, reverting…
fzaninotto authored
3
275de8b @willdurand Added travis-ci image
willdurand authored
4 [![Build Status](https://secure.travis-ci.org/propelorm/sfPropelORMPlugin.png?branch=master)](http://travis-ci.org/propelorm/sfPropelORMPlugin)
5
8e6722e @willdurand Updated README
willdurand authored
6 Replaces symfony's core Propel plugin by the latest version of Propel, in branch 1.6.
a0ecb20 @fzaninotto [1.6] Markdown is more natural and easier to read than RST, reverting…
fzaninotto authored
7
0551f26 @garak Updated references of svn github (see https://github.com/blog/966-imp…
garak authored
8 ## Installation
8e6722e @willdurand Updated README
willdurand authored
9
e0d0cb1 Added Composer installation instruction
Bert-Jan de Lange authored
10 ### The Composer way
11
12 Add the require to your composer.json. It's oddly named but like this Composer's symfony1 installer camelcases it correctly.
13 Composer will install it into your project's plugins directory automatically, and add the requirements.
14
15 {
16 "config": {
17 "vendor-dir": "lib/vendor"
18 },
19 "require": {
20 "propel/sf-propel-o-r-m-plugin": "dev-master"
21 }
22 }
23
98e28f1 Updated Composer installation docs
bugbyte authored
24 Of course, don't forget to add Composer's autoloader to your ProjectConfiguration:
25
26 ``` php
27 // config/ProjectConfiguration.class.php
28
29 require __DIR__ .'/../lib/vendor/autoload.php';
30
31 require_once dirname(__FILE__) .'/../lib/vendor/symfony/lib/autoload/sfCoreAutoload.class.php';
32 sfCoreAutoload::register();
33
34 class ProjectConfiguration extends sfProjectConfiguration
35 {
36 public function setup()
37 {
38 $this->enablePlugins(array(
39 'sfPropelORMPlugin',
40 ...
41 ));
42
43 // mandatory because of the Composer vendor directory naming scheme
44 sfConfig::set('sf_phing_path', sfConfig::get('sf_lib_dir') .'/vendor/phing/phing');
45 sfConfig::set('sf_propel_path', sfConfig::get('sf_lib_dir') .'/vendor/propel/propel1');
46 }
47 }
48 ```
49
50
8e6722e @willdurand Updated README
willdurand authored
51 ### The Git way
52
53 Clone the plugin from Github:
54
55 git clone git://github.com/propelorm/sfPropelORMPlugin.git plugins/sfPropelORMPlugin
56 cd plugins/sfPropelORMPlugin
d2372a0 @willdurand Fixed git typo
willdurand authored
57 git submodule update --init
8e6722e @willdurand Updated README
willdurand authored
58
59 If you use Git as a VCS for your project, it should be better to add the plugin as a submodule:
60
61 git submodule add git://github.com/propelorm/sfPropelORMPlugin.git plugins/sfPropelORMPlugin
b52f1fe @willdurand Updated README
willdurand authored
62 git submodule update --init --recursive
8e6722e @willdurand Updated README
willdurand authored
63
64 As both Phing and Propel libraries are bundled with the plugin, you have to initialize submodules for the plugin.
65
66 ### The SVN way
a0ecb20 @fzaninotto [1.6] Markdown is more natural and easier to read than RST, reverting…
fzaninotto authored
67
68 Install the plugin via the subversion repository:
69
0551f26 @garak Updated references of svn github (see https://github.com/blog/966-imp…
garak authored
70 svn checkout https://github.com/propelorm/sfPropelORMPlugin/trunk plugins/sfPropelORMPlugin
8e6722e @willdurand Updated README
willdurand authored
71
72 Install `Phing` and `Propel`:
73
b52f1fe @willdurand Updated README
willdurand authored
74 svn checkout http://phing.mirror.svn.symfony-project.com/tags/2.3.3/classes/phing lib/vendor/phing
0551f26 @garak Updated references of svn github (see https://github.com/blog/966-imp…
garak authored
75 svn checkout https://github.com/propelorm/Propel/tags/1.6.5 lib/vendor/propel
a0ecb20 @fzaninotto [1.6] Markdown is more natural and easier to read than RST, reverting…
fzaninotto authored
76
b52f1fe @willdurand Updated README
willdurand authored
77 ### Final step
78
1066e1b Update README.md
Jacob Thomason authored
79 Disable the core Propel plugin and enable the `sfPropelORMPlugin` instead. Also, change the location for
80 the Propel and Phing libs.
a3edbd5 @lucasaba Ads cleanliness to the code
lucasaba authored
81
82 ``` php
b52f1fe @willdurand Updated README
willdurand authored
83 // config/ProjectConfiguration.class.php
a3edbd5 @lucasaba Ads cleanliness to the code
lucasaba authored
84
85 class ProjectConfiguration extends sfProjectConfiguration
86 {
87 public function setup()
88 {
1066e1b Update README.md
Jacob Thomason authored
89 //setup the location for our phing and propel libs
90 sfConfig::set('sf_phing_path', sfConfig::get('sf_root_dir').'/plugins/sfPropelORMPlugin/lib/vendor/phing/');
1a55297 @willdurand Update README.md
willdurand authored
91 sfConfig::set('sf_propel_path', sfConfig::get('sf_root_dir').'/plugins/sfPropelORMPlugin/lib/vendor/propel/');
1066e1b Update README.md
Jacob Thomason authored
92 sfConfig::set('sf_propel_generator_path', sfConfig::get('sf_root_dir').'/plugins/sfPropelORMPlugin/lib/vendor/propel/generator/lib/');
b52f1fe @willdurand Updated README
willdurand authored
93
94 $this->enablePlugins('sfPropelORMPlugin');
a3edbd5 @lucasaba Ads cleanliness to the code
lucasaba authored
95 }
b52f1fe @willdurand Updated README
willdurand authored
96 }
a3edbd5 @lucasaba Ads cleanliness to the code
lucasaba authored
97 ```
98
b52f1fe @willdurand Updated README
willdurand authored
99 **Optional:** update references to the `propel` and `phing` folders in the test project.
a0ecb20 @fzaninotto [1.6] Markdown is more natural and easier to read than RST, reverting…
fzaninotto authored
100
8e6722e @willdurand Updated README
willdurand authored
101 ``` php
b52f1fe @willdurand Updated README
willdurand authored
102 // plugins/sfPropelORMPlugin/test/functional/fixtures/config/ProjectConfiguration.class.php
a0ecb20 @fzaninotto [1.6] Markdown is more natural and easier to read than RST, reverting…
fzaninotto authored
103
8e6722e @willdurand Updated README
willdurand authored
104 class ProjectConfiguration extends sfProjectConfiguration
105 {
4878b50 @willdurand Fixed README
willdurand authored
106 public function setup()
107 {
b52f1fe @willdurand Updated README
willdurand authored
108 $this->enablePlugins(array('sfPropelORMPlugin'));
109 $this->setPluginPath('sfPropelORMPlugin', realpath(dirname(__FILE__) . '/../../../..'));
110
059da3e @willdurand Fixed tests
willdurand authored
111 // SVN way
112 //sfConfig::set('sf_propel_path', SF_DIR.'/../lib/vendor/propel');
113 //sfConfig::set('sf_phing_path', SF_DIR.'/../lib/vendor/phing');
114
115 // Git way
116 sfConfig::set('sf_propel_path', realpath(dirname(__FILE__) . '/../../../../lib/vendor/propel'));
117 sfConfig::set('sf_phing_path', realpath(dirname(__FILE__) . '/../../../../lib/vendor/phing'));
4878b50 @willdurand Fixed README
willdurand authored
118 }
8e6722e @willdurand Updated README
willdurand authored
119 ```
a0ecb20 @fzaninotto [1.6] Markdown is more natural and easier to read than RST, reverting…
fzaninotto authored
120
4878b50 @willdurand Fixed README
willdurand authored
121 Right after the installation of the plugin, you should update plugin assets:
122
123 php symfony plugin:publish-assets
124
a0ecb20 @fzaninotto [1.6] Markdown is more natural and easier to read than RST, reverting…
fzaninotto authored
125 Change the path of the symfony behaviors in the `config/propel.ini` file of your project:
126
8e6722e @willdurand Updated README
willdurand authored
127 ``` ini
128 // config/propel.ini
129
130 propel.behavior.symfony.class = plugins.sfPropelORMPlugin.lib.behavior.SfPropelBehaviorSymfony
131 propel.behavior.symfony_i18n.class = plugins.sfPropelORMPlugin.lib.behavior.SfPropelBehaviorI18n
132 propel.behavior.symfony_i18n_translation.class = plugins.sfPropelORMPlugin.lib.behavior.SfPropelBehaviorI18nTranslation
133 propel.behavior.symfony_behaviors.class = plugins.sfPropelORMPlugin.lib.behavior.SfPropelBehaviorSymfonyBehaviors
134 propel.behavior.symfony_timestampable.class = plugins.sfPropelORMPlugin.lib.behavior.SfPropelBehaviorTimestampable
135 ```
a0ecb20 @fzaninotto [1.6] Markdown is more natural and easier to read than RST, reverting…
fzaninotto authored
136
137 (Re)Build the model:
138
8e6722e @willdurand Updated README
willdurand authored
139 php symfony propel:build --all-classes
140
a0ecb20 @fzaninotto [1.6] Markdown is more natural and easier to read than RST, reverting…
fzaninotto authored
141
8e6722e @willdurand Updated README
willdurand authored
142 ## What's New In Propel 1.6
a0ecb20 @fzaninotto [1.6] Markdown is more natural and easier to read than RST, reverting…
fzaninotto authored
143
8e6722e @willdurand Updated README
willdurand authored
144 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:
a0ecb20 @fzaninotto [1.6] Markdown is more natural and easier to read than RST, reverting…
fzaninotto authored
145
8e6722e @willdurand Updated README
willdurand authored
146 ``` php
147 // find the 10 latest books published by authror 'Leo'
148 $books = BookQuery::create()
149 ->useAuthorQuery()
150 ->filterByFirstName('Leo')
151 ->endUse()
152 ->orderByPublishedAt('desc')
153 ->limit(10)
154 ->find($con);
155 ```
a0ecb20 @fzaninotto [1.6] Markdown is more natural and easier to read than RST, reverting…
fzaninotto authored
156
8e6722e @willdurand Updated README
willdurand authored
157 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.
a0ecb20 @fzaninotto [1.6] Markdown is more natural and easier to read than RST, reverting…
fzaninotto authored
158
159
8e6722e @willdurand Updated README
willdurand authored
160 ## Core Propel Behaviors
a0ecb20 @fzaninotto [1.6] Markdown is more natural and easier to read than RST, reverting…
fzaninotto authored
161
8e6722e @willdurand Updated README
willdurand authored
162 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:
a0ecb20 @fzaninotto [1.6] Markdown is more natural and easier to read than RST, reverting…
fzaninotto authored
163
8e6722e @willdurand Updated README
willdurand authored
164 - [timestampable](http://www.propelorm.org/wiki/Documentation/1.6/Behaviors/timestampable)
165 - [sluggable](http://www.propelorm.org/wiki/Documentation/1.6/Behaviors/sluggable)
166 - [soft_delete]([http://www.propelorm.org/wiki/Documentation/1.6/Behaviors/soft_delete)
167 - [nested_set](http://www.propelorm.org/wiki/Documentation/1.6/Behaviors/nested_set)
168 - [sortable](http://www.propelorm.org/wiki/Documentation/1.6/Behaviors/sortable)
169 - [concrete_inheritance](http://www.propelorm.org/wiki/Documentation/1.6/Inheritance#ConcreteTableInheritance)
170 - [query_cache](http://www.propelorm.org/wiki/Documentation/1.6/Behaviors/query_cache)
9d248d4 @GromNaN typo
GromNaN authored
171 - [alternative_coding_standards](http://www.propelorm.org/wiki/Documentation/1.6/Behaviors/alternative_coding_standards)
8e6722e @willdurand Updated README
willdurand authored
172 - [auto_add_pk](http://www.propelorm.org/wiki/Documentation/1.6/Behaviors/auto_add_pk)
a0ecb20 @fzaninotto [1.6] Markdown is more natural and easier to read than RST, reverting…
fzaninotto authored
173
8e6722e @willdurand Updated README
willdurand authored
174 `sfPropelORMPlugin` allows you to register core propel behaviors right from your `schema.yml`. For instance, to create a tree structure from a `Section` model:
a0ecb20 @fzaninotto [1.6] Markdown is more natural and easier to read than RST, reverting…
fzaninotto authored
175
8e6722e @willdurand Updated README
willdurand authored
176 ``` yaml
177 propel:
178 section:
179 _attributes: { phpName: Section }
180 _propel_behaviors:
181 - nested_set
182 id: ~
183 title: { type: varchar(100), required: true primaryString: true }
184 ```
a0ecb20 @fzaninotto [1.6] Markdown is more natural and easier to read than RST, reverting…
fzaninotto authored
185
8e6722e @willdurand Updated README
willdurand authored
186 **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.
a0ecb20 @fzaninotto [1.6] Markdown is more natural and easier to read than RST, reverting…
fzaninotto authored
187
8e6722e @willdurand Updated README
willdurand authored
188 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:
a0ecb20 @fzaninotto [1.6] Markdown is more natural and easier to read than RST, reverting…
fzaninotto authored
189
8e6722e @willdurand Updated README
willdurand authored
190 ``` ini
191 propel.behavior.default = symfony,symfony_i18n,alternative_coding_standards,auto_add_pk
192 ```
a0ecb20 @fzaninotto [1.6] Markdown is more natural and easier to read than RST, reverting…
fzaninotto authored
193
8e6722e @willdurand Updated README
willdurand authored
194 ## Admin Generator Extensions
a0ecb20 @fzaninotto [1.6] Markdown is more natural and easier to read than RST, reverting…
fzaninotto authored
195
8e6722e @willdurand Updated README
willdurand authored
196 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:
a0ecb20 @fzaninotto [1.6] Markdown is more natural and easier to read than RST, reverting…
fzaninotto authored
197
198 ### List view enhancements
199
200 - **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.
201 - **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.
202 - **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!
203 - **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
204 - **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:
205 - **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.
c9ca969 @garak added reference to sortable links
garak authored
206 - **Automatic sortable links**: If a module is generated on a model with sortable behavior, actions for moving records up and down are automatically added.
a0ecb20 @fzaninotto [1.6] Markdown is more natural and easier to read than RST, reverting…
fzaninotto authored
207
208 ### Filter and Edit forms enhancement
209
210 - **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.
211 - **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.
212
8e6722e @willdurand Updated README
willdurand authored
213 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.
a0ecb20 @fzaninotto [1.6] Markdown is more natural and easier to read than RST, reverting…
fzaninotto authored
214
8e6722e @willdurand Updated README
willdurand authored
215 ## Form Subframework Modifications
a0ecb20 @fzaninotto [1.6] Markdown is more natural and easier to read than RST, reverting…
fzaninotto authored
216
0ba5f54 Removed trailing spaces
rozwell authored
217 - **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.
a0ecb20 @fzaninotto [1.6] Markdown is more natural and easier to read than RST, reverting…
fzaninotto authored
218 - **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`.
219 - **Plain text widget and validator**: This new widget allows a field to be displayed in a form, without letting the use change it.
220 - **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.
221
8e6722e @willdurand Updated README
willdurand authored
222 ``` php
223 class ArticleForm extends BaseArticleForm
224 {
76a8cf1 @willdurand Fixed indentation in README
willdurand authored
225 public function configure()
226 {
8e6722e @willdurand Updated README
willdurand authored
227 $this->embedRelation('Book');
76a8cf1 @willdurand Fixed indentation in README
willdurand authored
228 }
8e6722e @willdurand Updated README
willdurand authored
229 }
230 ```
231
232 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.
233
476dcc2 @themouette updated README
themouette authored
234 ## Filter Subframework modification
235
236 You now can merge or embed filters into filters, it works out of the box.
237
238 ``` php
239 class ArticleFilter extends BaseArticleFilter
240 {
241 public function configure()
242 {
243 $this->mergeForm(new AuthorFilter());
244 }
245 }
246 ```
247
8e6722e @willdurand Updated README
willdurand authored
248 ## Routing Modifications
249
250 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()`.
251
252 ``` yaml
253 author:
254 class: sfPropelORMRouteCollection
255 options:
256 model: author
257 module: author
258 prefix_path: /author
259 column: id
260 query_methods:
261 object: [filterByIsPublished]
262 list: [filterByIsPublished, orderByLastName]
263 with_wildcard_routes: true
264 ```
a0ecb20 @fzaninotto [1.6] Markdown is more natural and easier to read than RST, reverting…
fzaninotto authored
265
09f08af query methods:
rozwell authored
266 Array of additional parameters are also possible for `query_methods`:
267
8e6722e @willdurand Updated README
willdurand authored
268 ``` yaml
269 author:
270 class: sfPropelORMRouteCollection
271 options:
272 model: author
273 module: author
274 prefix_path: /author
275 column: id
276 query_methods:
277 object:
278 filterByIsPublished: [false]
279 list:
280 filterByIsPublished: []
281 orderBy: [LastName]
282 with_wildcard_routes: true
283 ```
284
285 `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:
286
287 ``` php
288 public function executeShow(sfWebRequest $request)
289 {
290 // using sfPropelORMRoute with 'Author' as model
291 $this->author = $this->getRoute()->getAuthor();
292 }
293 ```
8eb59f1 @garak adds connection to pager and route
garak authored
294
cd2580b @garak added "connection" option to sfPropelORMRouteCollection
garak authored
295 A new option has been added to both `sfPropelORMRoute` and `sfPropelORMRouteCollection`, the `connection` option allows to set a specific Propel connection to use.
296 Examples:
8eb59f1 @garak adds connection to pager and route
garak authored
297
298 ``` yaml
299 author_show:
300 url: /author/:id
cd2580b @garak added "connection" option to sfPropelORMRouteCollection
garak authored
301 class: sfPropelORMRoute
8eb59f1 @garak adds connection to pager and route
garak authored
302 param: { module: myModule, action: show }
303 options: { model: Author, type: object, connection: my_connection }
304 ```
cd2580b @garak added "connection" option to sfPropelORMRouteCollection
garak authored
305
306 ``` yaml
307 author:
308 class: sfPropelORMRouteCollection
309 options:
310 model: Author
311 module: author
312 prefix_path: /author
313 column: id
314 connection: my_connection
315 with_wildcard_routes: true
316 ```
Something went wrong with that request. Please try again.