Helix\DB

Complexity

Total Complexity

50

Size/Duplication

Total Lines	560
Duplicated Lines	0 %

Importance

Changes	6
Bugs	0	Features	0

69 Methods

Rating	Name	Duplication	Size	Complexity
	quoteArray()	0	3	?
A	hp$0 ➔ offsetSet()	0	3	1
A	hp$0 ➔ getMigrator()	0	3	1
	factory()	0	3	?
	slots()	0	5	?
A	hp$0 ➔ offsetExists()	0	3	1
A	hp$0 ➔ offsetGet()	0	3	1
A	hp$0 ➔ getRecord()	0	4	2
A	hp$0 ➔ quoteArray()	0	3	1
	setRecord()	0	4	?
A	hp$0 ➔ isPostgreSQL()	0	3	1
	__toString()	0	3	?
	quoteList()	0	3	?
A	hp$0 ➔ prepare()	0	4	1
A	hp$0 ➔ quote()	0	15	6
A	hp$0 ➔ getSchema()	0	3	1
	exec()	0	4	?
A	hp$0 ➔ setLogger()	0	4	1
A	hp$0 ➔ offsetUnset()	0	3	1
	newTransaction()	0	3	?
	offsetUnset()	0	3	?
A	hp$0 ➔ quoteList()	0	3	1
	log()	0	3	?
	isSQLite()	0	3	?
A	hp$0 ➔ exec()	0	4	1
	getRecord()	0	4	?
	slotsEqual()	0	7	?
	commit()	0	12	?
	getJunction()	0	3	?
	getDriver()	0	3	?
	prepare()	0	4	?
	__construct()	0	45	?
A	hp$0 ➔ isMySQL()	0	3	1
A	hp$0 ➔ slotsEqual()	0	7	2
A	hp$0 ➔ setRecord()	0	4	1
A	hp$0 ➔ newTransaction()	0	3	1
	marks()	0	11	?
	quote()	0	15	?
	offsetExists()	0	3	?
A	hp$0 ➔ slots()	0	5	1
A	hp$0 ➔ query()	0	4	1
	isPostgreSQL()	0	3	?
	sqliteCreateFunctions()	0	6	?
A	hp$0 ➔ __construct()	0	45	3
A	hp$0 ➔ getLogger()	0	3	1
	getSchema()	0	3	?
A	hp$0 ➔ getJunction()	0	3	1
A	hp$0 ➔ isSQLite()	0	3	1
	offsetSet()	0	3	?
	isMySQL()	0	3	?
	query()	0	4	?
A	hp$0 ➔ marks()	0	11	2
A	hp$0 ➔ beginTransaction()	0	11	2
A	hp$0 ➔ transact()	0	6	1
	beginTransaction()	0	11	?
A	hp$0 ➔ log()	0	3	1
	transact()	0	6	?
A	hp$0 ➔ __toString()	0	3	1
	getLogger()	0	3	?
A	hp$0 ➔ rollBack()	0	12	2
A	hp$0 ➔ commit()	0	12	2
A	hp$0 ➔ sqliteCreateFunctions()	0	6	3
	setLogger()	0	4	?
	offsetGet()	0	3	?
A	hp$0 ➔ getDriver()	0	3	1
A	fromConfig()	0	14	1
	getMigrator()	0	3	?
A	hp$0 ➔ factory()	0	3	1
	rollBack()	0	12	?

<?php

namespace Helix;

use ArrayAccess;
use Countable;
use Helix\DB\EntityInterface;
use Helix\DB\Fluent\ExpressionInterface;
use Helix\DB\Junction;
use Helix\DB\Migrator;
use Helix\DB\Record;
use Helix\DB\Schema;
use Helix\DB\Statement;
use Helix\DB\Table;
use Helix\DB\Transaction;
use LogicException;
use PDO;
use ReflectionFunction;

/**
 * Extends `PDO` and acts as a central access point for the schema.
 */
class DB extends PDO implements ArrayAccess
{

    /**
     * The driver's name.
     *
     * - mysql
     * - sqlite
     *
     * @var string
     */
    protected $driver;

    /**
     * @var Junction[]
     */
    protected $junctions = [];

    /**
     * Notified whenever a query is executed or a statement is prepared.
     * This is a stub-closure by default.
     *
     * `fn($sql): void`
     *
     * @var callable
     */
    protected $logger;

