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:

Default Attributes

Attribute	PDO	Doll
`PDO::ATTR_ERRMODE`	`PDO::ERRMODE_SILENT`	`PDO::ERRMODE_EXCEPTION`
`PDO::ATTR_EMULATE_PREPARES`	`false`	`true`
`PDO::ATTR_DEFAULT_FETCH_MODE`	`PDO::FETCH_BOTH`	`PDO::FETCH_ASSOC`
`PDO::ATTR_STATEMENT_CLASS`	`PDOStatement`	`Gajus\Doll\PDOStatement`

Attribute	Reason
`PDO::ATTR_ERRMODE`	Enables method chaining.
`PDO::ATTR_EMULATE_PREPARES`	`PDO_MYSQL` will take advantage of native prepared statement support present in MySQL 4.1 and higher. It will always fall back to emulating the prepared statement if the driver cannot successfully prepare the current query.
`PDO::ATTR_DEFAULT_FETCH_MODE`	More convenient.
`PDO::ATTR_STATEMENT_CLASS`	Required for the extended type hinting implementation.

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:

Name	Parameter Type
`b`	`PDO::PARAM_BOOL`
`n`	`PDO::PARAM_NULL`
`i`	`PDO::PARAM_INT`
`s`	`PDO::PARAM_STR`
`l`	`PDO::PARAM_LOB`

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.

gajus / doll

Maintainers

Details