[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   *
   4   * This file is part of Aura for PHP.
   5   *
   6   * @license https://opensource.org/licenses/MIT MIT
   7   *
   8   */
   9  namespace Aura\Sql;
  10  
  11  use Aura\Sql\Profiler\Profiler;
  12  use Aura\Sql\Profiler\ProfilerInterface;
  13  use PDO;
  14  
  15  /**
  16   *
  17   * A lazy-connecting PDO with extended methods.
  18   *
  19   * @package Aura.Sql
  20   *
  21   */
  22  class ExtendedPdo extends AbstractExtendedPdo
  23  {
  24      public const CONNECT_IMMEDIATELY = 'auraSqlImmediate';
  25      public const DRIVER_SPECIFIC     = 'auraSqlDriverSpecific';
  26  
  27      /**
  28       *
  29       * Constructor arguments for instantiating the PDO connection.
  30       *
  31       * @var array
  32       *
  33       */
  34      protected array $args = [];
  35  
  36      /**
  37       *
  38       * Flag for how to construct the PDO object
  39       *
  40       * @var bool
  41       */
  42      protected bool $driverSpecific = false;
  43  
  44      /**
  45       *
  46       * Constructor.
  47       *
  48       * This overrides the parent so that it can take connection attributes as a
  49       * constructor parameter, and set them after connection.
  50       *
  51       * @param string $dsn The data source name for the connection.
  52       *
  53       * @param string|null $username The username for the connection.
  54       *
  55       * @param string|null $password The password for the connection.
  56       *
  57       * @param array $options Driver-specific options for the connection.
  58       *
  59       * @param array $queries Queries to execute after the connection.
  60       *
  61       * @param \Aura\Sql\Profiler\ProfilerInterface|null $profiler Tracks and logs query profiles.
  62       *
  63       * @see http://php.net/manual/en/pdo.construct.php
  64       */
  65      public function __construct(
  66          string $dsn,
  67          ?string $username = null,
  68          ?string $password = null,
  69          array $options = [],
  70          array $queries = [],
  71          ?ProfilerInterface $profiler = null
  72      ) {
  73          // if no error mode is specified, use exceptions
  74          if (! isset($options[PDO::ATTR_ERRMODE])) {
  75              $options[PDO::ATTR_ERRMODE] = PDO::ERRMODE_EXCEPTION;
  76          }
  77  
  78          // check option for driver specific construct and set flag for lazy loading later
  79          if (isset($options[static::DRIVER_SPECIFIC])) {
  80              $this->driverSpecific = (bool)$options[static::DRIVER_SPECIFIC];
  81              unset($options[static::DRIVER_SPECIFIC]);
  82          }
  83  
  84          // retain the arguments for later
  85          $this->args = [
  86              $dsn,
  87              $username,
  88              $password,
  89              $options,
  90              $queries
  91          ];
  92  
  93          // retain a profiler, instantiating a default one if needed
  94          $this->setProfiler($profiler ?? new Profiler());
  95  
  96          // retain a query parser
  97          $parts = explode(":", $dsn);
  98          $parser = $this->newParser($parts[0]);
  99          $this->setParser($parser);
 100  
 101          // set quotes for identifier names
 102          $this->setQuoteName($parts[0]);
 103  
 104          // create a connection immediately
 105          if (isset($options[static::CONNECT_IMMEDIATELY])) {
 106              $connectImmediately = (bool)$options[static::CONNECT_IMMEDIATELY];
 107              unset($options[static::CONNECT_IMMEDIATELY]);
 108              if ($connectImmediately) {
 109                  $this->lazyConnect();
 110              }
 111          }
 112      }
 113  
 114      public static function connect(
 115          string $dsn,
 116          ?string $username = null,
 117          ?string $password = null,
 118          ?array $options = null,
 119          array $queries = [],
 120          ?ProfilerInterface $profiler = null
 121      ): static {
 122          $options                          ??= [];
 123          $options[static::DRIVER_SPECIFIC] = true;
 124          return new static($dsn, $username, $password, $options, $queries, $profiler);
 125      }
 126  
 127      /**
 128       *
 129       * Connects to the database.
 130       *
 131       * @return void
 132       */
 133      public function lazyConnect(): void
 134      {
 135          if ($this->pdo) {
 136              return;
 137          }
 138  
 139          // connect
 140          $this->profiler->start(__FUNCTION__);
 141          list($dsn, $username, $password, $options, $queries) = $this->args;
 142          if ($this->driverSpecific && version_compare(PHP_VERSION, '8.4.0', '>=')) {
 143              $this->pdo = PDO::connect($dsn, $username, $password, $options);
 144          } else {
 145              $this->pdo = new PDO($dsn, $username, $password, $options);
 146          }
 147          $this->pdo = new PDO($dsn, $username, $password, $options);
 148          $this->profiler->finish();
 149  
 150          // connection-time queries
 151          foreach ($queries as $query) {
 152              $this->exec($query);
 153          }
 154      }
 155  
 156      /**
 157       *
 158       * Disconnects from the database.
 159       *
 160       * @return void
 161       *
 162       */
 163      public function disconnect(): void
 164      {
 165          $this->profiler->start(__FUNCTION__);
 166          $this->pdo = null;
 167          $this->profiler->finish();
 168      }
 169  
 170      /**
 171       *
 172       * The purpose of this method is to hide sensitive data from stack traces.
 173       *
 174       * @return array
 175       *
 176       */
 177      public function __debugInfo(): array
 178      {
 179          return [
 180              'args' => [
 181                  $this->args[0],
 182                  '****',
 183                  '****',
 184                  $this->args[3],
 185                  $this->args[4],
 186              ],
 187          ];
 188      }
 189  
 190      /**
 191       *
 192       * Return the inner PDO (if any)
 193       *
 194       * @return \PDO
 195       *
 196       */
 197      public function getPdo(): PDO
 198      {
 199          $this->lazyConnect();
 200          return $this->pdo;
 201      }
 202  }