    /**
     * The migrations directory for this connection.
     *
     * This can be set via class override, or configuration file (recommended).
     *
     * When using {@link DB::fromConfig()}, this defaults to `migrations/<CONNECTION NAME>`
     *
     * @var string
     */
    protected $migrations = 'migrations/default';

    /**
     * @var Record[]
     */
    protected $records = [];

    /**
     * @var Schema
     */
    protected $schema;

    /**
     * The count of open transactions/savepoints.
     *
     * @var int
     */
    protected $transactions = 0;

    /**
     * Returns a new connection using a configuration file.
     *
     * See `db.config.php` in the `test` directory for an example.
     *
     * @param string $connection
     * @param string $file
     * @return static
     */
    public static function fromConfig(string $connection = 'default', string $file = 'db.config.php')
    {
        $config = (include "{$file}")[$connection];
        $args = [
            $config['dsn'],
            $config['username'] ?? null,
            $config['password'] ?? null,
            $config['options'] ?? []
        ];
        $class = $config['class'] ?? static::class;
        $db = new $class(...$args);
        $db->logger = $config['logger'] ?? $db->logger;
        $db->migrations = $config['migrations'] ?? "migrations/{$connection}";
        return $db;
    }

    /**
     * Returns an array of `?` placeholder expressions.
     *
     * @param int|array|Countable $count
     * @return ExpressionInterface[]
     */
    public static function marks($count)
    {
        static $mark;
        $mark ??= new class implements ExpressionInterface {

            public function __toString()
            {
                return '?';
            }
        };
        return array_fill(0, is_int($count) ? $count : count($count), $mark);
    }

    /**
     * Converts an array of columns to `:named` placeholders for prepared queries.
     *
     * Qualified columns are slotted as `qualifier__column` (two underscores).
     *
     * @param string[] $columns
     * @return string[] `["column" => ":column"]`
     */
    public static function slots(array $columns)
    {
        return array_combine($columns, array_map(function (string $column) {
            return ':' . str_replace('.', '__', $column);
        }, $columns));
    }

    /**
     * @param string[] $columns
     * @return string[] `["column" => "column=:column"]`
     */
    public static function slotsEqual(array $columns)
    {
        $slots = static::slots($columns);
        foreach ($slots as $column => $slot) {
            $slots[$column] = "{$column} = {$slot}";
        }
        return $slots;
    }

    /**
     * Sets various attributes to streamline operations.
     *
     * Registers missing SQLite functions.
     *
     * @param string $dsn
     * @param string $username
     * @param string $password
     * @param array $options
     */
    public function __construct($dsn, $username = null, $password = null, array $options = [])
    {
        $options[self::ATTR_STATEMENT_CLASS] ??= [Statement::class, [$this]];
        parent::__construct($dsn, $username, $password, $options);
        $this->setAttribute(self::ATTR_DEFAULT_FETCH_MODE, self::FETCH_ASSOC);
        $this->setAttribute(self::ATTR_EMULATE_PREPARES, false);
        $this->setAttribute(self::ATTR_ERRMODE, self::ERRMODE_EXCEPTION);
        $this->setAttribute(self::ATTR_STRINGIFY_FETCHES, false);
        $this->driver = $this->getAttribute(self::ATTR_DRIVER_NAME);
        $this->logger ??= fn() => null;
        $this->schema ??= Schema::factory($this);

        if ($this->isMySQL()) {
            $this->exec("SET time_zone = 'UTC'");
        } elseif ($this->isSQLite()) {
            // polyfill sqlite functions
            $this->sqliteCreateFunctions([ // deterministic functions
                // https://www.sqlite.org/lang_mathfunc.html
                'ACOS' => 'acos',
                'ASIN' => 'asin',
                'ATAN' => 'atan',
                'CEIL' => 'ceil',
                'COS' => 'cos',
                'DEGREES' => 'rad2deg',
                'EXP' => 'exp',
                'FLOOR' => 'floor',
                'LN' => 'log',
                'LOG' => fn($b, $x) => log($x, $b),
                'LOG10' => 'log10',
                'LOG2' => fn($x) => log($x, 2),
                'PI' => 'pi',
                'POW' => 'pow',
                'RADIANS' => 'deg2rad',
                'SIN' => 'sin',
                'SQRT' => 'sqrt',
                'TAN' => 'tan',

                // these are not in sqlite at all but are in other dbms
                'CONV' => 'base_convert',
                'SIGN' => fn($x) => $x <=> 0
            ]);

            $this->sqliteCreateFunctions([ // non-deterministic
                'RAND' => fn() => mt_rand() / mt_getrandmax(),
            ], false);
        }
    }

