README.md

Introduction

This directory contains the implementation on the "database interface".

The "database interface" provides:

• Access to the database (through the procedures and the SQL requests).
• Information about the database. For example, you may request the list of fields that compose a given table.

The application should access the database through the procedures. However, it is possible to call SQL requests directly.

Synopsis

Since all the PHP code is documented using PhpDoc annotations, you should be able to exploit the auto completion feature from your favourite IDE. If you are using Eclipse, NetBeans or PhPStorm, using this API should be pretty intuitive.

Initialize a database interface:

    $di = \dbeurive\Backend\Database\DatabaseInterface::getInstance('default', $configuration);

Get an entry point (SQL request to a procedure):

    $request   = $di->getSql('User/Authenticate');
    $procedure = $di->getProcedure('User/Authenticate'); 

Configure and execute the entry point:

    $resultSql       = $request->execute(['user.login' => 'foo', 'user.password' => 'bar']);           
    $resultProcedure = $procedure->execute(['user.login' => 'foo', 'user.password' => 'bar']);

See how to write the use SQL requests and procedures.

Initialization in details

First you create a database handler that you will use within your SQL requests. In this example, we use an instance of PDO. But you can use any type of database handler. The choice is up to you.

$dbh = new PDO('mysql:dbname=testdb;host=127.0.0.1', 'dbuser', 'dbpass');

Then you get an instance of the database interface:

Example 1:

$diConfiguration = [
            'sql-repository-path'          => '/Users/denisbeurive/php-public/backend/tests/EntryPoints/Brands/MySql/Sqls',
            'procedure-repository-path'    => '/Users/denisbeurive/php-public/backend/tests/EntryPoints/Brands/MySql/Procedures',
            'sql-base-namespace'           => '\\dbeurive\\BackendTest\\EntryPoints\\Brands\\MySql\\Sqls',
            'procedure-base-namespace'     => '\\dbeurive\\BackendTest\\EntryPoints\\Brands\\MySql\\Procedures',
            'schema-path'                  => '/Users/denisbeurive/php-public/backend/tests/cache/mysql_db_schema.php',
            'db-handler'                   => $dbh
];

$databaseInterface = \dbeurive\Backend\Database\DatabaseInterface::getInstance('default', $diConfiguration);

Parameter	Description
sql-repository-path	Absolute path to the base directory use to store all SQL requests (PHP) classes.
procedure-repository-path	Absolute path to the base directory use to store all procedures (PHP) classes.
sql-base-namespace	Base namespace for all SQL requests.
procedure-base-namespace	Base namespace for all procedures.
schema-path	Path to the PHP file that contains the schema of the database (the list of fields). Ses note.
db-handler	Handler to the data (example: an instance of PDO)

Note:

The PHP file that contains the schema of the database has been previously generated by the script backend. See this documentation.

Or, example 2:

$diConfiguration = [
            'sql-repository-path'          => '/Users/denisbeurive/php-public/backend/tests/EntryPoints/Brands/MySql/Sqls',
            'procedure-repository-path'    => '/Users/denisbeurive/php-public/backend/tests/EntryPoints/Brands/MySql/Procedures',
            'sql-base-namespace'           => '\\dbeurive\\BackendTest\\EntryPoints\\Brands\\MySql\\Sqls',
            'procedure-base-namespace'     => '\\dbeurive\\BackendTest\\EntryPoints\\Brands\\MySql\\Procedures',
            'schema-path'                  => '/Users/denisbeurive/php-public/backend/tests/cache/mysql_db_schema.php'
];

$databaseInterface = \dbeurive\Backend\Database\DatabaseInterface::getInstance('default', $diConfiguration);
$databaseInterface->setDbHandler($dbh);

Or, example 3:

$databaseInterface = \dbeurive\Backend\Database\DatabaseInterface::getInstance();
$databaseInterface->setSqlRepositoryBasePath($inOptConfig['/Users/denisbeurive/php-public/backend/tests/EntryPoints/Brands/MySql/Sqls');
$databaseInterface->setSqlBaseNameSpace($inOptConfig['/Users/denisbeurive/php-public/backend/tests/EntryPoints/Brands/MySql/Procedures');
$databaseInterface->setProcedureRepositoryBasePath('\\dbeurive\\BackendTest\\EntryPoints\\Brands\\MySql\\Sqls');
$databaseInterface->setProcedureBaseNameSpace($inOptConfig['\\dbeurive\\BackendTest\\EntryPoints\\Brands\\MySql\\Procedures');
$databaseInterface->setPhpDatabaseRepresentationPath($inOptConfig['/Users/denisbeurive/php-public/backend/tests/cache/mysql_db_schema.php');
$databaseInterface->setDbHandler($dbh);

NOTE: The three examples above are strictly equivalent.

Then, from anywhere in your code, you can retrieve the previously instantiated database interface by its name:

$databaseInterface =  \dbeurive\Backend\Database\DatabaseInterface::getInstance('default');

Please note than you can create as many instances of the database interface. Each instance has a name. If you don't give a name to a new instance (see example 3), then the name of the instance is "default". Creating many database interfaces may be interesting if you use more than one database. Or you may want to define specific entry points to enforce security.