DBALException.php 9.51 KB
Newer Older
1
<?php
Benjamin Morel's avatar
Benjamin Morel committed
2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
/*
 * 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>.
 */
19 20 21

namespace Doctrine\DBAL;

22 23
use Doctrine\DBAL\Exception;
use Doctrine\DBAL\Driver;
24
use Doctrine\DBAL\Driver\ExceptionConverterDriver;
25
use Doctrine\DBAL\Platforms\AbstractPlatform;
26 27 28 29 30 31 32 33
use function array_map;
use function bin2hex;
use function implode;
use function is_resource;
use function is_string;
use function json_encode;
use function sprintf;
use function str_split;
34

35 36
class DBALException extends \Exception
{
Benjamin Morel's avatar
Benjamin Morel committed
37 38 39 40 41
    /**
     * @param string $method
     *
     * @return \Doctrine\DBAL\DBALException
     */
42 43
    public static function notSupported($method)
    {
44
        return new self("Operation '$method' is not supported by platform.");
45
    }
46

47 48 49 50 51 52 53
    public static function invalidPlatformSpecified() : self
    {
        return new self(
            "Invalid 'platform' option specified, need to give an instance of ".
            "\Doctrine\DBAL\Platforms\AbstractPlatform.");
    }

Benjamin Morel's avatar
Benjamin Morel committed
54
    /**
55
     * @param mixed $invalidPlatform
Benjamin Morel's avatar
Benjamin Morel committed
56
     */
57
    public static function invalidPlatformType($invalidPlatform) : self
58
    {
59
        if (\is_object($invalidPlatform)) {
60 61 62 63
            return new self(
                sprintf(
                    "Option 'platform' must be a subtype of '%s', instance of '%s' given",
                    AbstractPlatform::class,
64
                    \get_class($invalidPlatform)
65 66 67 68
                )
            );
        }

69
        return new self(
70
            sprintf(
71 72
                "Option 'platform' must be an object and subtype of '%s'. Got '%s'",
                AbstractPlatform::class,
73
                \gettype($invalidPlatform)
74 75
            )
        );
76 77
    }

78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97
    /**
     * Returns a new instance for an invalid specified platform version.
     *
     * @param string $version        The invalid platform version given.
     * @param string $expectedFormat The expected platform version format.
     *
     * @return DBALException
     */
    public static function invalidPlatformVersionSpecified($version, $expectedFormat)
    {
        return new self(
            sprintf(
                'Invalid platform version "%s" specified. ' .
                'The platform version has to be specified in the format: "%s".',
                $version,
                $expectedFormat
            )
        );
    }

Benjamin Morel's avatar
Benjamin Morel committed
98 99 100
    /**
     * @return \Doctrine\DBAL\DBALException
     */
101 102 103 104 105 106 107 108
    public static function invalidPdoInstance()
    {
        return new self(
            "The 'pdo' option was used in DriverManager::getConnection() but no ".
            "instance of PDO was given."
        );
    }

Benjamin Morel's avatar
Benjamin Morel committed
109
    /**
110
     * @param string|null $url The URL that was provided in the connection parameters (if any).
111
     *
Benjamin Morel's avatar
Benjamin Morel committed
112 113
     * @return \Doctrine\DBAL\DBALException
     */
114
    public static function driverRequired($url = null)
115
    {
116 117 118 119 120 121 122 123 124 125
        if ($url) {
            return new self(
                sprintf(
                    "The options 'driver' or 'driverClass' are mandatory if a connection URL without scheme " .
                    "is given to DriverManager::getConnection(). Given URL: %s",
                    $url
                )
            );
        }

126 127 128 129
        return new self("The options 'driver' or 'driverClass' are mandatory if no PDO ".
            "instance is given to DriverManager::getConnection().");
    }

Benjamin Morel's avatar
Benjamin Morel committed
130 131 132 133 134 135
    /**
     * @param string $unknownDriverName
     * @param array  $knownDrivers
     *
     * @return \Doctrine\DBAL\DBALException
     */
136 137 138 139
    public static function unknownDriver($unknownDriverName, array $knownDrivers)
    {
        return new self("The given 'driver' ".$unknownDriverName." is unknown, ".
            "Doctrine currently supports only the following drivers: ".implode(", ", $knownDrivers));
140
    }
141

Benjamin Morel's avatar
Benjamin Morel committed
142
    /**
143 144 145 146
     * @param \Doctrine\DBAL\Driver $driver
     * @param \Exception            $driverEx
     * @param string                $sql
     * @param array                 $params
Benjamin Morel's avatar
Benjamin Morel committed
147 148 149
     *
     * @return \Doctrine\DBAL\DBALException
     */
150
    public static function driverExceptionDuringQuery(Driver $driver, \Exception $driverEx, $sql, array $params = [])
151 152 153
    {
        $msg = "An exception occurred while executing '".$sql."'";
        if ($params) {
154
            $msg .= " with params " . self::formatParameters($params);
155 156 157
        }
        $msg .= ":\n\n".$driverEx->getMessage();

158
        return static::wrapException($driver, $driverEx, $msg);
159 160
    }

161
    /**
162 163
     * @param \Doctrine\DBAL\Driver $driver
     * @param \Exception            $driverEx
164 165 166 167 168
     *
     * @return \Doctrine\DBAL\DBALException
     */
    public static function driverException(Driver $driver, \Exception $driverEx)
    {
169 170
        return static::wrapException($driver, $driverEx, "An exception occurred in driver: " . $driverEx->getMessage());
    }
171

172
    /**
173 174
     * @param \Doctrine\DBAL\Driver $driver
     * @param \Exception            $driverEx
175 176 177 178 179 180 181 182 183
     *
     * @return \Doctrine\DBAL\DBALException
     */
    private static function wrapException(Driver $driver, \Exception $driverEx, $msg)
    {
        if ($driverEx instanceof Exception\DriverException) {
            return $driverEx;
        }
        if ($driver instanceof ExceptionConverterDriver && $driverEx instanceof Driver\DriverException) {
184
            return $driver->convertException($msg, $driverEx);
185
        }
186 187

        return new self($msg, 0, $driverEx);
188 189
    }

190 191 192 193 194 195 196 197 198 199
    /**
     * Returns a human-readable representation of an array of parameters.
     * This properly handles binary data by returning a hex representation.
     *
     * @param array $params
     *
     * @return string
     */
    private static function formatParameters(array $params)
    {
Steve Müller's avatar
Steve Müller committed
200
        return '[' . implode(', ', array_map(function ($param) {
201 202 203 204
            if (is_resource($param)) {
                return (string) $param;
            }
            
205 206 207 208 209 210 211 212 213 214 215
            $json = @json_encode($param);

            if (! is_string($json) || $json == 'null' && is_string($param)) {
                // JSON encoding failed, this is not a UTF-8 string.
                return '"\x' . implode('\x', str_split(bin2hex($param), 2)) . '"';
            }

            return $json;
        }, $params)) . ']';
    }

Benjamin Morel's avatar
Benjamin Morel committed
216 217 218 219 220
    /**
     * @param string $wrapperClass
     *
     * @return \Doctrine\DBAL\DBALException
     */
221 222 223 224 225 226
    public static function invalidWrapperClass($wrapperClass)
    {
        return new self("The given 'wrapperClass' ".$wrapperClass." has to be a ".
            "subtype of \Doctrine\DBAL\Connection.");
    }

Benjamin Morel's avatar
Benjamin Morel committed
227 228 229 230 231
    /**
     * @param string $driverClass
     *
     * @return \Doctrine\DBAL\DBALException
     */
232 233 234 235 236
    public static function invalidDriverClass($driverClass)
    {
        return new self("The given 'driverClass' ".$driverClass." has to implement the ".
            "\Doctrine\DBAL\Driver interface.");
    }
237 238 239

