Inspecting Bindings

Whenever you bind a value to a parameter in one of your queries, Wye will store that binding information along with the PDOStatement object so that you can inspect the bindings, either for debugging or for writing tests for your assumptions about the flow of data through your application.

BindingCollection Object

A BindingCollection object extends the Collection class and operates as an array with additional helper methods. The BindingCollection stores Binding objects in the order that the values were bound on the statement.

You can retrieve a BindingCollection object from a statement by calling PDOStatement::getBindings().

Array Behavior

As a Collection, all BindingCollection objects can be handled as arrays, allowing for interation and key-based value setting.

use Stratedge\Wye\Wye;

$bindings = Wye::makeBindingCollection();

count($bindings); //0

//Array-like assignment
$bindings[] = Wye::makeBinding('apparatus', 'Engine 8');
$bindings[] = Wye::makeBinding('type', 'Pumper');

count($bindings); //2

//Array-like iteration
foreach ($bindings as $binding) {
    $binding instanceof \Stratedge\Wye\Binding; //true
}

//Array-like referencing
$bindings[1]->getValue(); //'Pumper'

Has-Parameter

BindingCollection::hasParameter() will determine if any of the Binding objects in the collection bind a value to the given property.

$statement->bindValue('apparatus', 'Engine 2');

$bindings = $statement->getBindings();

$bindings->hasParameter('apparatus'); //true

Has-Value

BindingCollection::hasValue() will determine if any of the Binding objects in the collection bind the given value to any property.

$statement->bindValue('apparatus', 'Engine 2');

$bindings = $statement->getBindings();

$bindings->hasValue('Engine 2'); //true

Has-Value-Like

BindingCollection::hasValue() will determine if any of the Binding objects in the collection bind a value that contains the given value to any property.

$statement->bindValue('apparatus', 'Engine 2');

$bindings = $statement->getBindings();

$bindings->hasValueLike('ine'); //true

Has-Data-Type

BindingCollection::hasDataType() will determine if any of the Binding objects in the collection bind a value to a property using the given PDO::PARAM_* data type.

use PDO;

$statement->bindValue('apparatus', 'Engine 2', PDO::PARAM_STR);

$bindings = $statement->getBindings();

$bindings->hasDataType(PDO::PARAM_STR); //true

Filter-By-Parameter

BindingCollection::filterByParameter() will return a new collection containing only the Binding objects from the original collection that bind a value to the given parameter.

$statement->bindValue('apparatus', 'Squad 3');
$statement->bindValue('type', 'Rescue');

$bindings = $statement->getBindings();

$only_type = $bindings->filterByParameter('type');

//$only_type is a new BindingCollection object containing just the Binding
//object for type

$this->assertCount(1, $only_type);

Filter-By-Value

BindingCollection::filterByValue() will return a new collection containing only the Binding objects from the original collection that bind a given value to any parameter.

$statement->bindValue('apparatus', 'Squad 3');
$statement->bindValue('type', 'Rescue');

$bindings = $statement->getBindings();

$only_rescue = $bindings->filterByValue('Rescue');

//$only_rescue is a new BindingCollection object containing just the Binding
//object with a value of 'Rescue'

$this->assertCount(1, $only_rescue);

Filter-By-Value-Like

BindingCollection::filterByValue() will return a new collection containing only the Binding objects from the original collection that bind a value that contains the given value to any parameter.

$statement->bindValue('apparatus', 'Engine 3');
$statement->bindValue('type', 'Pumper');

$bindings = $statement->getBindings();

$only_engine = $bindings->filterByValueLike('en');

//$only_engine is a new BindingCollection object containing just the Binding
//object with a value that contains 'en'

$this->assertCount(1, $only_engine);

Filter-By-Data-Type

BindingCollection::filterByDataType() will return a new collection containing only the Binding objects from the original collection that bind a value with a given PDO::PARAM_* data type.

use PDO;

$statement->bindValue('apparatus', 'Engine 3', PDO::PARAM_STR);
$statement->bindValue('type', 'Pumper', PDO::PARAM_STR);
$statement->bindValue('in_service', 1, PDO::PARAM_BOOL);

$bindings = $statement->getBindings();

$only_in_service = $bindings->filterByDataType(PDO::PARAM_BOOL);

//$only_in_service is a new BindingCollection object containing just the Binding
//object with a value is bound as a PDO::PARAM_BOOL

$this->assertCount(1, $only_in_service);

Binding Object

A Binding object represents a single value being bound to a single parameter with a specific data type. A new object is created with each individual binding.

You can retrieve a Binding object from a BindingCollection.

Get-Parameter

To retrieve the parameter that is bound in a binding, call Binding::getParameter().

use Stratedge\Wye\Wye;

$binding = Wye::makeBinding('apparatus', 'Engine 2');

$binding->getParameter(); //'apparatus'

Get-Value

To retrieve the value that is bound in a binding, call Binding::getValue().

use Stratedge\Wye\Wye;

$binding = Wye::makeBinding('apparatus', 'Engine 2');

$binding->getValue(); //'Engine 2'

Get-Data-Type

To retrieve the integer value that represents the date type of the value that is bound in a binding, call Binding::getDataType().

use PDO;
use Stratedge\Wye\Wye;

$binding = Wye::makeBinding('apparatus', 'Engine 2', PDO::PARAM_STR);

$binding->getDataType(); //PDO::PARAM_STR integer value

Is-Data-Type

While you can retrieve the data type of a binding with Binding::getDataType(), having the integer value may not always be entirely useful, and with the possibility that the value could also include the bit for PDO::PARAM_INPUT_OUTPUT set, it could get unwieldly.

Recognizing this, there are several methods to help test the data type set for a binding: isBoolean() or isBool(), isNull(), isInteger() or isInt(), isString() or isStr(), isLargeObject() or isLOB(), isStatement() or isStmt(), and isInputOutput().

Each of of the listed methods accounts for the PDO::PARAM_INPUT_OUTPUT flag, except for isNull().

use Stratedge\Wye\Wye;

$binding = Wye::makeBinding('apparatus', 'Engine 2', PDO::PARAM_STR);

$binding->isString(); //true
$binding->isInputOutput(); //false

$binding2 = Wye::makeBinding('type', 'Pumper', PDO::PARAM_STR | PDO::PARAM_INPUT_OUTPUT);

$binding->isString(); //true
$binding->isInputOutput(); //true