PHP Database library

English version

Biblioteca para la administración de bases de datos SQL para ser utilizada por varios proveedores al mismo tiempo.

• Requisitos
• Instalación
• Cómo empezar y ejemplos
• Cómo empezar
• Get connection
• CREATE TABLE
• SELECT
• INSERT INTO
• UPDATE
• REPLACE
• DELETE
• TRUNCATE TABLE
• DROP TABLE
• Tests
• Tareas pendientes
• Manejador de excepciones
• Contribuir
• Repositorio
• Licencia
• Copyright

Requisitos

Esta clase es soportada por versiones de PHP 5.6 o superiores y es compatible con versiones de HHVM 3.0 o superiores.

Instalación

La mejor forma de instalar esta extensión es a través de Composer.

Para instalar PHP Database library, simplemente escribe:

$ composer require Josantonius/Database

El comando anterior sólo instalará los archivos necesarios, si prefieres descargar todo el código fuente puedes utilizar:

$ composer require Josantonius/Database --prefer-source

También puedes clonar el repositorio completo con Git:

$ git clone https://github.com/Josantonius/PHP-Database.git

O instalarlo manualmente:

Descargar Database.php, Provider.php, PDOprovider.php, MSSQLprovider.php and DBException.php:

$ wget https://raw.githubusercontent.com/Josantonius/PHP-Database/master/src/Database.php
$ wget https://raw.githubusercontent.com/Josantonius/PHP-Database/master/src/Provider/Provider.php
$ wget https://raw.githubusercontent.com/Josantonius/PHP-Database/master/src/Provider/PDOprovider.php
$ wget https://raw.githubusercontent.com/Josantonius/PHP-Database/master/src/Provider/MSSQLprovider.php
$ wget https://raw.githubusercontent.com/Josantonius/PHP-Database/master/src/Exception/DBException.php

Get connection

- Get connection:

Database::getConnection($id, $provider, $host, $user, $name, $password, $settings);

| Atributo | Descripción | Tipo | Requerido | Predeterminado | --- | --- | --- | --- | --- | | $id | ID único. | string | Sí | | | $provider | Nombre de la clase del proveedor. | string | No | null | | $host | Host. | string | No | null | | $user | Usuario. | string | No | null | | $name | Nombre. | string | No | null | | $password | Password . | string | No | null |

| Attribute | Key | Description | Type | Required | Default | --- | --- | --- | --- | --- | --- | | $settings | | Opciones | array | No | null | | $settings | 'port' | Puerto. | string | No | | | $settings | 'charset' | Charset. | string | No | |

# Return (object) ? objeto con la conexión

$db = Database::getConnection(
    'identifier',  # Unique identifier
    'PDOprovider', # Database provider name
    'localhost',   # Database server
    'db-user',     # Database user
    'db-name',     # Database name
    'password',    # Database password
    array('charset' => 'utf8')
);

$externalDB = Database::getConnection(
    'external',          # Unique identifier
    'PDOprovider',       # Database provider name
    'http://site.com',   # Database server
    'db-user',           # Database user
    'db-name',           # Database name
    'password',          # Database password
    array('charset' => 'utf8')
);

// And once the connection is established:

$db = Database::getConnection('identifier');

$externalDB = Database::getConnection('external');

Query

- Procesar la consulta y prepararla para el proveedor:

$db->query($query, $statements, $result);

| Atributo | Descripción | Tipo | Requerido | Predeterminado | --- | --- | --- | --- | --- | | $query | Query. | string | Sí | | | $statements | Declaraciones preparadas. | array | No | null | | $result | Resultado de la consulta; 'obj', 'array_num', 'array_assoc', 'rows', 'id'. | string | No | 'obj' |

# Return (mixed) ? resultado como objeto, array, int...

# throws [DBException] ? tipo de consulta no válida

$db->query(
    'CREATE TABLE test (
        id    INT(6)      PRIMARY KEY,
        name  VARCHAR(30) NOT NULL,
        email VARCHAR(50)
    )'
);

$db->query(
    'SELECT id, name, email
     FROM test',
    false,
    'array_assoc' // array_assoc, obj, array_num
);

$statements[] = [1, "Many"];
$statements[] = [2, "many@email.com"];
        
$db->query(
    'INSERT INTO test (name, email)
     VALUES (?, ?)',
    $statements,
    'id' // id, rows
);

CREATE TABLE

- CREATE TABLE:

$db->create($data)
   ->table($table)
   ->foreing($id)
   ->reference($table)
   ->on($table)
   ->actions($action)
   ->engine($type)
   ->charset($type)
   ->execute();

