Create castAs method for generic casting

Tests/DatabaseQueryTest.php

@@ -10,6 +10,7 @@
 use Joomla\Database\DatabaseQuery;
 use Joomla\Database\Exception\QueryTypeAlreadyDefinedException;
 use Joomla\Database\ParameterType;
+use Joomla\Database\Exception\UnknownTypeException;
 use PHPUnit\Framework\MockObject\MockObject;
 use PHPUnit\Framework\TestCase;
 
@@ -84,6 +85,31 @@ public function testCastAsChar()
 		$this->assertSame('foo', $this->query->castAsChar('foo'));
 	}
 
+	/**
+	 * @testdox  A string is cast as a character string for the driver
+	 */
+	public function testCastAs()
+	{
+		$this->assertSame('123', $this->query->castAs('CHAR', '123'));
+	}
+
+	/**
+	 * @testdox  The length param is ignored for castAs when the sql driver doesn't support it
+	 */
+	public function testCastAsLengthParamIgnoredWhenNotSupported()
+	{
+		$this->assertSame('123', $this->query->castAs('CHAR', '123', 2));
+	}
+
+	/**
+	 * @testdox  Test an unknown type case return an unknown type exception
+	 */
+	public function testCastAsWithUnknownType()
+	{
+		$this->expectException(UnknownTypeException::class);
+		$this->query->castAs('INT', '123');
+	}
+
 	/**
 	 * Data provider for character length test cases
 	 *

Tests/Mysql/MysqlQueryTest.php

@@ -128,4 +128,34 @@ public function testRegexp()
 			$this->query->regexp('foo')
 		);
 	}
+
+	/**
+	 * @testdox  A string is cast as a character string for the driver
+	 */
+	public function testCastAsWithChar()
+	{
+		$this->assertSame('123', $this->query->castAs('CHAR', '123'));
+	}
+
+	/**
+	 * @testdox  The length param is added to the CAST statement when provided
+	 */
+	public function testCastAsWithCharAndLengthParam()
+	{
+		$this->assertSame(
+			'CAST(123 AS CHAR(2))',
+			$this->query->castAs('CHAR', '123', 2)
+		);
+	}
+
+	/**
+	 * @testdox  Test castAs behaviour with INT (adds 0 to the input)
+	 */
+	public function testCastAsWithIntegerType()
+	{
+		$this->assertSame(
+			'(123 + 0)',
+			$this->query->castAs('INT', '123')
+		);
+	}
 }

Tests/Mysqli/MysqliQueryTest.php

@@ -128,4 +128,34 @@ public function testRegexp()
 			$this->query->regexp('foo')
 		);
 	}
+
+	/**
+	 * @testdox  A string is cast as a character string for the driver
+	 */
+	public function testCastAsWithChar()
+	{
+		$this->assertSame('123', $this->query->castAs('CHAR', '123'));
+	}
+
+	/**
+	 * @testdox  The length param is added to the CAST statement when provided
+	 */
+	public function testCastAsWithCharAndLengthParam()
+	{
+		$this->assertSame(
+			'CAST(123 AS CHAR(2))',
+			$this->query->castAs('CHAR', '123', 2)
+		);
+	}
+
+	/**
+	 * @testdox  Test castAs behaviour with INT (adds 0 to the input)
+	 */
+	public function testCastAsWithIntegerType()
+	{
+		$this->assertSame(
+			'(123 + 0)',
+			$this->query->castAs('INT', '123')
+		);
+	}
 }

Tests/Pgsql/PgsqlQueryTest.php

@@ -53,6 +53,36 @@ public function testCastAsChar()
 		$this->assertSame('foo::text', $this->query->castAsChar('foo'));
 	}
 
