From 3076e2a1f7828f80a70f5cce0a7d24a132fdd175 Mon Sep 17 00:00:00 2001
From: "Fabio B. Silva" <fabio.bat.silva@gmail.com>
Date: Thu, 12 Apr 2012 22:39:39 -0300
Subject: [PATCH 1/2] docs for NamingStrategy

---
 en/index.rst                    |   3 +
 en/reference/namingstrategy.rst | 141 ++++++++++++++++++++++++++++++++
 en/toc.rst                      |   3 +
 3 files changed, 147 insertions(+)
 create mode 100644 en/reference/namingstrategy.rst

diff --git a/en/index.rst b/en/index.rst
index a02f80f551..3841e06541 100644
--- a/en/index.rst
+++ b/en/index.rst
@@ -84,6 +84,9 @@ Advanced Topics
 * **Filtering entities**:
   :doc:`Filters <reference/filters>`
 
+* **Implementing a NamingStrategy**:
+  :doc:`NamingStrategy <reference/namingstrategy>`
+
 * **Performance**:
   :doc:`Improving Performance <reference/improving-performance>` |
   :doc:`Caching <reference/caching>` |
diff --git a/en/reference/namingstrategy.rst b/en/reference/namingstrategy.rst
new file mode 100644
index 0000000000..9963fc7986
--- /dev/null
+++ b/en/reference/namingstrategy.rst
@@ -0,0 +1,141 @@
+Implementing a NamingStrategy
+==============================
+
+Using a naming strategy you can provide rules for automatically generating database identifiers, columns and tables names
+when the table/column name is not given.
+This feature helps reduce the verbosity of the mapping document, eliminating repetitive noise (eg: ``TABLE_``).
+
+
+Configuring a naming strategy
+-----------------------------
+The default strategy used by Doctrine is quite minimal.
+
+By default the ``Doctrine\ORM\Mapping\DefaultNamingStrategy``
+uses the simple class name and the attributes names to generate tables and columns
+
+You can specify a different strategy by calling ``Doctrine\ORM\Configuration#setNamingStrategy()`` :
+
+.. code-block:: php
+
+    <?php
+    $namingStrategy = new MyNamingStrategy();
+    $configuration()->setNamingStrategy($namingStrategy);
+
+Underscore naming strategy
+---------------------------
+
+``\Doctrine\ORM\Mapping\UnderscoreNamingStrategy`` is a built-in strategy that might be a useful if you want to use a underlying convention.
+
+.. code-block:: php
+
+    <?php
+    $namingStrategy = new \Doctrine\ORM\Mapping\UnderscoreNamingStrategy(CASE_UPPER);
+    $configuration()->setNamingStrategy(namingStrategy);
+
+Then SomeEntityName will generate the table SOME_ENTITY_NAME when CASE_UPPER or some_entity_name using CASE_LOWER is given.
+
+
+Naming strategy interface
+-------------------------
+The interface ``Doctrine\ORM\Mapping\NamingStrategy`` allows you to specify a "naming standard" for database tables and columns.
+
+.. code-block:: php
+
+    <?php
+    /**
+     * Return a table name for an entity class
+     *
+     * @param string $className The fully-qualified class name
+     * @return string A table name
+     */
+    function classToTableName($className);
+
+    /**
+     * Return a column name for a property
+     *
+     * @param string $propertyName A property
+     * @return string A column name
+     */
+    function propertyToColumnName($propertyName);
+
+    /**
+     * Return the default reference column name
+     *
+     * @return string A column name
+     */
+    function referenceColumnName();
+
+    /**
+     * Return a join column name for a property
+     *
+     * @param string $propertyName A property
+     * @return string A join column name
+     */
+    function joinColumnName($propertyName);
+
+    /**
+     * Return a join table name
+     *
+     * @param string $sourceEntity The source entity
+     * @param string $targetEntity The target entity
+     * @param string $propertyName A property
+     * @return string A join table name
+     */
+    function joinTableName($sourceEntity, $targetEntity, $propertyName = null);
+
+    /**
+     * Return the foreign key column name for the given parameters
+     *
+     * @param string $entityName A entity
+     * @param string $referencedColumnName A property
+     * @return string A join column name
+     */
+    function joinKeyColumnName($entityName, $referencedColumnName = null);
+
+Implementing a naming strategy
+-------------------------------
+If you have database naming standards like all tables names should be prefixed by the application prefix, all column names should be upper case, you can easily achieve such standards by implementing a naming strategy.
+You need to implements NamingStrategy first. Following is an example
+
+
+.. code-block:: php
+
+    <?php
+    class MyAppNamingStrategy implements NamingStrategy
+    {
+        public function classToTableName($className)
+        {
+            return 'MyApp_' . substr($className, strrpos($className, '\\') + 1);
+        }
+        public function propertyToColumnName($propertyName)
+        {
+            return $propertyName;
+        }
+        public function referenceColumnName()
+        {
+            return 'id';
+        }
+        public function joinColumnName($propertyName)
+        {
+            return $propertyName . '_' . $this->referenceColumnName();
+        }
+        public function joinTableName($sourceEntity, $targetEntity, $propertyName = null)
+        {
+            return strtolower($this->classToTableName($sourceEntity) . '_' .
+                    $this->classToTableName($targetEntity));
+        }
+        public function joinKeyColumnName($entityName, $referencedColumnName = null)
+        {
+            return strtolower($this->classToTableName($entityName) . '_' .
+                    ($referencedColumnName ?: $this->referenceColumnName()));
+        }
+    }
+
+Configuring the namingstrategy is easy if.
+Just set your naming strategy calling ``Doctrine\ORM\Configuration#setNamingStrategy()`` :.
+
+.. code-block:: php
+
+    <?php
+    $namingStrategy = new MyAppNamingStrategy();
+    $configuration()->setNamingStrategy($namingStrategy);
\ No newline at end of file
diff --git a/en/toc.rst b/en/toc.rst
index 8178f8c05e..5cdbe90c78 100644
--- a/en/toc.rst
+++ b/en/toc.rst
@@ -50,6 +50,9 @@ Reference Guide
    reference/metadata-drivers
    reference/best-practices
    reference/limitations-and-known-issues
