Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 229 lines (167 sloc) 11.474 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 to...
fzaninotto authored
3
8e6722e @willdurand Updated README
willdurand authored
4 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 to...
fzaninotto authored
5
8e6722e @willdurand Updated README
willdurand authored
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
d2372a0 @willdurand Fixed git typo
willdurand authored
14 git submodule update --init
8e6722e @willdurand Updated README
willdurand authored
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
b52f1fe @willdurand Updated README
willdurand authored
19 git submodule update --init --recursive
8e6722e @willdurand Updated README
willdurand authored
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
a0ecb20 @fzaninotto [1.6] Markdown is more natural and easier to read than RST, reverting to...
fzaninotto authored
24
25 Install the plugin via the subversion repository:
26
8e6722e @willdurand Updated README
willdurand authored
27 svn checkout http://svn.github.com/propelorm/sfPropelORMPlugin.git plugins/sfPropelORMPlugin
28
29 Install `Phing` and `Propel`:
30
b52f1fe @willdurand Updated README
willdurand authored
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
a0ecb20 @fzaninotto [1.6] Markdown is more natural and easier to read than RST, reverting to...
fzaninotto authored
33
b52f1fe @willdurand Updated README
willdurand authored
34 ### Final step
35
36 Disable the core Propel plugin and enable the `sfPropelORMPlugin` instead:
a3edbd5 @lucasaba Ads cleanliness to the code
lucasaba authored
37
38 ``` php
b52f1fe @willdurand Updated README
willdurand authored
39 // config/ProjectConfiguration.class.php
a3edbd5 @lucasaba Ads cleanliness to the code
lucasaba authored
40
41 class ProjectConfiguration extends sfProjectConfiguration
42 {
43 public function setup()
44 {
b52f1fe @willdurand Updated README
willdurand authored
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');
48
49 $this->enablePlugins('sfPropelORMPlugin');
a3edbd5 @lucasaba Ads cleanliness to the code
lucasaba authored
50 }
b52f1fe @willdurand Updated README
willdurand authored
51 }
a3edbd5 @lucasaba Ads cleanliness to the code
lucasaba authored
52 ```
53
b52f1fe @willdurand Updated README
willdurand authored
54 **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 to...
fzaninotto authored
55
8e6722e @willdurand Updated README
willdurand authored
56 ``` php
b52f1fe @willdurand Updated README
willdurand authored
57 // plugins/sfPropelORMPlugin/test/functional/fixtures/config/ProjectConfiguration.class.php
a0ecb20 @fzaninotto [1.6] Markdown is more natural and easier to read than RST, reverting to...
fzaninotto authored
58
8e6722e @willdurand Updated README
willdurand authored
59 class ProjectConfiguration extends sfProjectConfiguration
60 {
4878b50 @willdurand Fixed README
willdurand authored
61 public function setup()
62 {
b52f1fe @willdurand Updated README
willdurand authored
63 $this->enablePlugins(array('sfPropelORMPlugin'));
64 $this->setPluginPath('sfPropelORMPlugin', realpath(dirname(__FILE__) . '/../../../..'));
65
66 sfConfig::set('sf_phing_path', SF_DIR.'/../phing');
67 sfConfig::set('sf_propel_path', SF_DIR.'/../propel');
4878b50 @willdurand Fixed README
willdurand authored
68 }
8e6722e @willdurand Updated README
willdurand authored
69 ```
a0ecb20 @fzaninotto [1.6] Markdown is more natural and easier to read than RST, reverting to...
fzaninotto authored
70
4878b50 @willdurand Fixed README
willdurand authored
71 Right after the installation of the plugin, you should update plugin assets:
72
73 php symfony plugin:publish-assets
74
a0ecb20 @fzaninotto [1.6] Markdown is more natural and easier to read than RST, reverting to...
fzaninotto authored
75 Change the path of the symfony behaviors in the `config/propel.ini` file of your project:
76
8e6722e @willdurand Updated README
willdurand authored
77 ``` ini
78 // config/propel.ini
79
80 propel.behavior.symfony.class = plugins.sfPropelORMPlugin.lib.behavior.SfPropelBehaviorSymfony
81 propel.behavior.symfony_i18n.class = plugins.sfPropelORMPlugin.lib.behavior.SfPropelBehaviorI18n
82 propel.behavior.symfony_i18n_translation.class = plugins.sfPropelORMPlugin.lib.behavior.SfPropelBehaviorI18nTranslation
83 propel.behavior.symfony_behaviors.class = plugins.sfPropelORMPlugin.lib.behavior.SfPropelBehaviorSymfonyBehaviors
84 propel.behavior.symfony_timestampable.class = plugins.sfPropelORMPlugin.lib.behavior.SfPropelBehaviorTimestampable
85 ```
a0ecb20 @fzaninotto [1.6] Markdown is more natural and easier to read than RST, reverting to...
fzaninotto authored
86
87 (Re)Build the model:
88
8e6722e @willdurand Updated README
willdurand authored
89 php symfony propel:build --all-classes
90
a0ecb20 @fzaninotto [1.6] Markdown is more natural and easier to read than RST, reverting to...
fzaninotto authored
91
8e6722e @willdurand Updated README
willdurand authored
92 ## What's New In Propel 1.6
a0ecb20 @fzaninotto [1.6] Markdown is more natural and easier to read than RST, reverting to...
fzaninotto authored
93
8e6722e @willdurand Updated README
willdurand authored
94 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 to...
fzaninotto authored
95
8e6722e @willdurand Updated README
willdurand authored
96 ``` php
97 // find the 10 latest books published by authror 'Leo'
98 $books = BookQuery::create()
99 ->useAuthorQuery()
100 ->filterByFirstName('Leo')
101 ->endUse()
102 ->orderByPublishedAt('desc')
103 ->limit(10)
104 ->find($con);
105 ```
a0ecb20 @fzaninotto [1.6] Markdown is more natural and easier to read than RST, reverting to...
fzaninotto authored
106
8e6722e @willdurand Updated README
willdurand authored
107 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 to...
fzaninotto authored
108
109
8e6722e @willdurand Updated README
willdurand authored
110 ## Core Propel Behaviors
a0ecb20 @fzaninotto [1.6] Markdown is more natural and easier to read than RST, reverting to...
fzaninotto authored
111
8e6722e @willdurand Updated README
willdurand authored
112 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 to...
fzaninotto authored
113
8e6722e @willdurand Updated README
willdurand authored
114 - [timestampable](http://www.propelorm.org/wiki/Documentation/1.6/Behaviors/timestampable)
115 - [sluggable](http://www.propelorm.org/wiki/Documentation/1.6/Behaviors/sluggable)
116 - [soft_delete]([http://www.propelorm.org/wiki/Documentation/1.6/Behaviors/soft_delete)
117 - [nested_set](http://www.propelorm.org/wiki/Documentation/1.6/Behaviors/nested_set)
118 - [sortable](http://www.propelorm.org/wiki/Documentation/1.6/Behaviors/sortable)
119 - [concrete_inheritance](http://www.propelorm.org/wiki/Documentation/1.6/Inheritance#ConcreteTableInheritance)
120 - [query_cache](http://www.propelorm.org/wiki/Documentation/1.6/Behaviors/query_cache)
9d248d4 @GromNaN typo
GromNaN authored
121 - [alternative_coding_standards](http://www.propelorm.org/wiki/Documentation/1.6/Behaviors/alternative_coding_standards)
8e6722e @willdurand Updated README
willdurand authored
122 - [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 to...
fzaninotto authored
123
8e6722e @willdurand Updated README
willdurand authored
124 `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 to...
fzaninotto authored
125
8e6722e @willdurand Updated README
willdurand authored
126 ``` yaml
127 propel:
128 section:
129 _attributes: { phpName: Section }
130 _propel_behaviors:
131 - nested_set
132 id: ~
133 title: { type: varchar(100), required: true primaryString: true }
134 ```
a0ecb20 @fzaninotto [1.6] Markdown is more natural and easier to read than RST, reverting to...
fzaninotto authored
135
8e6722e @willdurand Updated README
willdurand authored
136 **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 to...
fzaninotto authored
137
8e6722e @willdurand Updated README
willdurand authored
138 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 to...
fzaninotto authored
139
8e6722e @willdurand Updated README
willdurand authored
140 ``` ini
141 propel.behavior.default = symfony,symfony_i18n,alternative_coding_standards,auto_add_pk
142 ```
a0ecb20 @fzaninotto [1.6] Markdown is more natural and easier to read than RST, reverting to...
fzaninotto authored
143
8e6722e @willdurand Updated README
willdurand authored
144 ## Admin Generator Extensions
a0ecb20 @fzaninotto [1.6] Markdown is more natural and easier to read than RST, reverting to...
fzaninotto authored
145
8e6722e @willdurand Updated README
willdurand authored
146 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 to...
fzaninotto authored
147
148 ### List view enhancements
149
150 - **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.
151 - **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.
152 - **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!
153 - **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
154 - **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:
155 - **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.
156
157 ### Filter and Edit forms enhancement
158
159 - **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.
160 - **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.
161
8e6722e @willdurand Updated README
willdurand authored
162 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 to...
fzaninotto authored
163
8e6722e @willdurand Updated README
willdurand authored
164 ## Form Subframework Modifications
a0ecb20 @fzaninotto [1.6] Markdown is more natural and easier to read than RST, reverting to...
fzaninotto authored
165
0ba5f54 Removed trailing spaces
rozwell authored
166 - **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 to...
fzaninotto authored
167 - **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`.
168 - **Plain text widget and validator**: This new widget allows a field to be displayed in a form, without letting the use change it.
169 - **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.
170
8e6722e @willdurand Updated README
willdurand authored
171 ``` php
172 class ArticleForm extends BaseArticleForm
173 {
76a8cf1 @willdurand Fixed indentation in README
willdurand authored
174 public function configure()
175 {
8e6722e @willdurand Updated README
willdurand authored
176 $this->embedRelation('Book');
76a8cf1 @willdurand Fixed indentation in README
willdurand authored
177 }
8e6722e @willdurand Updated README
willdurand authored
178 }
179 ```
180
181 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.
182
183 ## Routing Modifications
184
185 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()`.
186
187 ``` yaml
188 author:
189 class: sfPropelORMRouteCollection
190 options:
191 model: author
192 module: author
193 prefix_path: /author
194 column: id
195 query_methods:
196 object: [filterByIsPublished]
197 list: [filterByIsPublished, orderByLastName]
198 with_wildcard_routes: true
199 ```
a0ecb20 @fzaninotto [1.6] Markdown is more natural and easier to read than RST, reverting to...
fzaninotto authored
200
09f08af query methods:
rozwell authored
201 Array of additional parameters are also possible for `query_methods`:
202
8e6722e @willdurand Updated README
willdurand authored
203 ``` yaml
204 author:
205 class: sfPropelORMRouteCollection
206 options:
207 model: author
208 module: author
209 prefix_path: /author
210 column: id
211 query_methods:
212 object:
213 filterByIsPublished: [false]
214 list:
215 filterByIsPublished: []
216 orderBy: [LastName]
217 with_wildcard_routes: true
218 ```
219
220 `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:
221
222 ``` php
223 public function executeShow(sfWebRequest $request)
224 {
225 // using sfPropelORMRoute with 'Author' as model
226 $this->author = $this->getRoute()->getAuthor();
227 }
228 ```
Something went wrong with that request. Please try again.