    /**
     * The driver's name.
     *
     * @return string
     */
    final public function __toString(): string
    {
        return $this->driver;
    }

    /**
     * Allows nested transactions by using `SAVEPOINT`
     *
     * Use {@link DB::newTransaction()} to work with {@link Transaction} instead.
     *
     * @return true
     */
    public function beginTransaction()
    {
        assert($this->transactions >= 0);
        if ($this->transactions === 0) {
            $this->log("BEGIN TRANSACTION");
            parent::beginTransaction();
        } else {
            $this->exec("SAVEPOINT SAVEPOINT_{$this->transactions}");
        }
        $this->transactions++;
        return true;
    }

    /**
     * Allows nested transactions by using `RELEASE SAVEPOINT`
     *
     * Use {@link DB::newTransaction()} to work with {@link Transaction} instead.
     *
     * @return true
     */
    public function commit()
    {
        assert($this->transactions > 0);
        if ($this->transactions === 1) {
            $this->log("COMMIT TRANSACTION");
            parent::commit();
        } else {
            $savepoint = $this->transactions - 1;
            $this->exec("RELEASE SAVEPOINT SAVEPOINT_{$savepoint}");
        }
        $this->transactions--;
        return true;
    }

    /**
     * Notifies the logger and executes.
     *
     * @param string $sql
     * @return int
     */
    public function exec($sql): int
    {
        $this->log($sql);
        return parent::exec($sql);
    }

    /**
     * Central point of object creation.
     *
     * Override this to override classes.
     *
     * The only thing that calls this should be {@link \Helix\DB\FactoryTrait}
     *
     * @param string $class
     * @param mixed ...$args
     * @return mixed
     */
    public function factory(string $class, ...$args)
    {
        return new $class($this, ...$args);
    }

    /**
     * @return string
     */
    final public function getDriver(): string
    {
        return $this->driver;
    }

    /**
     * Returns a {@link Junction} access object based on an annotated interface.
     *
     * @param string $interface
     * @return Junction
     */
    public function getJunction(string $interface)
    {
        return $this->junctions[$interface] ??= Junction::factory($this, $interface);
    }

    /**
     * @return callable
     */
    final public function getLogger()
    {
        return $this->logger;
    }

    /**
     * @param string $dir
     * @return Migrator
     */
    public function getMigrator()
    {
        return Migrator::factory($this, $this->migrations);
    }

    /**
     * Returns a {@link Record} access object based on an annotated class.
     *
     * @param string|EntityInterface $class
     * @return Record
     */
    public function getRecord($class)
    {
        $name = is_object($class) ? get_class($class) : $class;
        return $this->records[$name] ??= Record::factory($this, $class);
    }

    /**
     * @return Schema
     */
    public function getSchema()
    {
        return $this->schema;
    }

    /**
     * @return bool
     */
    final public function isMySQL(): bool
    {
        return $this->driver === 'mysql';
    }

    /**
     * @return bool
     */
    final public function isPostgreSQL(): bool
    {
        return $this->driver === 'pgsql';
    }

    /**
     * @return bool
     */
    final public function isSQLite(): bool
    {
        return $this->driver === 'sqlite';
    }

    /**
     * @param string $sql
     */
    public function log(string $sql): void
    {
        call_user_func($this->logger, $sql);
    }

    /**
     * Returns a scoped transaction.
     *
     * @return Transaction
     */
    public function newTransaction()
    {
        return Transaction::factory($this);
    }

    /**
     * Whether a table exists.
     *
     * @param string $table
     * @return bool
     */
    final public function offsetExists($table): bool
    {
        return (bool)$this->offsetGet($table);
    }

    /**
     * Returns a table by name.
     *
     * @param string $table
     * @return null|Table
     */
    public function offsetGet($table)
    {
        return $this->schema->getTable($table);
    }