    /**
     * @param string $tableName
Benjamin Morel's avatar
Benjamin Morel committed
240 241
     *
     * @return \Doctrine\DBAL\DBALException
242 243 244 245 246 247 248 249
     */
    public static function invalidTableName($tableName)
    {
        return new self("Invalid table name specified: ".$tableName);
    }

    /**
     * @param string $tableName
Benjamin Morel's avatar
Benjamin Morel committed
250 251
     *
     * @return \Doctrine\DBAL\DBALException
252 253 254 255 256 257
     */
    public static function noColumnsSpecifiedForTable($tableName)
    {
        return new self("No columns specified for table ".$tableName);
    }

Benjamin Morel's avatar
Benjamin Morel committed
258 259 260
    /**
     * @return \Doctrine\DBAL\DBALException
     */
261 262
    public static function limitOffsetInvalid()
    {
263
        return new self("Invalid Offset in Limit Query, it has to be larger than or equal to 0.");
264
    }
265

Benjamin Morel's avatar
Benjamin Morel committed
266 267 268 269 270
    /**
     * @param string $name
     *
     * @return \Doctrine\DBAL\DBALException
     */
271 272 273 274 275
    public static function typeExists($name)
    {
        return new self('Type '.$name.' already exists.');
    }

Benjamin Morel's avatar
Benjamin Morel committed
276 277 278 279 280
    /**
     * @param string $name
     *
     * @return \Doctrine\DBAL\DBALException
     */
281 282
    public static function unknownColumnType($name)
    {
283 284
        return new self('Unknown column type "'.$name.'" requested. Any Doctrine type that you use has ' .
            'to be registered with \Doctrine\DBAL\Types\Type::addType(). You can get a list of all the ' .
285
            'known types with \Doctrine\DBAL\Types\Type::getTypesMap(). If this error occurs during database ' .
286
            'introspection then you might have forgotten to register all database types for a Doctrine Type. Use ' .
287 288
            'AbstractPlatform#registerDoctrineTypeMapping() or have your custom types implement ' .
            'Type#getMappedDatabaseTypes(). If the type name is empty you might ' .
289 290
            'have a problem with the cache or forgot some mapping information.'
        );
291 292
    }

Benjamin Morel's avatar
Benjamin Morel committed
293 294 295 296 297
    /**
     * @param string $name
     *
     * @return \Doctrine\DBAL\DBALException
     */
298 299 300 301
    public static function typeNotFound($name)
    {
        return new self('Type to be overwritten '.$name.' does not exist.');
    }
302
}