Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 500 lines (392 sloc) 17.32 kb
a5a0dfa Benjamin Eberlei Converted ORM Docs into ReST
beberlei authored
1 Basic Mapping
2 =============
3
f7108b4 Benjamin Eberlei Move Annotations introduction to the reference.
beberlei authored
4 This guide explains the basic mapping of entities and properties.
5 After working through this guide you should know:
6
1fcef33 Ryan Weaver Changes thanks to @Ocramius
weaverryan authored
7 - How to create PHP objects that can be saved to the database with Doctrine;
f7108b4 Benjamin Eberlei Move Annotations introduction to the reference.
beberlei authored
8 - How to configure the mapping between columns on tables and properties on
36d7d60 Ryan Weaver Minor updates while reading the basic-mapping page
weaverryan authored
9 entities;
10 - What Doctrine mapping types are;
11 - Defining primary keys and how identifiers are generated by Doctrine;
12 - How quoting of reserved symbols works in Doctrine.
f7108b4 Benjamin Eberlei Move Annotations introduction to the reference.
beberlei authored
13
cf2580d Benjamin Eberlei Cleanup of Configuration and Mapping reference chapters.
beberlei authored
14 Mapping of associations will be covered in the next chapter on
15 :doc:`Association Mapping <association-mapping>`.
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
16
f7108b4 Benjamin Eberlei Move Annotations introduction to the reference.
beberlei authored
17 Guide Assumptions
18 -----------------
19
20 You should have already :doc:`installed and configure <configuration>`
21 Doctrine.
22
caf6ba6 Benjamin Eberlei Refactor Basic Mapping chapter to focus on the actual topic more. Rearra...
beberlei authored
23 Creating Classes for the Database
24 ---------------------------------
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
25
1fcef33 Ryan Weaver Changes thanks to @Ocramius
weaverryan authored
26 Every PHP object that you want to save in the database using Doctrine
36d7d60 Ryan Weaver Minor updates while reading the basic-mapping page
weaverryan authored
27 is called an "Entity". The term "Entity" describes objects
28 that have an identity over many independent requests. This identity is
caf6ba6 Benjamin Eberlei Refactor Basic Mapping chapter to focus on the actual topic more. Rearra...
beberlei authored
29 usually achieved by assigning a unique identifier to an entity.
36d7d60 Ryan Weaver Minor updates while reading the basic-mapping page
weaverryan authored
30 In this tutorial the following ``Message`` PHP class will serve as the
caf6ba6 Benjamin Eberlei Refactor Basic Mapping chapter to focus on the actual topic more. Rearra...
beberlei authored
31 example Entity:
32
33 .. code-block:: php
34
35 <?php
36 class Message
37 {
38 private $id;
39 private $text;
40 private $postedAt;
41 }
42
36d7d60 Ryan Weaver Minor updates while reading the basic-mapping page
weaverryan authored
43 Because Doctrine is a generic library, it only knows about your
44 entities because you will describe their existence and structure using
45 mapping metadata, which is configuration that tells Doctrine how your
46 entity should be stored in the database. The documentation will often
47 speak of "mapping something", which means writing the mapping metadata
48 that describes your entity.
caf6ba6 Benjamin Eberlei Refactor Basic Mapping chapter to focus on the actual topic more. Rearra...
beberlei authored
49
1fcef33 Ryan Weaver Changes thanks to @Ocramius
weaverryan authored
50 Doctrine provides several different ways to specify object-relational
caf6ba6 Benjamin Eberlei Refactor Basic Mapping chapter to focus on the actual topic more. Rearra...
beberlei authored
51 mapping metadata:
52
53 - :doc:`Docblock Annotations <annotations-reference>`
54 - :doc:`XML <xml-mapping>`
a948cb4 Benjamin Eberlei Small fixes in basic-mapping.rst
beberlei authored
55 - :doc:`YAML <yaml-mapping>`
56 - :doc:`PHP code <php-mapping>`
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
57
36d7d60 Ryan Weaver Minor updates while reading the basic-mapping page
weaverryan authored
58 This manual will usually show mapping metadata via docblock annotations, though
59 many examples also show the equivalent configuration in YAML and XML.
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
60
a5a0dfa Benjamin Eberlei Converted ORM Docs into ReST
beberlei authored
61 .. note::
62
caf6ba6 Benjamin Eberlei Refactor Basic Mapping chapter to focus on the actual topic more. Rearra...
beberlei authored
63 All metadata drivers perform equally. Once the metadata of a class has been
64 read from the source (annotations, xml or yaml) it is stored in an instance
65 of the ``Doctrine\ORM\Mapping\ClassMetadata`` class and these instances are
66 stored in the metadata cache. If you're not using a metadata cache (not
36d7d60 Ryan Weaver Minor updates while reading the basic-mapping page
weaverryan authored
67 recommended!) then the XML driver is the fastest.
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
68
36d7d60 Ryan Weaver Minor updates while reading the basic-mapping page
weaverryan authored
69 Marking our ``Message`` class as an entity for Doctrine is straightforward:
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
70
b5827ea Benjamin Eberlei Add tons of xml and yaml configuration blocks to basic- and association-...
beberlei authored
71 .. configuration-block::
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
72
b5827ea Benjamin Eberlei Add tons of xml and yaml configuration blocks to basic- and association-...
beberlei authored
73 .. code-block:: php
74
75 <?php
76 /** @Entity */
caf6ba6 Benjamin Eberlei Refactor Basic Mapping chapter to focus on the actual topic more. Rearra...
beberlei authored
77 class Message
b5827ea Benjamin Eberlei Add tons of xml and yaml configuration blocks to basic- and association-...
beberlei authored
78 {
79 //...
80 }
81
82 .. code-block:: xml
83
84 <doctrine-mapping>
caf6ba6 Benjamin Eberlei Refactor Basic Mapping chapter to focus on the actual topic more. Rearra...
beberlei authored
85 <entity name="Message">
f6aa387 Benjamin Eberlei Fix missing chars in xml comment
beberlei authored
86 <!-- ... -->
b5827ea Benjamin Eberlei Add tons of xml and yaml configuration blocks to basic- and association-...
beberlei authored
87 </entity>
88 </doctrine-mapping>
89
90 .. code-block:: yaml
91
caf6ba6 Benjamin Eberlei Refactor Basic Mapping chapter to focus on the actual topic more. Rearra...
beberlei authored
92 Message:
b5827ea Benjamin Eberlei Add tons of xml and yaml configuration blocks to basic- and association-...
beberlei authored
93 type: entity
94 # ...
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
95
36d7d60 Ryan Weaver Minor updates while reading the basic-mapping page
weaverryan authored
96 With no additional information, Doctrine expects the entity to be saved
caf6ba6 Benjamin Eberlei Refactor Basic Mapping chapter to focus on the actual topic more. Rearra...
beberlei authored
97 into a table with the same name as the class in our case ``Message``.
98 You can change this by configuring information about the table:
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
99
b5827ea Benjamin Eberlei Add tons of xml and yaml configuration blocks to basic- and association-...
beberlei authored
100 .. configuration-block::
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
101
b5827ea Benjamin Eberlei Add tons of xml and yaml configuration blocks to basic- and association-...
beberlei authored
102 .. code-block:: php
103
104 <?php
105 /**
106 * @Entity
caf6ba6 Benjamin Eberlei Refactor Basic Mapping chapter to focus on the actual topic more. Rearra...
beberlei authored
107 * @Table(name="message")
b5827ea Benjamin Eberlei Add tons of xml and yaml configuration blocks to basic- and association-...
beberlei authored
108 */
caf6ba6 Benjamin Eberlei Refactor Basic Mapping chapter to focus on the actual topic more. Rearra...
beberlei authored
109 class Message
b5827ea Benjamin Eberlei Add tons of xml and yaml configuration blocks to basic- and association-...
beberlei authored
110 {
111 //...
112 }
113
114 .. code-block:: xml
115
116 <doctrine-mapping>
caf6ba6 Benjamin Eberlei Refactor Basic Mapping chapter to focus on the actual topic more. Rearra...
beberlei authored
117 <entity name="Message" table="message">
f6aa387 Benjamin Eberlei Fix missing chars in xml comment
beberlei authored
118 <!-- ... -->
b5827ea Benjamin Eberlei Add tons of xml and yaml configuration blocks to basic- and association-...
beberlei authored
119 </entity>
120 </doctrine-mapping>
121
122 .. code-block:: yaml
123
caf6ba6 Benjamin Eberlei Refactor Basic Mapping chapter to focus on the actual topic more. Rearra...
beberlei authored
124 Message:
b5827ea Benjamin Eberlei Add tons of xml and yaml configuration blocks to basic- and association-...
beberlei authored
125 type: entity
caf6ba6 Benjamin Eberlei Refactor Basic Mapping chapter to focus on the actual topic more. Rearra...
beberlei authored
126 table: message
b5827ea Benjamin Eberlei Add tons of xml and yaml configuration blocks to basic- and association-...
beberlei authored
127 # ...
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
128
caf6ba6 Benjamin Eberlei Refactor Basic Mapping chapter to focus on the actual topic more. Rearra...
beberlei authored
129 Now the class ``Message`` will be saved and fetched from the table ``message``.
130
131 Property Mapping
132 ----------------
133
36d7d60 Ryan Weaver Minor updates while reading the basic-mapping page
weaverryan authored
134 The next step after marking a PHP class as an entity is mapping its properties
caf6ba6 Benjamin Eberlei Refactor Basic Mapping chapter to focus on the actual topic more. Rearra...
beberlei authored
135 to columns in a table.
136
137 To configure a property use the ``@Column`` docblock annotation. The ``type``
36d7d60 Ryan Weaver Minor updates while reading the basic-mapping page
weaverryan authored
138 attribute specifies the :ref:`Doctrine Mapping Type <reference-mapping-types>`
139 to use for the field. If the type is not specified, ``string`` is used as the
140 default.
caf6ba6 Benjamin Eberlei Refactor Basic Mapping chapter to focus on the actual topic more. Rearra...
beberlei authored
141
142 .. configuration-block::
143
144 .. code-block:: php
145
146 <?php
147 /** @Entity */
148 class Message
149 {
150 /** @Column(type="integer") */
151 private $id;
152 /** @Column(length=140) */
153 private $text;
154 /** @Column(type="datetime", name="posted_at") */
155 private $postedAt;
156 }
157
158 .. code-block:: xml
159
160 <doctrine-mapping>
161 <entity name="Message">
162 <field name="id" type="integer" />
163 <field name="text" length="140" />
164 <field name="postedAt" column="posted_at" type="datetime" />
165 </entity>
166 </doctrine-mapping>
167
168 .. code-block:: yaml
169
170 Message:
171 type: entity
172 fields:
173 id:
174 type: integer
175 text:
176 length: 140
177 postedAt:
178 type: datetime
1057628 Benjamin Eberlei [DDC-2803] Fix error in documentation.
beberlei authored
179 column: posted_at
caf6ba6 Benjamin Eberlei Refactor Basic Mapping chapter to focus on the actual topic more. Rearra...
beberlei authored
180
36d7d60 Ryan Weaver Minor updates while reading the basic-mapping page
weaverryan authored
181 When we don't explicitly specify a column name via the ``name`` option, Doctrine
182 assumes the field name is also the column name. This means that:
183
184 * the ``id`` property will map to the column ``id`` using the type ``integer``;
185 * the ``text`` property will map to the column ``text`` with the default mapping type ``string``;
186 * the ``postedAt`` property will map to the ``posted_at`` column with the ``datetime`` type.
caf6ba6 Benjamin Eberlei Refactor Basic Mapping chapter to focus on the actual topic more. Rearra...
beberlei authored
187
188 The Column annotation has some more attributes. Here is a complete
189 list:
190
a948cb4 Benjamin Eberlei Small fixes in basic-mapping.rst
beberlei authored
191 - ``type``: (optional, defaults to 'string') The mapping type to
192 use for the column.
193 - ``name``: (optional, defaults to field name) The name of the
194 column in the database.
195 - ``length``: (optional, default 255) The length of the column in
196 the database. (Applies only if a string-valued column is used).
197 - ``unique``: (optional, default FALSE) Whether the column is a
198 unique key.
199 - ``nullable``: (optional, default FALSE) Whether the database
200 column is nullable.
201 - ``precision``: (optional, default 0) The precision for a decimal
d93f648 Christian Extended the docs for mapping attributes precision and scale
leonex-cstoller authored
202 (exact numeric) column (applies only for decimal column),
203 which is the maximum number of digits that are stored for the values.
a948cb4 Benjamin Eberlei Small fixes in basic-mapping.rst
beberlei authored
204 - ``scale``: (optional, default 0) The scale for a decimal (exact
d93f648 Christian Extended the docs for mapping attributes precision and scale
leonex-cstoller authored
205 numeric) column (applies only for decimal column), which represents
206 the number of digits to the right of the decimal point and must
207 not be greater than *precision*.
a948cb4 Benjamin Eberlei Small fixes in basic-mapping.rst
beberlei authored
208 - ``columnDefinition``: (optional) Allows to define a custom
209 DDL snippet that is used to create the column. Warning: This normally
210 confuses the SchemaTool to always detect the column as changed.
caf6ba6 Benjamin Eberlei Refactor Basic Mapping chapter to focus on the actual topic more. Rearra...
beberlei authored
211 - ``options``: (optional) Key-value pairs of options that get passed
a948cb4 Benjamin Eberlei Small fixes in basic-mapping.rst
beberlei authored
212 to the underlying database platform when generating DDL statements.
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
213
36d7d60 Ryan Weaver Minor updates while reading the basic-mapping page
weaverryan authored
214 .. _reference-mapping-types:
215
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
216 Doctrine Mapping Types
217 ----------------------
218
546c817 Benjamin Eberlei Move Custom Mapping Types into cookbook, restructure the chapter more.
beberlei authored
219 The ``type`` option used in the ``@Column`` accepts any of the existing
220 Doctrine types or even your own custom types. A Doctrine type defines
36d7d60 Ryan Weaver Minor updates while reading the basic-mapping page
weaverryan authored
221 the conversion between PHP and SQL types, independent from the database vendor
546c817 Benjamin Eberlei Move Custom Mapping Types into cookbook, restructure the chapter more.
beberlei authored
222 you are using. All Mapping Types that ship with Doctrine are fully portable
223 between the supported database systems.
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
224
36d7d60 Ryan Weaver Minor updates while reading the basic-mapping page
weaverryan authored
225 As an example, the Doctrine Mapping Type ``string`` defines the
d4061ff Dustin Moorman Fixed typos in Doctrine Mapping Types section.
dustinmoorman authored
226 mapping from a PHP string to a SQL VARCHAR (or VARCHAR2 etc.
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
227 depending on the RDBMS brand). Here is a quick overview of the
228 built-in mapping types:
229
d4061ff Dustin Moorman Fixed typos in Doctrine Mapping Types section.
dustinmoorman authored
230 - ``string``: Type that maps a SQL VARCHAR to a PHP string.
231 - ``integer``: Type that maps a SQL INT to a PHP integer.
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
232 - ``smallint``: Type that maps a database SMALLINT to a PHP
233 integer.
234 - ``bigint``: Type that maps a database BIGINT to a PHP string.
546c817 Benjamin Eberlei Move Custom Mapping Types into cookbook, restructure the chapter more.
beberlei authored
235 - ``boolean``: Type that maps a SQL boolean or equivalent (TINYINT) to a PHP boolean.
d4061ff Dustin Moorman Fixed typos in Doctrine Mapping Types section.
dustinmoorman authored
236 - ``decimal``: Type that maps a SQL DECIMAL to a PHP string.
237 - ``date``: Type that maps a SQL DATETIME to a PHP DateTime
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
238 object.
d4061ff Dustin Moorman Fixed typos in Doctrine Mapping Types section.
dustinmoorman authored
239 - ``time``: Type that maps a SQL TIME to a PHP DateTime object.
240 - ``datetime``: Type that maps a SQL DATETIME/TIMESTAMP to a PHP
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
241 DateTime object.
d4061ff Dustin Moorman Fixed typos in Doctrine Mapping Types section.
dustinmoorman authored
242 - ``datetimetz``: Type that maps a SQL DATETIME/TIMESTAMP to a PHP
46f4b00 Peter Kruithof Added missing mapping types
pkruithof authored
243 DateTime object with timezone.
d4061ff Dustin Moorman Fixed typos in Doctrine Mapping Types section.
dustinmoorman authored
244 - ``text``: Type that maps a SQL CLOB to a PHP string.
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
245 - ``object``: Type that maps a SQL CLOB to a PHP object using
246 ``serialize()`` and ``unserialize()``
a61afed Lennart Hildebrandt Fixed typo for mapping type "array"
lennerd authored
247 - ``array``: Type that maps a SQL CLOB to a PHP array using
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
248 ``serialize()`` and ``unserialize()``
46f4b00 Peter Kruithof Added missing mapping types
pkruithof authored
249 - ``simple_array``: Type that maps a SQL CLOB to a PHP array using
250 ``implode()`` and ``explode()``, with a comma as delimiter. *IMPORTANT*
251 Only use this type if you are sure that your values cannot contain a ",".
252 - ``json_array``: Type that maps a SQL CLOB to a PHP array using
253 ``json_encode()`` and ``json_decode()``
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
254 - ``float``: Type that maps a SQL Float (Double Precision) to a
255 PHP double. *IMPORTANT*: Works only with locale settings that use
256 decimal points as separator.
f5ba83c Peter Kruithof Documented `guid` mapping type
pkruithof authored
257 - ``guid``: Type that maps a database GUID/UUID to a PHP string. Defaults to
258 varchar but uses a specific type if the platform supports it.
d4061ff Dustin Moorman Fixed typos in Doctrine Mapping Types section.
dustinmoorman authored
259 - ``blob``: Type that maps a SQL BLOB to a PHP resource stream
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
260
546c817 Benjamin Eberlei Move Custom Mapping Types into cookbook, restructure the chapter more.
beberlei authored
261 A cookbook article shows how to define :doc:`your own custom mapping types
262 <../cookbook/custom-mapping-types>`.
263
a5a0dfa Benjamin Eberlei Converted ORM Docs into ReST
beberlei authored
264 .. note::
265
546c817 Benjamin Eberlei Move Custom Mapping Types into cookbook, restructure the chapter more.
beberlei authored
266 DateTime and Object types are compared by reference, not by value. Doctrine
267 updates this values if the reference changes and therefore behaves as if
268 these objects are immutable value objects.
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
269
a5a0dfa Benjamin Eberlei Converted ORM Docs into ReST
beberlei authored
270 .. warning::
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
271
d0ae956 Benjamin Eberlei Add warnining about date types assuming default timezone.
beberlei authored
272 All Date types assume that you are exclusively using the default timezone
273 set by `date_default_timezone_set() <http://docs.php.net/manual/en/function.date-default-timezone-set.php>`_
274 or by the php.ini configuration ``date.timezone``. Working with
275 different timezones will cause troubles and unexpected behavior.
276
277 If you need specific timezone handling you have to handle this
278 in your domain, converting all the values back and forth from UTC.
2996420 Michał Pipa Fixed broken link.
michalpipa authored
279 There is also a :doc:`cookbook entry <../cookbook/working-with-datetime>`
d0ae956 Benjamin Eberlei Add warnining about date types assuming default timezone.
beberlei authored
280 on working with datetimes that gives hints for implementing
281 multi timezone applications.
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
282
283 Identifiers / Primary Keys
284 --------------------------
285
36d7d60 Ryan Weaver Minor updates while reading the basic-mapping page
weaverryan authored
286 Every entity class must have an identifier/primary key. You can select
cf2580d Benjamin Eberlei Cleanup of Configuration and Mapping reference chapters.
beberlei authored
287 the field that serves as the identifier with the ``@Id``
546c817 Benjamin Eberlei Move Custom Mapping Types into cookbook, restructure the chapter more.
beberlei authored
288 annotation.
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
289
b5827ea Benjamin Eberlei Add tons of xml and yaml configuration blocks to basic- and association-...
beberlei authored
290 .. configuration-block::
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
291
b5827ea Benjamin Eberlei Add tons of xml and yaml configuration blocks to basic- and association-...
beberlei authored
292 .. code-block:: php
293
294 <?php
546c817 Benjamin Eberlei Move Custom Mapping Types into cookbook, restructure the chapter more.
beberlei authored
295 class Message
b5827ea Benjamin Eberlei Add tons of xml and yaml configuration blocks to basic- and association-...
beberlei authored
296 {
297 /**
298 * @Id @Column(type="integer")
299 * @GeneratedValue
300 */
301 private $id;
546c817 Benjamin Eberlei Move Custom Mapping Types into cookbook, restructure the chapter more.
beberlei authored
302 //...
b5827ea Benjamin Eberlei Add tons of xml and yaml configuration blocks to basic- and association-...
beberlei authored
303 }
304
305 .. code-block:: xml
306
307 <doctrine-mapping>
546c817 Benjamin Eberlei Move Custom Mapping Types into cookbook, restructure the chapter more.
beberlei authored
308 <entity name="Message">
b5827ea Benjamin Eberlei Add tons of xml and yaml configuration blocks to basic- and association-...
beberlei authored
309 <id name="id" type="integer">
310 <generator strategy="AUTO" />
311 </id>
546c817 Benjamin Eberlei Move Custom Mapping Types into cookbook, restructure the chapter more.
beberlei authored
312 <!-- -->
b5827ea Benjamin Eberlei Add tons of xml and yaml configuration blocks to basic- and association-...
beberlei authored
313 </entity>
314 </doctrine-mapping>
315
316 .. code-block:: yaml
317
546c817 Benjamin Eberlei Move Custom Mapping Types into cookbook, restructure the chapter more.
beberlei authored
318 Message:
b5827ea Benjamin Eberlei Add tons of xml and yaml configuration blocks to basic- and association-...
beberlei authored
319 type: entity
320 id:
321 id:
322 type: integer
323 generator:
324 strategy: AUTO
325 fields:
546c817 Benjamin Eberlei Move Custom Mapping Types into cookbook, restructure the chapter more.
beberlei authored
326 # fields here
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
327
546c817 Benjamin Eberlei Move Custom Mapping Types into cookbook, restructure the chapter more.
beberlei authored
328 In most cases using the automatic generator strategy (``@GeneratedValue``) is
329 what you want. It defaults to the identifier generation mechanism your current
330 database vendor prefers: AUTO_INCREMENT with MySQL, SERIAL with PostgreSQL,
331 Sequences with Oracle and so on.
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
332
333 Identifier Generation Strategies
334 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
335
336 The previous example showed how to use the default identifier
337 generation strategy without knowing the underlying database with
338 the AUTO-detection strategy. It is also possible to specify the
36d7d60 Ryan Weaver Minor updates while reading the basic-mapping page
weaverryan authored
339 identifier generation strategy more explicitly, which allows you to
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
340 make use of some additional features.
341
342 Here is the list of possible generation strategies:
343
344 - ``AUTO`` (default): Tells Doctrine to pick the strategy that is
345 preferred by the used database platform. The preferred strategies
45118a2 Steve Müller mention SQL Anywhere in basic mapping docs
deeky666 authored
346 are IDENTITY for MySQL, SQLite, MsSQL and SQL Anywhere and SEQUENCE
347 for Oracle and PostgreSQL. This strategy provides full portability.
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
348 - ``SEQUENCE``: Tells Doctrine to use a database sequence for ID
349 generation. This strategy does currently not provide full
45118a2 Steve Müller mention SQL Anywhere in basic mapping docs
deeky666 authored
350 portability. Sequences are supported by Oracle, PostgreSql and
351 SQL Anywhere.
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
352 - ``IDENTITY``: Tells Doctrine to use special identity columns in
353 the database that generate a value on insertion of a row. This
354 strategy does currently not provide full portability and is
45118a2 Steve Müller mention SQL Anywhere in basic mapping docs
deeky666 authored
355 supported by the following platforms: MySQL/SQLite/SQL Anywhere
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
356 (AUTO\_INCREMENT), MSSQL (IDENTITY) and PostgreSQL (SERIAL).
357 - ``TABLE``: Tells Doctrine to use a separate table for ID
358 generation. This strategy provides full portability.
359 ***This strategy is not yet implemented!***
360 - ``NONE``: Tells Doctrine that the identifiers are assigned (and
361 thus generated) by your code. The assignment must take place before
362 a new entity is passed to ``EntityManager#persist``. NONE is the
363 same as leaving off the @GeneratedValue entirely.
364
365 Sequence Generator
366 ^^^^^^^^^^^^^^^^^^
367
368 The Sequence Generator can currently be used in conjunction with
369 Oracle or Postgres and allows some additional configuration options
370 besides specifying the sequence's name:
371
b5827ea Benjamin Eberlei Add tons of xml and yaml configuration blocks to basic- and association-...
beberlei authored
372 .. configuration-block::
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
373
b5827ea Benjamin Eberlei Add tons of xml and yaml configuration blocks to basic- and association-...
beberlei authored
374 .. code-block:: php
375
376 <?php
9983fcb Benjamin Eberlei Fix some more details in basic-mapping.rst
beberlei authored
377 class Message
b5827ea Benjamin Eberlei Add tons of xml and yaml configuration blocks to basic- and association-...
beberlei authored
378 {
379 /**
380 * @Id
381 * @GeneratedValue(strategy="SEQUENCE")
9983fcb Benjamin Eberlei Fix some more details in basic-mapping.rst
beberlei authored
382 * @SequenceGenerator(sequenceName="message_seq", initialValue=1, allocationSize=100)
b5827ea Benjamin Eberlei Add tons of xml and yaml configuration blocks to basic- and association-...
beberlei authored
383 */
384 protected $id = null;
9983fcb Benjamin Eberlei Fix some more details in basic-mapping.rst
beberlei authored
385 //...
b5827ea Benjamin Eberlei Add tons of xml and yaml configuration blocks to basic- and association-...
beberlei authored
386 }
387
388 .. code-block:: xml
389
390 <doctrine-mapping>
9983fcb Benjamin Eberlei Fix some more details in basic-mapping.rst
beberlei authored
391 <entity name="Message">
b5827ea Benjamin Eberlei Add tons of xml and yaml configuration blocks to basic- and association-...
beberlei authored
392 <id name="id" type="integer">
393 <generator strategy="SEQUENCE" />
9983fcb Benjamin Eberlei Fix some more details in basic-mapping.rst
beberlei authored
394 <sequence-generator sequence-name="message_seq" allocation-size="100" initial-value="1" />
b5827ea Benjamin Eberlei Add tons of xml and yaml configuration blocks to basic- and association-...
beberlei authored
395 </id>
396 </entity>
397 </doctrine-mapping>
45118a2 Steve Müller mention SQL Anywhere in basic mapping docs
deeky666 authored
398
b5827ea Benjamin Eberlei Add tons of xml and yaml configuration blocks to basic- and association-...
beberlei authored
399 .. code-block:: yaml
400
9983fcb Benjamin Eberlei Fix some more details in basic-mapping.rst
beberlei authored
401 Message:
b5827ea Benjamin Eberlei Add tons of xml and yaml configuration blocks to basic- and association-...
beberlei authored
402 type: entity
403 id:
404 id:
405 type: integer
406 generator:
407 strategy: SEQUENCE
408 sequenceGenerator:
9983fcb Benjamin Eberlei Fix some more details in basic-mapping.rst
beberlei authored
409 sequenceName: message_seq
b5827ea Benjamin Eberlei Add tons of xml and yaml configuration blocks to basic- and association-...
beberlei authored
410 allocationSize: 100
411 initialValue: 1
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
412
413 The initial value specifies at which value the sequence should
414 start.
415
416 The allocationSize is a powerful feature to optimize INSERT
417 performance of Doctrine. The allocationSize specifies by how much
418 values the sequence is incremented whenever the next value is
419 retrieved. If this is larger than 1 (one) Doctrine can generate
420 identifier values for the allocationSizes amount of entities. In
421 the above example with ``allocationSize=100`` Doctrine 2 would only
422 need to access the sequence once to generate the identifiers for
423 100 new entities.
424
425 *The default allocationSize for a @SequenceGenerator is currently 10.*
426
4698346 Benjamin Eberlei Finialized ReST doc changes, merged changes from latest Markdown docs.
beberlei authored
427 .. caution::
428
429 The allocationSize is detected by SchemaTool and
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
430 transformed into an "INCREMENT BY " clause in the CREATE SEQUENCE
431 statement. For a database schema created manually (and not
432 SchemaTool) you have to make sure that the allocationSize
433 configuration option is never larger than the actual sequences
434 INCREMENT BY value, otherwise you may get duplicate keys.
435
436
a5a0dfa Benjamin Eberlei Converted ORM Docs into ReST
beberlei authored
437 .. note::
438
439 It is possible to use strategy="AUTO" and at the same time
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
440 specifying a @SequenceGenerator. In such a case, your custom
441 sequence settings are used in the case where the preferred strategy
442 of the underlying platform is SEQUENCE, such as for Oracle and
443 PostgreSQL.
444
445
446 Composite Keys
447 ~~~~~~~~~~~~~~
448
9983fcb Benjamin Eberlei Fix some more details in basic-mapping.rst
beberlei authored
449 with Doctrine 2 you can use composite primary keys, using ``@Id`` on more then
450 one column. Some restrictions exist opposed to using a single identifier in
451 this case: The use of the ``@GeneratedValue`` annotation is not supported,
452 which means you can only use composite keys if you generate the primary key
453 values yourself before calling ``EntityManager#persist()`` on the entity.
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
454
9983fcb Benjamin Eberlei Fix some more details in basic-mapping.rst
beberlei authored
455 More details on composite primary keys are discussed in a :doc:`dedicated tutorial
456 <../tutorials/composite-primary-keys>`.
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
457
458 Quoting Reserved Words
459 ----------------------
460
cf2580d Benjamin Eberlei Cleanup of Configuration and Mapping reference chapters.
beberlei authored
461 Sometimes it is necessary to quote a column or table name because of reserved
462 word conflicts. Doctrine does not quote identifiers automatically, because it
f9b4df7 Bilge Minor grammar fix.
Bilge authored
463 leads to more problems than it would solve. Quoting tables and column names
cf2580d Benjamin Eberlei Cleanup of Configuration and Mapping reference chapters.
beberlei authored
464 needs to be done explicitly using ticks in the definition.
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
465
4698346 Benjamin Eberlei Finialized ReST doc changes, merged changes from latest Markdown docs.
beberlei authored
466 .. code-block:: php
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
467
468 <?php
469 /** @Column(name="`number`", type="integer") */
470 private $number;
471
472 Doctrine will then quote this column name in all SQL statements
473 according to the used database platform.
474
a5a0dfa Benjamin Eberlei Converted ORM Docs into ReST
beberlei authored
475 .. warning::
476
cf2580d Benjamin Eberlei Cleanup of Configuration and Mapping reference chapters.
beberlei authored
477 Identifier Quoting does not work for join column names or discriminator
275724f Benjamin Eberlei Add missing documentation for 2.4 features
beberlei authored
478 column names unless you are using a custom ``QuoteStrategy``.
1bfeaf3 Benjamin Eberlei Initial conversion from Markdown to ReST - Finalized Cookbook
beberlei authored
479
cf2580d Benjamin Eberlei Cleanup of Configuration and Mapping reference chapters.
beberlei authored
480 .. _reference-basic-mapping-custom-mapping-types:
481
275724f Benjamin Eberlei Add missing documentation for 2.4 features
beberlei authored
482 .. versionadded: 2.3
483
484 For more control over column quoting the ``Doctrine\ORM\Mapping\QuoteStrategy`` interface
485 was introduced in 2.3. It is invoked for every column, table, alias and other
486 SQL names. You can implement the QuoteStrategy and set it by calling
487 ``Doctrine\ORM\Configuration#setQuoteStrategy()``.
488
489 .. versionadded: 2.4
490
491 The ANSI Quote Strategy was added, which assumes quoting is not necessary for any SQL name.
492 You can use it with the following code:
493
494 .. code-block:: php
495
496 <?php
497 use Doctrine\ORM\Mapping\AnsiQuoteStrategy;
498
499 $configuration->setQuoteStrategy(new AnsiQuoteStrategy());
Something went wrong with that request. Please try again.