| Método | Atributo | Descripción | Tipo | Requerido | Predeterminado | --- | --- | --- | --- | --- | --- | | | $data | Nombre de columna y configuración para tipos de datos. | array | Sí | | | table() | | Establecer nombre de tabla. | method | Sí | | | | $table | Nombre de tabla. | string | Sí | | | foreing() | | Establecer clave foránea. | method | No | | | | $id | ID de la columna. | string | Sí | | | reference() | | Referencia para clave foránea. | method | No | | | | $table | Nombre de tabla. | array | Sí | | | on() | | Establecer nombre de tabla. | method | No | | | | $table | Nombre de tabla. | array | Sí | | | actions() | | Establecer las acciones cuando se borre o actualice algún campo relacionado con clave foránea. | method | No | | | | $action | Acción para cuando se borre o actualice algún campo. | array | Sí | | | engine() | | Establecer tipo de motor para la tabla. | method | No | | | | $type | Tipo de motor. | string | Sí | | | charset() | | Establecer charset. | method | No | | | | $type | Tipo de charset. | string | Sí | | | execute() | | Ejecutar consulta. | method | Sí | |

# Return (boolean)

$params = [
    'id'    => 'INT(6) PRIMARY KEY',
    'name'  => 'VARCHAR(30) NOT NULL',
    'email' => 'VARCHAR(50)'
];

$query = $db->create($params)
            ->table('test')
            ->execute();

$db->create($params)
   ->table('test_two')
   ->foreing('id')
   ->reference('id')
   ->on('test')
   ->actions('ON DELETE CASCADE ON UPDATE CASCADE')
   ->engine('innodb')
   ->charset('utf8')
   ->execute();

SELECT

- Declaración SELECT:

$db->select($columns)
   ->from($table)
   ->where($clauses, $statements)
   ->order($type)
   ->limit($number)
   ->execute($result);

| Método | Atributo | Descripción | Tipo | Requerido | Predeterminado | --- | --- | --- | --- | --- | --- | | | $columns | Nombre/s de columna/s. | mixed | No | '*' | | from() | | Establecer nombre de tabla. | method | Sí | | | | $table | Nombre de tabla. | string | Sí | | | where() | | Cláusulas WHERE. | method | No | | | | $clauses | Nombre de la columna y valor. | mixed | Sí | | | | $statements | Declaraciones preparadas. | array | No | null | | order() | | Órden. | method | No | | | | $type | Tipo de ordenamiento. | string | Sí | | | limit() | | Límite. | method | No | | | | $number | Número. | int | Sí | | | execute() | | Ejecutar consulta. | method | Sí | | | | $result | Resultado de la consulta; 'obj', 'array_num', 'array_assoc', 'rows'. | string | No | 'obj' |

# Return (mixed) ? resultado de la consulta (object, array, int...) o número de filas afectadas

#SELECT all
$db->select()
    ->from('test')
    ->execute('array_num');

#SELECT con todos los parámetros
$db->select(['id', 'name'])
   ->from('test')
   ->where(['id = 4885', 'name = "Joe"'])
   ->order(['id DESC', 'name ASC'])
   ->limit(1)
   ->execute('obj');

#SELECT con declaraciones preparadas
$statements[] = [1, 3008];
$statements[] = [2, 'Manny'];
        
$db->select('name')
   ->from('test')
   ->where('id = ? OR name = ?', $statements)
   ->execute('rows');

#Otra versión de SELECT con declaraciones preparadas
$statements[] = [':id', 8, 'int'];
$statements[] = [':email', null, 'null'];

$clauses = [
    'id    = :id',
    'email = :email'
];

$db->select('name')
   ->from('test')
   ->where($clauses, $statements)
   ->execute('rows');

INSERT INTO

- Declaración INSERT INTO:

$db->insert($data, $statements)
   ->in($table)
   ->execute($result);

| Método | Atributo | Descripción | Tipo | Requerido | Predeterminado | --- | --- | --- | --- | --- | --- | | | $data | Nombre de la columna y valor. | array | Sí | | | | $statements | Declaraciones preparadas. | array | No | null | | in() | | Establecer nombre de tabla. | method | Sí | | | | $table | Nombre de tabla. | string | Sí | | | execute() | | Ejecutar consulta. | method | Sí | | | | $result | Resultado de la consulta; 'rows', 'id'. | string | No | 'rows' |

# Return (int) ? número de filas afectadas o ID de la última fila afectada

#INSERT INTO ejemplo básico
$data = [
    "name"  => "Isis",
    "email" => "isis@email.com",
];
        
