Merge pull request #1083 from deeky666/DDC-3073

[DDC-3073] Add documentation about how to map column options

docs/en/reference/annotations-reference.rst

@@ -109,6 +109,26 @@ Optional attributes:
 
 -  **nullable**: Determines if NULL values allowed for this column.
 
+-  **options**: Array of additional options:
+
+   -  ``default``: The default value to set for the column if no value
+      is supplied.
+
+   -  ``unsigned``: Boolean value to determine if the column should
+      be capable of representing only non-negative integers
+      (applies only for integer column and might not be supported by
+      all vendors).
+
+   -  ``fixed``: Boolean value to determine if the specified length of
+      a string column should be fixed or varying (applies only for
+      string/binary column and might not be supported by all vendors).
+
+   -  ``comment``: The comment of the column in the schema (might not
+      be supported by all vendors).
+
+   -  ``customSchemaOptions``: Array of additional schema options
+      which are mostly vendor specific.
+
 -  **columnDefinition**: DDL SQL snippet that starts after the column
    name and specifies the complete (non-portable!) column definition.
    This attribute allows to make use of advanced RMDBS features.
@@ -120,7 +140,12 @@ Optional attributes:
    attribute still handles the conversion between PHP and Database
    values. If you use this attribute on a column that is used for
    joins between tables you should also take a look at
-   :ref:`@JoinColumn <annref_joincolumn>`. 
+   :ref:`@JoinColumn <annref_joincolumn>`.
+
+.. note::
+
+    For more detailed information on each attribute, please refer to
+    the DBAL ``Schema-Representation`` documentation.
 
 Examples:
 
@@ -131,17 +156,27 @@ Examples:
      * @Column(type="string", length=32, unique=true, nullable=false)
      */
     protected $username;
-    
+
     /**
      * @Column(type="string", columnDefinition="CHAR(2) NOT NULL")
      */
     protected $country;
-    
+
     /**
      * @Column(type="decimal", precision=2, scale=1)
      */
     protected $height;
 
+    /**
+     * @Column(type="string", length=2, options={"fixed":true, "comment":"Initial letters of first and last name"})
+     */
+    protected $initials;
+
+    /**
+     * @Column(type="integer", name="login_count" nullable=false, options={"unsigned":true, "default":0})
+     */
+    protected $loginCount;
+
 .. _annref_column_result:
 
 @ColumnResult
@@ -222,7 +257,7 @@ Optional attributes:
 ~~~~~~~~~~~~~~~~~~~~~
 
 The discriminator map is a required annotation on the
-topmost/super class in an inheritance hierarchy. Its only argument is an 
+topmost/super class in an inheritance hierarchy. Its only argument is an
 array which defines which class should be saved under
 which name in the database. Keys are the database value and values
 are the classes, either as fully- or as unqualified class names
@@ -447,7 +482,7 @@ Examples:
     {
         // ...
     }
-    
+
     /**
      * @Entity
      * @InheritanceType("JOINED")
@@ -640,7 +675,7 @@ Example:
      *      )
      */
     private $groups;