+	/**
+	 * @testdox  A string is cast as a character string for the driver
+	 */
+	public function testCastAsWithChar()
+	{
+		$this->assertSame('foo::text', $this->query->castAs('CHAR', 'foo'));
+	}
+
+	/**
+	 * @testdox  The length param is added to the CAST statement when provided
+	 */
+	public function testCastAsWithCharAndLengthParam()
+	{
+		$this->assertSame(
+			'CAST(foo AS CHAR(2))',
+			$this->query->castAs('CHAR', 'foo', 2)
+		);
+	}
+
+	/**
+	 * @testdox  Test castAs behaviour with INT
+	 */
+	public function testCastAsWithIntegerType()
+	{
+		$this->assertSame(
+			'CAST(123 AS INTEGER)',
+			$this->query->castAs('INT', '123')
+		);
+	}
+
 	/**
 	 * Data provider for concatenate test cases
 	 *

Tests/Sqlsrv/SqlsrvQueryTest.php

@@ -53,6 +53,36 @@ public function testCastAsChar()
 		$this->assertSame('CAST(foo as NVARCHAR(10))', $this->query->castAsChar('foo'));
 	}
 
+	/**
+	 * @testdox  A string is cast as a character string for the driver
+	 */
+	public function testCastAsWithChar()
+	{
+		$this->assertSame('CAST(foo as NVARCHAR(10))', $this->query->castAs('CHAR', 'foo'));
+	}
+
+	/**
+	 * @testdox  The length param is added to the CAST statement when provided
+	 */
+	public function testCastAsWithCharAndLengthParam()
+	{
+		$this->assertSame(
+			'CAST(foo as NVARCHAR(2))',
+			$this->query->castAs('CHAR', 'foo', 2)
+		);
+	}
+
+	/**
+	 * @testdox  Test castAs behaviour with INT
+	 */
+	public function testCastAsWithIntegerType()
+	{
+		$this->assertSame(
+			'CAST(123 AS INT)',
+			$this->query->castAs('INT', '123')
+		);
+	}
+
 	/**
 	 * Data provider for character length test cases
 	 *

docs/v1-to-v2-update.md

@@ -114,3 +114,9 @@ Instead of `$query->from($subquery, 'alias')` use `$query->from($subquery->alias
 Several methods which defined a query type (i.e. INSERT, SELECT, UPDATE) contained doc blocks indicating the query type should not be changed, but
 this was not enforced in the code. As of 2.0, an exception will be thrown if trying to change a query type. If intending to change the query type,
 either call `DatabaseQuery::clear()` (optionally only clearing the type clause) or a new query object should be created instead.
+
+#### `castAsChar` deprecated. Replaced with `castAs`
+
+`castAsChar($value)` has been deprecated in favour using of the more generic `castAs('CHAR', $value)` method. This
+method has support for supplying the length of a string and also accepting other types of casts such as integers.
+The intent is to add more cast types in the subsequent versions.

src/DatabaseQuery.php

@@ -9,6 +9,7 @@
 namespace Joomla\Database;
 
 use Joomla\Database\Exception\QueryTypeAlreadyDefinedException;
+use Joomla\Database\Exception\UnknownTypeException;
 
 /**
  * Joomla Framework Query Building Class.
@@ -555,6 +556,40 @@ public function call($columns)
 		return $this;
 	}
 
+	/**
+	 * Casts a value to a char.
+	 *
+	 * Ensure that the value is properly quoted before passing to the method.
+	 *
+	 * Usage:
+	 * $query->select($query->castAs('CHAR', 'a'));
+	 *
+	 * @param   string  $type    The type of string to cast as.
+	 * @param   string  $value   The value to cast as a char.
+	 * @param   string  $length  Optionally specify the length of the field (if the type supports it otherwise
+	 *                           ignored).
+	 *
+	 * @return  string  SQL statement to cast the value as a char type.
+	 *
+	 * @since   1.0
+	 */
+	public function castAs(string $type, string $value, ?string $length = null)
+	{
+		switch (strtoupper($type))
+		{
+			case 'CHAR':
+				return $value;
+
+			default:
+				throw new UnknownTypeException(
+					sprintf(
+						'Type %s was not recognised by the database driver as valid for casting',
+						$type
+					)
+				);
+		}
+	}
+
 	/**
 	 * Casts a value to a char.
 	 *
@@ -565,13 +600,14 @@ public function call($columns)
 	 *
 	 * @param   string  $value  The value to cast as a char.
 	 *
-	 * @return  string  Returns the cast value.
+	 * @return  string  SQL statement to cast the value as a char type.
 	 *
-	 * @since   1.0
+	 * @since       1.0
+	 * @deprecated  3.0  Use $query->castAs('CHAR', $value)
 	 */
 	public function castAsChar($value)
 	{
-		return $value;
+		return $this->castAs('CHAR', $value);
 	}
 
 	/**

src/Exception/UnknownTypeException.php

@@ -0,0 +1,18 @@
+<?php
+/**
+ * Part of the Joomla Framework Database Package
+ *
+ * @copyright  Copyright (C) 2005 - 2019 Open Source Matters, Inc. All rights reserved.
+ * @license    GNU General Public License version 2 or later; see LICENSE
+ */
+
+namespace Joomla\Database\Exception;
+
+/**
+ * Class representing an unknown type for a given database driver.
+ *
+ * @since  __DEPLOY_VERSION__
+ */
+class UnknownTypeException extends \InvalidArgumentException
+{
+}

