From 904bcfa4f94ac333da6bb9fe92fe1359288d65a7 Mon Sep 17 00:00:00 2001
From: Stefano Torresi <stefano@torresi.io>
Date: Tue, 17 Mar 2015 19:36:11 +0100
Subject: [PATCH] add docs notice about custom object types as IDs

---
 docs/en/cookbook/custom-mapping-types.rst | 28 ++++++++++++++---------
 1 file changed, 17 insertions(+), 11 deletions(-)

diff --git a/docs/en/cookbook/custom-mapping-types.rst b/docs/en/cookbook/custom-mapping-types.rst
index 27ada30ee..1bd4f1242 100644
--- a/docs/en/cookbook/custom-mapping-types.rst
+++ b/docs/en/cookbook/custom-mapping-types.rst
@@ -13,44 +13,50 @@ you wish. Here is an example skeleton of such a custom type class:
 
     <?php
     namespace My\Project\Types;
-    
+
     use Doctrine\DBAL\Types\Type;
     use Doctrine\DBAL\Platforms\AbstractPlatform;
-    
+
     /**
      * My custom datatype.
      */
     class MyType extends Type
     {
         const MYTYPE = 'mytype'; // modify to match your type name
-    
+
         public function getSQLDeclaration(array $fieldDeclaration, AbstractPlatform $platform)
         {
             // return the SQL used to create your column type. To create a portable column type, use the $platform.
         }
-    
+
         public function convertToPHPValue($value, AbstractPlatform $platform)
         {
             // This is executed when the value is read from the database. Make your conversions here, optionally using the $platform.
         }
-    
+
         public function convertToDatabaseValue($value, AbstractPlatform $platform)
         {
             // This is executed when the value is written to the database. Make your conversions here, optionally using the $platform.
         }
-    
+
         public function getName()
         {
             return self::MYTYPE; // modify to match your constant name
         }
     }
 
-The following assumptions are applied to mapping types by the ORM:
+.. note::
 
--  If the value of the field is *NULL* the method
-   ``convertToDatabaseValue()`` is not called.
--  The ``UnitOfWork`` never passes values to the database convert
-   method that did not change in the request.
+    The following assumptions are applied to mapping types by the ORM:
+
+    -  If the value of the field is *NULL* the method
+       ``convertToDatabaseValue()`` is not called.
+    -  The ``UnitOfWork`` never passes values to the database convert
+       method that did not change in the request.
+    -  The ``UnitOfWork`` internally assumes that entity identifiers are
+       castable to string. Hence, when using custom types that map to PHP
+       objects as IDs, such objects must implement the ``__toString()`` magic
+       method.
 
 When you have implemented the type you still need to let Doctrine
 know about it. This can be achieved through the