<?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 LGPL. For more information, see

 * <http://www.doctrine-project.org>.

 */

namespace Doctrine\DBAL\Platforms;

use Doctrine\DBAL\DBALException,

    Doctrine\DBAL\Connection,

    Doctrine\DBAL\Types,

    Doctrine\DBAL\Schema\Table,

    Doctrine\DBAL\Schema\Index,

    Doctrine\DBAL\Schema\ForeignKeyConstraint,

    Doctrine\DBAL\Schema\TableDiff,

    Doctrine\DBAL\Schema\Column,

    Doctrine\DBAL\Types\Type;

/**

 * Base class for all DatabasePlatforms. The DatabasePlatforms are the central

 * point of abstraction of platform-specific behaviors, features and SQL dialects.

 * They are a passive source of information.

 *

 * @license http://www.opensource.org/licenses/lgpl-license.php LGPL

 * @link    www.doctrine-project.org

 * @since   2.0

 * @version $Revision: 3938 $

 * @author  Guilherme Blanco <guilhermeblanco@hotmail.com>

 * @author  Jonathan Wage <jonwage@gmail.com>

 * @author  Roman Borschel <roman@code-factory.org>

 * @author  Lukas Smith <smith@pooteeweet.org> (PEAR MDB2 library)

 * @author  Benjamin Eberlei <kontakt@beberlei.de>

 * @todo Remove any unnecessary methods.

 */

abstract class AbstractPlatform

{

    /**

     * @var int

     */

    const CREATE_INDEXES = 1;

    /**

     * @var int

     */

    const CREATE_FOREIGNKEYS = 2;

    /**

     * @var int

     */

    const TRIM_UNSPECIFIED = 0;

    /**

     * @var int

     */

    const TRIM_LEADING = 1;

    /**

     * @var int

     */

    const TRIM_TRAILING = 2;

    /**

     * @var int

     */

    const TRIM_BOTH = 3;

    /**

     * @var array

     */

    protected $doctrineTypeMapping = null;

    /**

     * Contains a list of all columns that should generate parseable column comments for type-detection

     * in reverse engineering scenarios.

     *

     * @var array

     */

    protected $doctrineTypeComments = null;

    /**

     * Constructor.

     */

    public function __construct() {}

    /**

     * Gets the SQL snippet that declares a boolean column.

     *

     * @param array $columnDef

     * @return string

     */

    abstract public function getBooleanTypeDeclarationSQL(array $columnDef);

    /**

     * Gets the SQL snippet that declares a 4 byte integer column.

     *

     * @param array $columnDef

     * @return string

     */

    abstract public function getIntegerTypeDeclarationSQL(array $columnDef);

    /**

     * Gets the SQL snippet that declares an 8 byte integer column.

     *

     * @param array $columnDef

     * @return string

     */

    abstract public function getBigIntTypeDeclarationSQL(array $columnDef);

    /**

     * Gets the SQL snippet that declares a 2 byte integer column.

     *

     * @param array $columnDef

     * @return string

     */

    abstract public function getSmallIntTypeDeclarationSQL(array $columnDef);

    /**

     * Gets the SQL snippet that declares common properties of an integer column.

     *

     * @param array $columnDef

     * @return string

     */

    abstract protected function _getCommonIntegerTypeDeclarationSQL(array $columnDef);

    /**

     * Lazy load Doctrine Type Mappings

     *

     * @return void

     */

    abstract protected function initializeDoctrineTypeMappings();

    /**

     * Gets the SQL snippet used to declare a VARCHAR column type.

     *

     * @param array $field

     */

    public function getVarcharTypeDeclarationSQL(array $field)

    {

        if ( !isset($field['length'])) {

            $field['length'] = $this->getVarcharDefaultLength();

        }

        $fixed = (isset($field['fixed'])) ? $field['fixed'] : false;

        if ($field['length'] > $this->getVarcharMaxLength()) {

            return $this->getClobTypeDeclarationSQL($field);

        } else {

            return $this->getVarcharTypeDeclarationSQLSnippet($field['length'], $fixed);

        }

    }

    protected function getVarcharTypeDeclarationSQLSnippet($length, $fixed)

    {

        throw DBALException::notSupported('VARCHARs not supported by Platform.');

    }

    /**

     * Gets the SQL snippet used to declare a CLOB column type.

     *

     * @param array $field

     */

    abstract public function getClobTypeDeclarationSQL(array $field);

    /**

     * Gets the name of the platform.

     *

     * @return string

     */

    abstract public function getName();

    /**

     * Register a doctrine type to be used in conjunction with a column type of this platform.

     *

     * @param string $dbType

     * @param string $doctrineType

     */

    public function registerDoctrineTypeMapping($dbType, $doctrineType)

    {

        if ($this->doctrineTypeMapping === null) {

            $this->initializeDoctrineTypeMappings();

        }

        if (!Types\Type::hasType($doctrineType)) {

            throw DBALException::typeNotFound($doctrineType);

        }

        $dbType = strtolower($dbType);

        $this->doctrineTypeMapping[$dbType] = $doctrineType;

    }

    /**

     * Get the Doctrine type that is mapped for the given database column type.

     * 

     * @param  string $dbType

     * @return string

     */

    public function getDoctrineTypeMapping($dbType)