$db->insert($data)
   ->in('test')
   ->execute();

#INSERT INTO con declaraciones preparadas
$data = [
    "name"  => "?",
    "email" => "?",
];

$statements[] = [1, "Isis"];
$statements[] = [2, "isis@email.com"];

$db->insert($data, $statements)
   ->in('test')
   ->execute('rows');

#Otra versión de INSERT INTO con declaraciones preparadas
$data = [
    "name"  => ":name",
    "email" => ":email",
];

$statements[] = [":name", "Isis", "str"];
$statements[] = [":email", "isis@email.com", "str"];

$db->insert($data, $statements)
   ->in('test')
   ->execute('id');

UPDATE

- Declaración UPDATE:

$db->update($data, $statements)
   ->in($table)
   ->where($clauses, $statements)
   ->execute();

| Método | Atributo | Descripción | Tipo | Requerido | Predeterminado | --- | --- | --- | --- | --- | --- | | | $data | Nombre de la columna y valor. | array | Sí | | | | $statements | Declaraciones preparadas. | array | No | null | | in() | | Establecer nombre de tabla. | method | Sí | | | | $table | Nombre de tabla. | string | Sí | | | where() | | Cláusulas WHERE. | method | No | | | | $clauses | Nombre de la columna y valor. | mixed | Sí | | | | $statements | Declaraciones preparadas. | array | No | null | | execute() | | Ejecutar consulta. | method | Sí | |

# Return (int) ? número de filas afectadas

#UPDATE ejemplo básico
$data = [
    'name'  => 'Isis',
    'email' => 'isis@email.com',
];

$db->update($data)
   ->in('test')
   ->execute();

#UPDATE with WHERE
$data = [
    'name'  => 'Manny',
    'email' => 'manny@email.com',
];

$clauses = [
    'name  = "isis"',
    'email = "isis@email.com"'
];

$db->update($data)
   ->in('test')
   ->where($clauses)
   ->execute();

#UPDATE con declaraciones preparadas
$data = [
    'name'  => '?',
    'email' => '?',
];

$statements['data'][] = [1, 'Isis'];
$statements['data'][] = [2, 'isis@email.com'];

$clauses = 'id = ? AND name = ? OR name = ?';

$statements['clauses'][] = [3, 4883];
$statements['clauses'][] = [4, 'Isis'];
$statements['clauses'][] = [5, 'Manny'];

$db->update($data, $statements['data'])
   ->in('test')
   ->where($clauses, $statements['clauses'])
   ->execute();

#Otra versión de UPDATE con declaraciones preparadas
$data = [
    'name'  => ':new_name',
    'email' => ':new_email',
];

$statements['data'][] = [':new_name', 'Manny', 'str'];
$statements['data'][] = [':new_email', 'manny@email.com', 'str'];

$clauses = 'name = :name1 OR name = :name2';

$statements['clauses'][] = [':name1', 'Isis', 'str'];
$statements['clauses'][] = [':name2', 'Manny', 'str'];

$db->update($data, $statements['data'])
   ->in('test')
   ->where($clauses, $statements['clauses'])
   ->execute();

REPLACE

- Reemplazar una línea en una tabla si existe o insertar una nueva línea si no existe:

$db->replace($data, $statements)
   ->from($table)
   ->execute($result);

| Método | Atributo | Descripción | Tipo | Requerido | Predeterminado | --- | --- | --- | --- | --- | --- | | | $data | Nombre de la columna y valor. | array | Sí | | | | $statements | Declaraciones preparadas. | array | No | null | | from() | | Establecer nombre de tabla. | method | Sí | | | | $table | Nombre de tabla. | string | Sí | | | execute() | | Ejecutar consulta. | method | Sí | | | | $result | Resultado de la consulta; 'rows', 'id'. | string | No | 'rows' |

# Return (int) ? número de filas afectadas o ID de la última fila afectada

#REPLACE ejemplo básico
$data = [
    'id'    => 3008,
    'name'  => 'Manny',
    'email' => 'manny@email.com',
];

$db->replace($data)
   ->from('test')
   ->execute();

#UPDATE con declaraciones preparadas
$data = [
    'id'    => 4889,
    'name'  => ':name',
    'email' => ':email',
];

$statements[] = [':name', 'Manny'];
$statements[] = [':email', 'manny@email.com'];

$db->replace($data, $statements)
   ->from('test')
   ->execute('rows');

#Otra versión de UPDATE con declaraciones preparadas
$data = [
    'id'    => 2,
    'name'  => '?',
    'email' => '?',
];

$statements[] = [1, 'Manny'];
$statements[] = [2, 'manny@email.com'];