    /**
     * Throws.
     *
     * @param $offset
     * @param $value
     * @throws LogicException
     */
    final public function offsetSet($offset, $value)
    {
        throw new LogicException('The schema cannot be altered this way.');
    }

    /**
     * Throws.
     *
     * @param $offset
     * @throws LogicException
     */
    final public function offsetUnset($offset)
    {
        throw new LogicException('The schema cannot be altered this way.');
    }

    /**
     * Notifies the logger and prepares a statement.
     *
     * @param string $sql
     * @param array $options
     * @return Statement
     */
    public function prepare($sql, $options = [])
    {
        $this->log($sql);
        return parent::{'prepare'}($sql, $options);
    }

    /**
     * Notifies the logger and queries.
     *
     * @param string $sql
     * @param int $mode
     * @param mixed $arg3
     * @param array $ctorargs
     * @return Statement
     */
    public function query($sql, $mode = PDO::ATTR_DEFAULT_FETCH_MODE, $arg3 = null, array $ctorargs = [])
    {
        $this->log($sql);
        return parent::{'query'}(...func_get_args());
    }

    /**
     * Quotes a value, with special considerations.
     *
     * - {@link ExpressionInterface} instances are returned as-is.
     * - Booleans and integers are returned as unquoted integer-string.
     * - Everything else is returned as a quoted string.
     *
     * @param bool|number|string|object $value
     * @param int $type Ignored.
     * @return string|ExpressionInterface
     */
    public function quote($value, $type = self::PARAM_STR)
    {
        if ($value instanceof ExpressionInterface) {
            return $value;
        }
        if ($value instanceof EntityInterface) {
            return (string)$value->getId();
        }
        switch (gettype($value)) {
            case 'integer' :
            case 'boolean' :
            case 'resource' :
                return (string)(int)$value;
            default:
                return parent::quote((string)$value);
        }
    }

    /**
     * Quotes an array of values. Keys are preserved.
     *
     * @param array $values
     * @return string[]
     */
    public function quoteArray(array $values)
    {
        return array_map([$this, 'quote'], $values);
    }

    /**
     * Returns a quoted, comma-separated list.
     *
     * @param array $values
     * @return string
     */
    public function quoteList(array $values): string
    {
        return implode(',', $this->quoteArray($values));
    }

    /**
     * Allows nested transactions by using `ROLLBACK TO SAVEPOINT`
     *
     * Use {@link DB::newTransaction()} to work with {@link Transaction} instead.
     *
     * @return true
     */
    public function rollBack()
    {
        assert($this->transactions > 0);
        if ($this->transactions === 1) {
            $this->log("ROLLBACK TRANSACTION");
            parent::rollBack();
        } else {
            $savepoint = $this->transactions - 1;
            $this->exec("ROLLBACK TO SAVEPOINT SAVEPOINT_{$savepoint}");
        }
        $this->transactions--;
        return true;
    }

    /**
     * @param callable $logger
     * @return $this
     */
    public function setLogger(callable $logger)
    {
        $this->logger = $logger;
        return $this;
    }

    /**
     * Installs a {@link Record} for a third-party class that cannot be annotated.
     *
     * @param string $class
     * @param Record $record
     * @return $this
     */
    public function setRecord(string $class, Record $record)
    {
        $this->records[$class] = $record;
        return $this;
    }

    /**
     * Create multiple SQLite functions at a time.
     *
     * @param callable[] $callables Keyed by function name.
     * @param bool $deterministic Whether the callables aren't random / are without side-effects.
     */
    public function sqliteCreateFunctions(array $callables, bool $deterministic = true): void
    {
        $deterministic = $deterministic ? self::SQLITE_DETERMINISTIC : 0;
        foreach ($callables as $name => $callable) {
            $argc = (new ReflectionFunction($callable))->getNumberOfRequiredParameters();
            $this->sqliteCreateFunction($name, $callable, $argc, $deterministic);
        }
    }

    /**
     * Performs work within a scoped transaction.
     *
     * The work is rolled back if an exception is thrown.
     *
     * @param callable $work `fn(): mixed`
     * @return mixed The return value of `$work`
     */
    public function transact(callable $work)
    {
        $transaction = $this->newTransaction();
        $return = call_user_func($work);
        $transaction->commit();
        return $return;
    }
}