    {

        if ($this->doctrineTypeMapping === null) {

            $this->initializeDoctrineTypeMappings();

        }

        $dbType = strtolower($dbType);

        if (isset($this->doctrineTypeMapping[$dbType])) {

            return $this->doctrineTypeMapping[$dbType];

        } else {

            throw new \Doctrine\DBAL\DBALException("Unknown database type ".$dbType." requested, " . get_class($this) . " may not support it.");

        }

    }

    /**

     * Check if a database type is currently supported by this platform.

     *

     * @param string $dbType

     * @return bool

     */

    public function hasDoctrineTypeMappingFor($dbType)

    {

        if ($this->doctrineTypeMapping === null) {

            $this->initializeDoctrineTypeMappings();

        }

        $dbType = strtolower($dbType);

        return isset($this->doctrineTypeMapping[$dbType]);

    }

    /**

     * Initialize the Doctrine Type comments instance variable for in_array() checks.

     *

     * @return void

     */

    protected function initializeCommentedDoctrineTypes()

    {

        $this->doctrineTypeComments = array(Type::TARRAY, Type::OBJECT);

    }

    /**

     * Is it necessary for the platform to add a parsable type comment to allow reverse engineering the given type?

     *

     * @param Type $doctrineType

     * @return bool

     */

    public function isCommentedDoctrineType(Type $doctrineType)

    {

        if ($this->doctrineTypeComments === null) {

            $this->initializeCommentedDoctrineTypes();

        }

        return in_array($doctrineType->getName(), $this->doctrineTypeComments);

    }

    /**

     * Mark this type as to be commented in ALTER TABLE and CREATE TABLE statements.

     * 

     * @param Type $doctrineType

     * @return void

     */

    public function markDoctrineTypeCommented(Type $doctrineType)

    {

        if ($this->doctrineTypeComments === null) {

            $this->initializeCommentedDoctrineTypes();

        }

        $this->doctrineTypeComments[] = $doctrineType->getName();

    }

    /**

     * Get the comment to append to a column comment that helps parsing this type in reverse engineering.

     * 

     * @param Type $doctrineType

     * @return string

     */

    public function getDoctrineTypeComment(Type $doctrineType)

    {

        return '(DC2Type:' . $doctrineType->getName() . ')';

    }

    /**

     * Return the comment of a passed column modified by potential doctrine type comment hints.

     * 

     * @param Column $column

     * @return string

     */

    protected function getColumnComment(Column $column)

    {

        $comment = $column->getComment();

        if ($this->isCommentedDoctrineType($column->getType())) {

            $comment .= $this->getDoctrineTypeComment($column->getType());

        }

        return $comment;

    }

    /**

     * Gets the character used for identifier quoting.

     *

     * @return string

     */

    public function getIdentifierQuoteCharacter()

    {

        return '"';

    }

    /**

     * Gets the string portion that starts an SQL comment.

     *

     * @return string

     */

    public function getSqlCommentStartString()

    {

        return "--";

    }

    /**

     * Gets the string portion that ends an SQL comment.

     *

     * @return string

     */

    public function getSqlCommentEndString()

    {

        return "\n";

    }

    /**

     * Gets the maximum length of a varchar field.

     *

     * @return integer

     */

    public function getVarcharMaxLength()

    {

        return 4000;

    }

    /**

     * Gets the default length of a varchar field.

     *

     * @return integer

     */

    public function getVarcharDefaultLength()

    {

        return 255;

    }

    /**

     * Gets all SQL wildcard characters of the platform.

     *

     * @return array

     */

    public function getWildcards()

    {

        return array('%', '_');

    }

    /**

     * Returns the regular expression operator.

     *

     * @return string

     */

    public function getRegexpExpression()

    {

        throw DBALException::notSupported(__METHOD__);

    }

    /**

     * Returns the average value of a column

     *

     * @param string $column    the column to use

     * @return string           generated sql including an AVG aggregate function

     */

    public function getAvgExpression($column)

    {

        return 'AVG(' .  $column . ')';

    }

    /**

     * Returns the number of rows (without a NULL value) of a column

     *

     * If a '*' is used instead of a column the number of selected rows

     * is returned.

     *

     * @param string|integer $column    the column to use

     * @return string                   generated sql including a COUNT aggregate function

     */

    public function getCountExpression($column)

    {

        return 'COUNT(' . $column . ')';

    }

    /**

     * Returns the highest value of a column

     *

     * @param string $column    the column to use

     * @return string           generated sql including a MAX aggregate function

     */

    public function getMaxExpression($column)

    {

        return 'MAX(' . $column . ')';

    }

    /**

     * Returns the lowest value of a column

     *

     * @param string $column the column to use

     * @return string

     */

    public function getMinExpression($column)

    {

        return 'MIN(' . $column . ')';

    }

    /**

     * Returns the total sum of a column

     *

     * @param string $column the column to use

     * @return string

     */

    public function getSumExpression($column)

    {

        return 'SUM(' . $column . ')';

    }

    // scalar functions

    /**

     * Returns the md5 sum of a field.

     *

     * Note: Not SQL92, but common functionality

     *

     * @return string

     */

    public function getMd5Expression($column)

    {

        return 'MD5(' . $column . ')';

    }

    /**

     * Returns the length of a text field.

     *

     * @param string $expression1

     * @param string $expression2

     * @return string

     */

    public function getLengthExpression($column)

    {

        return 'LENGTH(' . $column . ')';

    }

    /**

     * Rounds a numeric field to the number of decimals specified.

     *

     * @param string $expression1

     * @param string $expression2

     * @return string

     */