$db->replace($data, $statements)
   ->from('test')
   ->execute('id');

DELETE

- Declaración DELETE:

$db->replace($data, $statements)
   ->from($table)
   ->where($clauses, $statements)
   ->execute();

| Método | Atributo | Descripción | Tipo | Requerido | Predeterminado | --- | --- | --- | --- | --- | --- | | | $data | Nombre de la columna y valor. | array | Sí | | | | $statements | Declaraciones preparadas. | array | No | null | | from() | | Establecer nombre de tabla. | method | Sí | | | | $table | Nombre de tabla. | string | Sí | | | where() | | Cláusulas WHERE. | method | No | | | | $clauses | Nombre de la columna y valor. | mixed | Sí | | | | $statements | Declaraciones preparadas. | array | No | null | | execute() | | Ejecutar consulta. | method | Sí | |

# Return (int) ? número de filas afectadas

#DELETE all
$db->delete()
   ->from('test')
   ->execute();

#DELETE with WHERE
$clauses = [
    'id = 4884',
    'name  = "isis"',
    'email = "isis@email.com"',
];

$db->delete()
   ->from('test')
   ->where($clauses)
   ->execute();

#DELETE con declaraciones preparadas
$clauses = 'id = :id AND name = :name1 OR name = :name2';

$statements[] = [':id', 4885];
$statements[] = [':name1', 'Isis'];
$statements[] = [':name2', 'Manny'];

$db->delete()
   ->from('test')
   ->where($clauses, $statements)
   ->execute();

#Otra versión de DELETE con declaraciones preparadas
$clauses = 'id = :id AND name = :name1 OR name = :name2';

$statements[] = [':id', 4886, 'int'];
$statements[] = [':name1', 'Isis', 'src'];
$statements[] = [':name2', 'Manny', 'src'];

$db->delete()
   ->from('test_table')
   ->where($clauses, $statements)
   ->execute();

TRUNCATE TABLE

- Declaración TRUNCATE TABLE:

$db->truncate()
   ->table($table)
   ->execute();

| Método | Atributo | Descripción | Tipo | Requerido | Predeterminado | --- | --- | --- | --- | --- | --- | | table() | | Establecer nombre de tabla. | method | Sí | | | | $table | Nombre de tabla. | string | Sí | | | execute() | | Ejecutar consulta. | method | Sí | |

# Return (boolean)

$db->truncate()
   ->table('test')
   ->execute();

DROP TABLE

- Declaración DROP TABLE:

$db->drop()
   ->table($table)
   ->execute();

| Método | Atributo | Descripción | Tipo | Requerido | Predeterminado | --- | --- | --- | --- | --- | --- | | table() | | Establecer nombre de tabla. | method | Sí | | | | $table | Nombre de tabla. | string | Sí | | | execute() | | Ejecutar consulta. | method | Sí | |

# Return (boolean)

$db->drop()
   ->table('test')
   ->execute();

Tests

Para ejecutar las pruebas necesitarás Composer y seguir los siguientes pasos:

$ git clone https://github.com/Josantonius/PHP-Database.git

$ cd PHP-Database

$ composer install

Ejecutar pruebas unitarias con PHPUnit:

$ composer phpunit

Ejecutar pruebas de estándares de código PSR2 con PHPCS:

$ composer phpcs

Ejecutar pruebas con PHP Mess Detector para detectar inconsistencias en el estilo de codificación:

$ composer phpmd

Ejecutar todas las pruebas anteriores:

$ composer tests

? Tareas pendientes

• [ ] Añadir nueva funcionalidad
• [ ] Mejorar pruebas
• [ ] Mejorar documentación
• [ ] Refactorizar código

Manejador de excepciones

Esta biblioteca utiliza control de excepciones que puedes personalizar a tu gusto.

Contribuir

Si deseas colaborar, puedes echar un vistazo a la lista de issues o tareas pendientes.

Pull requests

• Fork and clone.
• Ejecuta el comando `composer install` para instalar dependencias. Esto también instalará las dependencias de desarrollo.
• Ejecuta el comando `composer fix` para estandarizar el código.
• Ejecuta las pruebas.
• Crea una nueva rama (branch), commit, push y envíame un pull request.

Repositorio

La estructura de archivos de este repositorio se creó con PHP-Skeleton.

Licencia

Este proyecto está licenciado bajo licencia MIT. Consulta el archivo LICENSE para más información.

Copyright

2017 Josantonius, josantonius.com

Si te ha resultado útil, házmelo saber :wink:

Puedes contactarme en Twitter o a través de mi correo electrónico.