+   tutorials/pagination.rst
+   reference/filters.rst
+   reference/namingstrategy.rst
 
 
 Cookbook

From 987834a2ddd3b746c9d63c92dd68f30cdc43a6db Mon Sep 17 00:00:00 2001
From: "Fabio B. Silva" <fabio.bat.silva@gmail.com>
Date: Fri, 13 Apr 2012 09:13:18 -0300
Subject: [PATCH 2/2] wrap lines

---
 en/reference/namingstrategy.rst | 21 ++++++++++++++-------
 1 file changed, 14 insertions(+), 7 deletions(-)

diff --git a/en/reference/namingstrategy.rst b/en/reference/namingstrategy.rst
index 9963fc7986..f1e856b583 100644
--- a/en/reference/namingstrategy.rst
+++ b/en/reference/namingstrategy.rst
@@ -1,9 +1,11 @@
 Implementing a NamingStrategy
 ==============================
 
-Using a naming strategy you can provide rules for automatically generating database identifiers, columns and tables names
+Using a naming strategy you can provide rules for automatically generating
+database identifiers, columns and tables names
 when the table/column name is not given.
-This feature helps reduce the verbosity of the mapping document, eliminating repetitive noise (eg: ``TABLE_``).
+This feature helps reduce the verbosity of the mapping document,
+eliminating repetitive noise (eg: ``TABLE_``).
 
 
 Configuring a naming strategy
@@ -24,20 +26,23 @@ You can specify a different strategy by calling ``Doctrine\ORM\Configuration#set
 Underscore naming strategy
 ---------------------------
 
-``\Doctrine\ORM\Mapping\UnderscoreNamingStrategy`` is a built-in strategy that might be a useful if you want to use a underlying convention.
+``\Doctrine\ORM\Mapping\UnderscoreNamingStrategy`` is a built-in strategy
+that might be a useful if you want to use a underlying convention.
 
 .. code-block:: php
 
     <?php
     $namingStrategy = new \Doctrine\ORM\Mapping\UnderscoreNamingStrategy(CASE_UPPER);
-    $configuration()->setNamingStrategy(namingStrategy);
+    $configuration()->setNamingStrategy($namingStrategy);
 
-Then SomeEntityName will generate the table SOME_ENTITY_NAME when CASE_UPPER or some_entity_name using CASE_LOWER is given.
+Then SomeEntityName will generate the table SOME_ENTITY_NAME when CASE_UPPER
+or some_entity_name using CASE_LOWER is given.
 
 
 Naming strategy interface
 -------------------------
-The interface ``Doctrine\ORM\Mapping\NamingStrategy`` allows you to specify a "naming standard" for database tables and columns.
+The interface ``Doctrine\ORM\Mapping\NamingStrategy`` allows you to specify
+a "naming standard" for database tables and columns.
 
 .. code-block:: php
 
@@ -94,7 +99,9 @@ The interface ``Doctrine\ORM\Mapping\NamingStrategy`` allows you to specify a "n
 
 Implementing a naming strategy
 -------------------------------
-If you have database naming standards like all tables names should be prefixed by the application prefix, all column names should be upper case, you can easily achieve such standards by implementing a naming strategy.
+If you have database naming standards like all tables names should be prefixed
+by the application prefix, all column names should be upper case,
+you can easily achieve such standards by implementing a naming strategy.
 You need to implements NamingStrategy first. Following is an example