src/Query/MysqlQueryBuilder.php

@@ -224,4 +224,41 @@ public function selectRowNumber($orderBy, $orderColumnAlias)
 
 		return $this->select("(SELECT @rownum := @rownum + 1 FROM (SELECT @rownum := 0) AS r) AS $orderColumnAlias");
 	}
+
+	/**
+	 * Casts a value to a char.
+	 *
+	 * Ensure that the value is properly quoted before passing to the method.
+	 *
+	 * Usage:
+	 * $query->select($query->castAs('CHAR', 'a'));
+	 *
+	 * @param   string  $type    The type of string to cast as.
+	 * @param   string  $value   The value to cast as a char.
+	 * @param   string  $length  The value to cast as a char.
+	 *
+	 * @return  string  SQL statement to cast the value as a char type.
+	 *
+	 * @since   1.0
+	 */
+	public function castAs(string $type, string $value, ?string $length = null)
+	{
+		switch (strtoupper($type))
+		{
+			case 'CHAR':
+				if (!$length)
+				{
+					return $value;
+				}
+				else
+				{
+					return 'CAST(' . $value . ' AS CHAR(' . $length . '))';
+				}
+
+			case 'INT':
+				return '(' . $value . ' + 0)';
+		}
+
+		return parent::castAs($type, $value, $length);
+	}
 }

src/Query/PostgresqlQueryBuilder.php

@@ -308,23 +308,42 @@ public function clear($clause = null)
 		return $this;
 	}
 
+
 	/**
 	 * Casts a value to a char.
 	 *
 	 * Ensure that the value is properly quoted before passing to the method.
 	 *
 	 * Usage:
-	 * $query->select($query->castAsChar('a'));
+	 * $query->select($query->castAs('CHAR', 'a'));
 	 *
-	 * @param   string  $value  The value to cast as a char.
+	 * @param   string  $type    The type of string to cast as.
+	 * @param   string  $value   The value to cast as a char.
+	 * @param   string  $length  The value to cast as a char.
 	 *
-	 * @return  string  Returns the cast value.
+	 * @return  string  SQL statement to cast the value as a char type.
 	 *
-	 * @since   __DEPLOY_VERSION__
+	 * @since   1.0
 	 */
-	public function castAsChar($value)
+	public function castAs(string $type, string $value, ?string $length = null)
 	{
-		return $value . '::text';
+		switch (strtoupper($type))
+		{
+			case 'CHAR':
+				if (!$length)
+				{
+					return $value . '::text';
+				}
+				else
+				{
+					return 'CAST(' . $value . ' AS CHAR(' . $length . '))';
+				}
+
+			case 'INT':
+				return 'CAST(' . $value . ' AS INTEGER)';
+		}
+
+		return parent::castAs($type, $value, $length);
 	}
 
 	/**