Connector.php

TLDR

This file, Connector.php, is a part of the Illuminate\Database\Connectors namespace and contains the Connector class. The class is responsible for creating PDO connections, handling exceptions, and managing connection options.

Methods

createConnection

This method creates a new PDO connection. It takes a DSN, an array of configuration options, and an array of connection options as parameters. It returns a PDO instance. If an exception occurs during the connection creation, the method attempts to create a new connection if the exception was caused by a lost connection.

createPdoConnection

This protected method creates a new PDO connection instance. It takes a DSN, a username, a password, and an array of connection options as parameters. It returns a PDO instance.

tryAgainIfCausedByLostConnection

This protected method handles an exception that occurred during the execution of the createConnection method. It takes a throwable exception, a DSN, a username, a password, and an array of connection options as parameters. If the exception was caused by a lost connection, it attempts to create a new connection by calling the createPdoConnection method. Otherwise, it rethrows the exception.

getOptions

This method retrieves the PDO options based on the given configuration. It takes an array of connection configuration as a parameter and returns an array of PDO options.

getDefaultOptions

This method retrieves the default PDO connection options. It returns an array of PDO options.

setDefaultOptions

This method sets the default PDO connection options. It takes an array of PDO options as a parameter and does not return anything.

Classes

Class Connector

The Connector class is responsible for creating PDO connections, handling exceptions, and managing connection options. It uses the DetectsLostConnections trait. The class contains the above-mentioned methods.

<?php

namespace Illuminate\Database\Connectors;

use Exception;
use Illuminate\Database\DetectsLostConnections;
use PDO;
use Throwable;

class Connector
{
    use DetectsLostConnections;

    /**
     * The default PDO connection options.
     *
     * @var array
     */
    protected $options = [
        PDO::ATTR_CASE => PDO::CASE_NATURAL,
        PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
        PDO::ATTR_ORACLE_NULLS => PDO::NULL_NATURAL,
        PDO::ATTR_STRINGIFY_FETCHES => false,
        PDO::ATTR_EMULATE_PREPARES => false,
    ];

    /**
     * Create a new PDO connection.
     *
     * @param  string  $dsn
     * @param  array  $config
     * @param  array  $options
     * @return \PDO
     *
     * @throws \Exception
     */
    public function createConnection($dsn, array $config, array $options)
    {
        [$username, $password] = [
            $config['username'] ?? null, $config['password'] ?? null,
        ];

        try {
            return $this->createPdoConnection(
                $dsn, $username, $password, $options
            );
        } catch (Exception $e) {
            return $this->tryAgainIfCausedByLostConnection(
                $e, $dsn, $username, $password, $options
            );
        }
    }

    /**
     * Create a new PDO connection instance.
     *
     * @param  string  $dsn
     * @param  string  $username
     * @param  string  $password
     * @param  array  $options
     * @return \PDO
     */
    protected function createPdoConnection($dsn, $username, $password, $options)
    {
        return new PDO($dsn, $username, $password, $options);
    }

    /**
     * Handle an exception that occurred during connect execution.
     *
     * @param  \Throwable  $e
     * @param  string  $dsn
     * @param  string  $username
     * @param  string  $password
     * @param  array  $options
     * @return \PDO
     *
     * @throws \Exception
     */
    protected function tryAgainIfCausedByLostConnection(Throwable $e, $dsn, $username, $password, $options)
    {
        if ($this->causedByLostConnection($e)) {
            return $this->createPdoConnection($dsn, $username, $password, $options);
        }

        throw $e;
    }

    /**
     * Get the PDO options based on the configuration.
     *
     * @param  array  $config
     * @return array
     */
    public function getOptions(array $config)
    {
        $options = $config['options'] ?? [];

        return array_diff_key($this->options, $options) + $options;
    }

    /**
     * Get the default PDO connection options.
     *
     * @return array
     */
    public function getDefaultOptions()
    {
        return $this->options;
    }

    /**
     * Set the default PDO connection options.
     *
     * @param  array  $options
     * @return void
     */
    public function setDefaultOptions(array $options)
    {
        $this->options = $options;
    }
}