-    
+
     /**
      * Inverse Side
      *

docs/en/reference/php-mapping.rst

@@ -27,7 +27,7 @@ to write a mapping file for it using the above configured
 
     <?php
     namespace Entities;
-    
+
     class User
     {
         private $id;
@@ -42,16 +42,30 @@ named ``Entities.User.php`` inside of the
 
     <?php
     // /path/to/php/mapping/files/Entities.User.php
-    
+
     $metadata->mapField(array(
        'id' => true,
        'fieldName' => 'id',
        'type' => 'integer'
     ));
-    
+
     $metadata->mapField(array(
        'fieldName' => 'username',
-       'type' => 'string'
+       'type' => 'string',
+       'options' => array(
+           'fixed' => true,
+           'comment' => "User's login name"
+       )
+    ));
+
+    $metadata->mapField(array(
+       'fieldName' => 'login_count',
+       'type' => 'integer',
+       'nullable' => false,
+       'options' => array(
+           'unsigned' => true,
+           'default' => 0
+       )
     ));
 
 Now we can easily retrieve the populated ``ClassMetadata`` instance
@@ -87,13 +101,13 @@ Now you just need to define a static function named
 
     <?php
     namespace Entities;
-    
+
     use Doctrine\ORM\Mapping\ClassMetadata;
-    
+
     class User
     {
         // ...
-    
+
         public static function loadMetadata(ClassMetadata $metadata)
         {
             $metadata->mapField(array(
@@ -101,7 +115,7 @@ Now you just need to define a static function named
                'fieldName' => 'id',
                'type' => 'integer'
             ));
-    
+
             $metadata->mapField(array(
                'fieldName' => 'username',
                'type' => 'string'

docs/en/reference/xml-mapping.rst

@@ -22,9 +22,9 @@ setup for the latest code in trunk.
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
                        https://raw.github.com/doctrine/doctrine2/master/doctrine-mapping.xsd">
-    
+
         ...
-    
+
     </doctrine-mapping>
 
 The XML mapping document of a class is loaded on-demand the first
@@ -108,37 +108,37 @@ of several common elements:
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
                               http://raw.github.com/doctrine/doctrine2/master/doctrine-mapping.xsd">
-    
+
         <entity name="Doctrine\Tests\ORM\Mapping\User" table="cms_users">
-    
+
             <indexes>
                 <index name="name_idx" columns="name"/>
                 <index columns="user_email"/>
             </indexes>
-    
+
             <unique-constraints>
                 <unique-constraint columns="name,user_email" name="search_idx" />
             </unique-constraints>
-    
+
             <lifecycle-callbacks>
                 <lifecycle-callback type="prePersist" method="doStuffOnPrePersist"/>
                 <lifecycle-callback type="prePersist" method="doOtherStuffOnPrePersistToo"/>
                 <lifecycle-callback type="postPersist" method="doStuffOnPostPersist"/>
             </lifecycle-callbacks>
-    
+
             <id name="id" type="integer" column="id">
                 <generator strategy="AUTO"/>
                 <sequence-generator sequence-name="tablename_seq" allocation-size="100" initial-value="1" />
             </id>
-    
+
             <field name="name" column="name" type="string" length="50" nullable="true" unique="true" />
             <field name="email" column="user_email" type="string" column-definition="CHAR(32) NOT NULL" />
-    
+
             <one-to-one field="address" target-entity="Address" inversed-by="user">
                 <cascade><cascade-remove /></cascade>
                 <join-column name="address_id" referenced-column-name="id" on-delete="CASCADE" on-update="CASCADE"/>
             </one-to-one>
-    
+
             <one-to-many field="phonenumbers" target-entity="Phonenumber" mapped-by="user">
                 <cascade>
                     <cascade-persist/>
@@ -147,7 +147,7 @@ of several common elements:
                     <order-by-field name="number" direction="ASC" />
                 </order-by>
             </one-to-many>
-    
+
             <many-to-many field="groups" target-entity="Group">
                 <cascade>
                     <cascade-all/>
@@ -161,9 +161,9 @@ of several common elements:
                     </inverse-join-columns>
                 </join-table>
             </many-to-many>
-    
+
         </entity>
-    
+
     </doctrine-mapping>
 
 Be aware that class-names specified in the XML files should be
@@ -224,12 +224,18 @@ entity. For the ID mapping you have to use the ``<id />`` element.
 .. code-block:: xml
 
     <entity name="MyProject\User">
-    
+
         <field name="name" type="string" length="50" />
         <field name="username" type="string" unique="true" />
         <field name="age" type="integer" nullable="true" />
         <field name="isActive" column="is_active" type="boolean" />
         <field name="weight" type="decimal" scale="5" precision="2" />
+        <field name="login_count" type="integer" nullable="false">
+            <options>
+                <option name="comment">The number of times the user has logged in.</option>
+                <option name="default">0</option>
+            </options>
+        </field>
     </entity>
 
 Required attributes:
@@ -255,12 +261,32 @@ Optional attributes:
    works on fields with type integer or datetime.
 -  scale - Scale of a decimal type.
 -  precision - Precision of a decimal type.
+-  options - Array of additional options:
+
+   -  default - The default value to set for the column if no value
+      is supplied.
+   -  unsigned - Boolean value to determine if the column should
+      be capable of representing only non-negative integers
+      (applies only for integer column and might not be supported by
+      all vendors).
+   -  fixed - Boolean value to determine if the specified length of
+      a string column should be fixed or varying (applies only for
+      string/binary column and might not be supported by all vendors).
+   -  comment - The comment of the column in the schema (might not
+      be supported by all vendors).
+   -  customSchemaOptions - Array of additional schema options
+      which are mostly vendor specific.
 -  column-definition - Optional alternative SQL representation for
    this column. This definition begin after the field-name and has to
    specify the complete column definition. Using this feature will
    turn this field dirty for Schema-Tool update commands at all
    times.
 
+.. note::
+
+    For more detailed information on each attribute, please refer to
+    the DBAL ``Schema-Representation`` documentation.
+
 Defining Identity and Generator Strategies
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -423,7 +449,7 @@ using the ``<lifecycle-callbacks />`` element:
 .. code-block:: xml
 
     <entity name="Doctrine\Tests\ORM\Mapping\User" table="cms_users">
-    
+
         <lifecycle-callbacks>
             <lifecycle-callback type="prePersist" method="onPrePersist" />
         </lifecycle-callbacks>
@@ -716,12 +742,12 @@ table you can use the ``<indexes />`` and
 .. code-block:: xml
 
     <entity name="Doctrine\Tests\ORM\Mapping\User" table="cms_users">
-    
+
         <indexes>
             <index name="name_idx" columns="name"/>
             <index columns="user_email"/>
         </indexes>
-    
+
         <unique-constraints>
             <unique-constraint columns="name,user_email" name="search_idx" />
         </unique-constraints>

docs/en/reference/yaml-mapping.rst

@@ -94,6 +94,14 @@ of several common elements:
           unique: true
           options:
             fixed: true
+            comment: User's email address
+        loginCount:
+          type: integer
+          column: login_count
+          nullable: false
+          options:
+            unsigned: true
+            default: 0
       oneToOne:
         address:
           targetEntity: Address