Introduce WellKnownTextConverter interface

docs/en/reference/types.rst

@@ -929,29 +929,25 @@ Now we implement our ``Doctrine\DBAL\Types\Type`` instance:
 
 The job of Doctrine-DBAL is to transform your type into an SQL
 declaration. You can modify the SQL declaration Doctrine will produce.
-At first, to enable this feature, you must override the
-``canRequireSQLConversion`` method:
+At first, to enable this feature, you must implement  the
+``Doctrine\DBAL\Types\WellKnownTextConverter`` interface:
 
 ::
 
     <?php
-    public function canRequireSQLConversion()
-    {
-        return true;
-    }
+    final class MyType implements WellKnownTextConverter
 
-Then you override the ``convertToPhpValueSQL`` and
-``convertToDatabaseValueSQL`` methods :
+The interface consists of two methods, which we implement like this in our case:
 
 ::
 
     <?php
-    public function convertToPHPValueSQL($sqlExpr, $platform)
+    public function convertToWellKnownTextSQL($sqlExpr, $platform)
     {
         return 'MyMoneyFunction(\''.$sqlExpr.'\') ';
     }
 
-    public function convertToDatabaseValueSQL($sqlExpr, AbstractPlatform $platform)
+    public function convertFromWellKnownTextSQL($sqlExpr, AbstractPlatform $platform)
     {
         return 'MyFunction('.$sqlExpr.')';
     }

lib/Doctrine/DBAL/Types/Type.php

@@ -292,6 +292,7 @@ public function __toString()
      * does nothing. This method can additionally be used for optimization purposes.
      *
      * @return boolean
+     * @deprecated implement WellKnownTextConverter instead
      */
     public function canRequireSQLConversion()
     {
@@ -305,6 +306,7 @@ public function canRequireSQLConversion()
      * @param \Doctrine\DBAL\Platforms\AbstractPlatform $platform
      *
      * @return string
+     * @deprecated implement WellKnownTextConverter::convertFromWellKnownTextSQL instead
      */
     public function convertToDatabaseValueSQL($sqlExpr, AbstractPlatform $platform)
     {
@@ -318,6 +320,7 @@ public function convertToDatabaseValueSQL($sqlExpr, AbstractPlatform $platform)
      * @param \Doctrine\DBAL\Platforms\AbstractPlatform $platform
      *
      * @return string
+     * @deprecated implement WellKnownTextConverter::convertToWellKnownTextSQL instead
      */
     public function convertToPHPValueSQL($sqlExpr, $platform)
     {

lib/Doctrine/DBAL/Types/WellKnownTextConverter.php

@@ -0,0 +1,55 @@
+<?php
+/*
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * This software consists of voluntary contributions made by many individuals
+ * and is licensed under the MIT license. For more information, see
+ * <http://www.doctrine-project.org>.
+ */
+
+namespace Doctrine\DBAL\Types;
+
+use Doctrine\DBAL\Platforms\AbstractPlatform;
+use Doctrine\DBAL\DBALException;
+
+/**
+ * Does working with this column require SQL conversion functions?
+ *
+ * This is a metadata function that is required for example in the ORM.
+ * Usage of {@link convertToDatabaseValueSQL} and
+ * {@link convertToPHPValueSQL} works for any type and mostly
+ * does nothing. This method can additionally be used for optimization purposes.
+ *
+ */
+interface WellKnownTextConverter
+{
+    /**
+     * Modifies the SQL expression (identifier, parameter) to convert to a database value.
+     *
+     * @param string                                    $sqlExpr
+     * @param \Doctrine\DBAL\Platforms\AbstractPlatform $platform
+     *
+     * @return string
+     */
+    public function convertFromWellKnownTextSQL(string $sqlExpr, AbstractPlatform $platform) : string;
+
+    /**
+     * Modifies the SQL expression (identifier, parameter) to convert to a PHP value.
+     *
+     * @param string                                    $sqlExpr
+     * @param \Doctrine\DBAL\Platforms\AbstractPlatform $platform
+     *
+     * @return string
+     */
+    public function convertToWellKnownTextSQL(string $sqlExpr, AbstractPlatform $platform) : string;
+}