gajus / doll
Extended PDO with inline type hinting, deferred connection support, logging and benchmarking.
Requires
- php: >=5.4
- ext-pdo: *
- psr/log: 1.0.0
Requires (Dev)
- satooshi/php-coveralls: dev-master
This package is not auto-updated.
Last update: 2024-11-19 01:52:56 UTC
README
Extended PDO with inline type hinting, deferred connection support, logging and benchmarking.
Single Parameter Constructor
PDO::__construct is using Data Source Name (DSN) string to describe the connection. PDO DSN implementation does not include user, password and driver options.
Doll instance is described using DataSource
object:
$data_source = new \Gajus\Doll\DataSource([ 'host' => '127.0.0.1', 'driver' => 'mysql', 'database' => null, 'user' => null, 'password' => null, 'charset' => 'utf8', 'driver_options' => [] ]);
Deferred Connection
PDO will establish a connection to the database upon initialization. If application initializes PDO during the bootstrap, but does not execute queries (e.g. request that is served from cache), the connection is unnecessary.
Doll will not connect to the database upon initialization:
$db = new \Gajus\Doll\PDO($data_source);
The connection is deferred until either of the following methods are invoked:
- PDO::prepare()
- PDO::exec()
- PDO::query()
- PDO::beginTransaction()
- PDO::commit()
- PDO::rollBack()
- PDOStatement::execute()
Default Attributes
Values for attributes not in the table do not differ.
Method Chaining
PDOStatement::execute() returns a boolean value indicating the state of the transaction, e.g.
$sth = $db->prepare("SELECT ?"); // PDOStatement $sth->execute([1]); // boolean $input = $sth->fetch(PDO::FETCH_COLUMN);
However, if you are using PDO::ERRMODE_EXCEPTION error handling strategy, the output of execute
is redundant.
Doll forces PDO::ERRMODE_EXCEPTION
error handling strategy, while execute
method returns an instance of \Gajus\Doll\PDOStatement
. This allows further method chaining, e.g.
$input = $db ->prepare("SELECT ?") // Gajus\Doll\PDOStatement ->execute([1]) // Gajus\Doll\PDOStatement ->fetch(PDO::FETCH_COLUMN);
Extended Type Hinting
Inline Type Hinting
PDOStatement::bindValue() method allows to set the parameter type. However, the syntax is verbose:
$sth = $db->prepare("SELECT :foo, :bar, :baz"); $sth->bindValue('foo', 'foo', PDO::PARAM_STR); $sth->bindValue('bar', 1, PDO::PARAM_INT); $sth->bindValue('baz', $fp, PDO::PARAM_LOB); $sth->execute();
Doll allows inline type hinting:
$sth = $db->prepare("SELECT s:foo, i:bar, l:baz"); $sth->execute(['foo' => 'foo', 'bar' => 1, 'baz' => $fp]);
Doll implementation supports all of the parameter types:
Inferred Type Hinting
When parameter name is "id" or ends with "_id", unless an explicit parameter type is set, Doll will use PDO::PARAM_INT
, e.g.
$db->prepare("SELECT :id, :foo_id");
Is equivalent to:
$db->prepare("SELECT i:id, i:foo_id");
You can explicitly set the parameter type:
$db->prepare("SELECT s:id, s:foo_id");
You can disable the inferred type hinting:
$db->setAttribute(\Gajus\Doll\PDO::ATTR_INFERRED_TYPE_HINTING, false);
Parameter Marker Reuse
Using Doll, you can reuse the named parameter markers in your prepared statements, e.g.
$db->prepare("SELECT :foo, :foo");
The native PDO implementation does not support it. It will raise the following error:
PDOException: SQLSTATE[HY093]: Invalid parameter number
Logging and Benchmarking
Doll supports query and statement execution logging. To enable logging, you need to set \Gajus\Doll\PDO::ATTR_LOGGING
attribute to true
.
$db->setAttribute(\Gajus\Doll\PDO::ATTR_LOGGING, true); $db ->prepare("SELECT :foo, SLEEP(.2)") ->execute(['foo' => 'a']); $log = $db->getLog(); var_dump($log);
The log output contains the following information about each query:
array(1) { [0]=> array(7) { ["statement"]=> string(22) "SELECT :foo, SLEEP(.2)" ["parameters"]=> array(1) { ["foo"]=> string(1) "a" } ["execution_wall_time"]=> float(0.20117211341858) ["backtrace"]=> array(5) { ["file"]=> string(85) "/../doll/tests/LogTest.php" ["line"]=> int(28) ["function"]=> string(7) "execute" ["class"]=> string(23) "Gajus\Doll\PDOStatement" ["type"]=> string(2) "->" } ["execution_duration"]=> float(0.200723) ["execution_overhead"]=> float(0.00044911341857909) ["query"]=> string(19) "SELECT ?, SLEEP(.2)" } }
"execution_duration" and "query" are retrieved from SHOW PROFILES. Doll will automatically run diagnostics every 100 executions to overcome the limit of 100 queries.