Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 321 lines (251 sloc) 9.814 kB
1bfb208 @mariano README updates
authored
1 li3\_doctrine2 offers integration between [the most RAD PHP framework] [lithium]
b7bce75 @mariano Adding README
authored
2 and possibly the best PHP 5.3 ORM out there: [Doctrine2] [doctrine2]
3
4 # License #
5
1bfb208 @mariano README updates
authored
6 li3\_doctrine2 is released under the [BSD License] [license].
b7bce75 @mariano Adding README
authored
7
8 # Installation #
9
1bfb208 @mariano README updates
authored
10 It is recommended that you install li3\_doctrine2 as a GIT submodule, in order
b7bce75 @mariano Adding README
authored
11 to keep up with the latest upgrades. To do so, switch to the core directory
12 holding your lithium application, and do:
13
14 ```bash
540750d @mariano Fixing repo URL
authored
15 $ git submodule add https://github.com/mariano/li3_doctrine2.git app/libraries/li3_doctrine2
b7bce75 @mariano Adding README
authored
16 $ cd app/libraries/li3_doctrine2 && git submodule update --init
17 $ cd _source/doctrine2 && git submodule update --init
18 ```
19
1bfb208 @mariano README updates
authored
20 # Usage #
21
b9bef23 @mariano README updates
authored
22 ## Adding the li3\_doctrine2 library ##
1bfb208 @mariano README updates
authored
23
623f2ae @mariano Documentation updates
authored
24 Once you have downloaded li3\_doctrine2 and placed it in your `app/libraries`,
1bfb208 @mariano README updates
authored
25 or your main `libraries` folder, you need to enable it by placing the following
26 at the end of your `app/config/bootstrap/libraries.php` file:
27
28 ```php
29 Libraries::add('li3_doctrine2');
30 ```
31
32 ## Defining a connection ##
33
b9bef23 @mariano README updates
authored
34 Setting up a connection with li3\_doctrine2 is easy. All you need to do is
35 add the following to your `app/config/bootstrap/connections.php` file (make
36 sure to edit the settings to match your host, without altering the `type`
37 setting):
38
39 ```php
40 Connections::add('default', array(
41 'type' => 'Doctrine',
42 'driver' => 'pdo_mysql',
43 'host' => 'localhost',
44 'user' => 'root',
45 'password' => 'password',
707fc8e @mariano Documentation updates
authored
46 'dbname' => 'my_db'
b9bef23 @mariano README updates
authored
47 ));
48 ```
1bfb208 @mariano README updates
authored
49
707fc8e @mariano Documentation updates
authored
50 ## Working with models ##
51
52 ### Creating models ###
1bfb208 @mariano README updates
authored
53
54 When looking to create your doctrine models, you have two choices: you can
889e90b @mariano Documentation updates
authored
55 have them follow your custom class hierarchy (or none at all), or you could
1bfb208 @mariano README updates
authored
56 have them extend from the `BaseEntity` class provided by this library. The
b9bef23 @mariano README updates
authored
57 advantage of choosing the later is that your models will have lithium's
889e90b @mariano Documentation updates
authored
58 validation support, and can be better integrated with the custom adapters
59 provided by this library (such as for session management or for authorization.)
b9bef23 @mariano README updates
authored
60
61 Let us create a `User` model. Following doctrine's [basic mapping guide]
72f1e8b @mariano Documentation updates
authored
62 [doctrine-mapping-guide] we'll use annotations to define the properties, and
63 we will also include lithium validation rules (that's why we are choosing to
64 extend this model from `BaseEntity`):
b9bef23 @mariano README updates
authored
65
66 ```php
72f1e8b @mariano Documentation updates
authored
67 <?php
68 namespace app\models;
69
70 use Doctrine\ORM\Mapping\Column;
71 use Doctrine\ORM\Mapping\Entity;
72 use Doctrine\ORM\Mapping\GeneratedValue;
73 use Doctrine\ORM\Mapping\Id;
74 use Doctrine\ORM\Mapping\Table;
75 use lithium\security\Password;
76
77 /**
78 * @Entity
79 * @Table(name="users")
80 */
81 class User extends \li3_doctrine2\models\BaseEntity {
82 /**
83 * @Id
84 * @GeneratedValue
85 * @Column(type="integer")
86 */
87 protected $id;
88
89 /**
90 * @Column(type="string",unique=true)
91 */
92 protected $email;
93
94 /**
95 * @Column(type="text")
96 */
97 protected $password;
98
99 /**
100 * @Column(type="string")
101 */
102 protected $name;
103
104 /**
105 * Validation rules
106 */
107 protected $validates = array(
108 'email' => array(
109 'required' => array('notEmpty', 'message' => 'Email is required'),
110 'valid' => array('email', 'message' => 'You must specify a valid email address', 'skipEmpty' => true)
111 ),
112 'password' => array('notEmpty', 'message' => 'Password must not be blank'),
113 'name' => array('notEmpty', 'message' => 'Please provide your full name')
114
115 );
116
117 public function getId() {
118 return $this->id;
119 }
120
121 public function getEmail() {
122 return $this->email;
123 }
124
125 public function setEmail($email) {
126 $this->email = $email;
127 }
128
129 public function setPassword($password) {
130 $this->password = !empty($password) ? Password::hash($password) : null;
131 }
132
133 public function getName() {
134 return $this->name;
135 }
136
137 public function setName($name) {
138 $this->name = $name;
139 }
140 }
141 ?>
b9bef23 @mariano README updates
authored
142 ```
1bfb208 @mariano README updates
authored
143
889e90b @mariano Documentation updates
authored
144 ### Using the Doctrine shell to generate the schema ###
707fc8e @mariano Documentation updates
authored
145
623f2ae @mariano Documentation updates
authored
146 Once you have your model(s) created, you can use doctrine's shell to generate
147 the schema. li3\_doctrine2 offers a wrapper for doctrine's shell that
889e90b @mariano Documentation updates
authored
148 reutilizes lithium's connection details. To run the access the core directory
149 of your application and do:
623f2ae @mariano Documentation updates
authored
150
151 ```bash
152 $ app/libraries/li3_doctrine2/bin/doctrine
153 ```
154
155 That will give you all the available commands. For example, to get the SQL
156 you should run to create the schema for your models, do:
157
158 ```bash
159 $ app/libraries/li3_doctrine2/bin/doctrine orm:schema-tool:create --dump-sql
160 ```
161
162 which will give an output similar to the following:
163
164 ```sql
165 CREATE TABLE users (
166 id INT AUTO_INCREMENT NOT NULL,
167 email VARCHAR(255) NOT NULL,
168 password LONGTEXT NOT NULL,
169 name VARCHAR(255) NOT NULL,
170 UNIQUE INDEX UNIQ_1483A5E9E7927C74 (email),
171 PRIMARY KEY(id)
172 ) ENGINE = InnoDB
173 ```
707fc8e @mariano Documentation updates
authored
174
889e90b @mariano Documentation updates
authored
175 ### Getting the entity manager ###
176
177 Doctrine's `EntityManager` is the way we have to interact with the underlying
178 database, which means we'll always need to obtain it. You can do so by
179 running the following code (change `default` to the name of your connection
180 as defined in `app/config/connections.php`):
181
182 ```php
183 $em = \lithium\data\Connections::get('default')->getEntityManager();
184 ```
185
186 If your models extend from `BaseEntity`, then all of them have a static method
187 named `getEntityManager()` (which uses a static property inherited from
188 `BaseEntity` named `$connectionName` to figure out what connection to use):
189
190 ```php
191 $em = User::getEntityManager();
192 ```
193
194 ### Fetching records ###
195
196 Once you have the entity manager, you can fetch a user with ID 1 (notice how
197 we use the fully qualified class name for the model) using the entity
198 manager:
199
200 ```php
201 $user = $em->find('app\models\User', 1);
202 ```
203
204 or using model repositories:
205
206 ```php
207 $user = $em->getRepository('app\models\User')->findOneById(1);
208 ```
209
210 If you want to find out more about querying models with Doctrine, go through
211 its [Querying guide] [doctrine-querying-guide].
212
213 ### Creating/Updating/Deleting records ###
214
215 Records are persisted (or removed) though the entity manager, as shown in
216 Doctrine's [Persisting guide] [doctrine-persisting-guide].
217
218 One thing to note is that if your models extend from `BaseEntity`, you have
219 validation rules defined for them, and the data you provide does not validate,
220 persisting it will throw a `ValidateException` (the following example uses
221 the `User` model we defined earlier):
222
223 ```php
224 $user = new User();
225 $user->setName('John Doe');
226 $user->setEmail('bademail@');
227
228 try {
229 $em->persist($user);
230 $em->flush();
231 } catch(\li3_doctrine2\models\ValidateException $e) {
232 echo $e->getMessage();
233 }
234 ```
235
236 You should also note that `BaseEntity` provides a method named `set()` which
237 comes very handy if the user data is to be populated from a form submission.
238 If so, the above code could be rewritten as:
239
240 ```php
241 $user = new User();
242 $user->set($this->request->data);
243
244 try {
245 $em->persist($user);
246 $em->flush();
247 } catch(\li3_doctrine2\models\ValidateException $e) {
248 echo $e->getMessage();
249 }
250 ```
251
252 In this last example, if lithium's form helper is bound to the record instance,
253 it will properly show validation errors. The following view code uses the
254 `$user` variable from the example above to bind the form to its validation
255 errors:
256
257 ```php
258 <?php echo $this->form->create(isset($user) ? $user : null); ?>
259 <?php echo $this->form->field('email'); ?>
260 <?php echo $this->form->field('password', array('type' => 'password')); ?>
261 <?php echo $this->form->field('name'); ?>
262 <?php echo $this->form->submit('Signup'); ?>
263 <?php echo $this->form->end(); ?>
264 ```
265
1bfb208 @mariano README updates
authored
266 # Integrating Doctrine libraries #
267
268 In this section I'll cover some of the doctrine extension libraries out there,
623f2ae @mariano Documentation updates
authored
269 and how to integrate them with li3_\doctrine2.
1bfb208 @mariano README updates
authored
270
271 ## DoctrineExtensions ##
b7bce75 @mariano Adding README
authored
272
273 If there is one tool I would recommend you checkout for your Doctrine models,
e811e60 @mariano Fixing link reference in README
authored
274 that would be [DoctrineExtensions] [DoctrineExtensions]. It provides with a set
b7bce75 @mariano Adding README
authored
275 of behavioral extensions to the Doctrine core that will simplify your
276 development.
277
278 To use DoctrineExtensions, you should first add it as GIT submodule. To do so,
279 switch to the core directory holding your lithium application, and do:
280
281 ```bash
282 $ git submodule add https://github.com/l3pp4rd/DoctrineExtensions.git app/libraries/_source/DoctrineExtensions
283 ```
284
285 Next you would use your connection configuration (in `app/config/connections.php`)
286 to configure Doctrine with your desired behaviors. For example, if you wish
287 to use Timestampable and Sluggable, you would first add the library in
288 `app/config/libraries.php`:
289
290 ```php
291 Libraries::add('Gedmo', array(
1bfb208 @mariano README updates
authored
292 'path' => LITHIUM_APP_PATH . '/libraries/_source/DoctrineExtensions/lib/Gedmo'
b7bce75 @mariano Adding README
authored
293 ));
294 ```
295
a165763 @mariano Making the creation of entity manager filterable
authored
296 And then you would filter the `createEntityManager` method in the `Doctrine`
297 datasource to add the behaviors. Edit your `app/config/connections.php` file
298 and add the following right below the connection definition:
b7bce75 @mariano Adding README
authored
299
300 ```php
a165763 @mariano Making the creation of entity manager filterable
authored
301 Connections::get('default')->applyFilter('createEntityManager',
302 function($self, $params, $chain) {
303 $params['eventManager']->addEventSubscriber(
304 new \Gedmo\Timestampable\TimestampableListener()
b7bce75 @mariano Adding README
authored
305 );
a165763 @mariano Making the creation of entity manager filterable
authored
306 $params['eventManager']->addEventSubscriber(
307 new \Gedmo\Sluggable\SluggableListener()
308 );
309 return $chain->next($self, $params, $chain);
b7bce75 @mariano Adding README
authored
310 }
a165763 @mariano Making the creation of entity manager filterable
authored
311 );
b7bce75 @mariano Adding README
authored
312 ```
313
314 [lithium]: http://lithify.me
315 [doctrine2]: http://www.doctrine-project.org
316 [license]: http://www.opensource.org/licenses/bsd-license.php
317 [DoctrineExtensions]: https://github.com/l3pp4rd/DoctrineExtensions
b9bef23 @mariano README updates
authored
318 [doctrine-mapping-guide]: http://www.doctrine-project.org/docs/orm/2.1/en/reference/basic-mapping.html
889e90b @mariano Documentation updates
authored
319 [doctrine-querying-guide]: http://www.doctrine-project.org/docs/orm/2.1/en/reference/working-with-objects.html#querying
320 [doctrine-persisting-guide]: http://www.doctrine-project.org/docs/orm/2.1/en/reference/working-with-objects.html#persisting-entities
Something went wrong with that request. Please try again.