Bases de Datos

El manejo de bases de datos es realmente sencillo en RSPhp. Lo primero que debes saber es como formar una conexión. Una conexión es configurable dentro de "config/app.json", como lo vimos aqui.

Consultas Parametrizadas

Query

Ahora, vamos a utilizar esas conexiónes, primero con una consulta simple:

    
      //  Instanciamos un asistente
      //  Si no pasamos parámetro, toma la conexión "default"
      $db = new Db();

      //  Establecemos una consulta parametrizada
      $sql = "SELECT * FROM orders WHERE id = :id;"

      //  Establecemos los parámetros de la consulta
      $params['id'] = 12369;

      //  Ejecutamos la consulta y obtenemos el resultado
      $resultSet = $db->query($sql, $params);

El método es "query", que acepta como parámetros:

$sql.- La consulta SQL. Los parámetros los establecemos con dos puntos (:) adelante.
$params.- Un arreglo asociativo que contiene los parámetros, siendo la llave el nombre del parámetro, y el valor el valor del parámetro.

El resultado es un arreglo de arreglos asociativos, en donde cada arreglo asociativo es un renglón, y cada renglón es una arreglo de llave-valor, donde la llave es el nombre de la columna.

    
      Array(
        [0] => Array (
          [id] => 1
          [customer] => 999
          [date] => 20160101
        )
        [1] => Array (
          [id] => 2
          [customer] => 889
          [date] => 20160102
        )
      )

NonQuery

NonQuery son las consultas que no devuelven datos, como INSERT, UPDATE y DELETE

Tiene exactamente el mismo formato que "query", pero no devuleve un resultset, devuelve el número de registros afectados.

    
      //  Instanciamos un asistente
      //  Si no pasamos parámetro, toma la conexión "default"
      $db = new Db();

      //  Establecemos una consulta parametrizada
      $sql = "INSERT INTO phonebook ( name, phone_number ) VALUES ( :name, :phoneNumber );";

      //  Establecemos los parámetros de la consulta
      $params['name'] = 'Luis Espino';
      $params['phoneNumber'] = '555-7890';

      //  Ejecutamos la consulta y obtenemos el resultado
      $rows = $db->nonquery($sql, $params);

      //  Imprime 1
      echo $rows;

Scalar

Scalar son las consultas que devuelven un solo dato, un campo de un registro, no un conjunto de registros.

Tiene exactamente el mismo formato que "query", pero no devuleve un resultset, devuelve un dato escalar.

    
      //  Instanciamos un asistente
      //  Si no pasamos parámetro, toma la conexión "default"
      $db = new Db();

      //  Establecemos una consulta parametrizada
      $sql = "SELECT MAX(order_id) as last_order FROM orders WHERE customer_id = :customerId;";

      //  Establecemos los parámetros de la consulta
      $params['customerId'] = 999;

      //  Ejecutamos la consulta y obtenemos el resultado
      $last_order_id = $db->scalar($sql, $params);

      //  Imprime 1001
      echo $last_order_id;

Constructor de Consultas

RSPhp cuenta con un constructor de consultas que utiliza una sintáxis muy parecida a SQL. Comenzamos desde la instancia de la base de datos para acceder a todos los métodos, que son un espejo de los claúsulas de SQL:

Select
From
Where
Order By
Top
Join

Consultas de Selección

El ejemplo más sencillo es el de seleccionar todos los datos de una tabla (solo recomendable para tablas pequeñas de catálogo)

get( $tableName = null, $className = null ).

Parámetros:

$tableName El nombre de la tabla. Opcional, ya que podemos establecerlo también con "from".
$className El nombre de la clase a la que queramos convertir cada registro en el arreglo. Silo especificamos, nos devolverá un arreglo de instances de esta clase. Por supuesto, la clase debe ser un modelo de la tabla, para poder realizar correctamente la conversión.

    
      //  Instanciamos un asistente
      //  Si no pasamos parámetro, toma la conexión "default"
      $db = new Db();

      //  Realiza un SELECT * FROM orders;
      $resultSet = $db->get('orders');

"get" es el método para mandar obtener los datos. Por ejemplo, si creamos un consulta simple "SELECT ... FROM ...", tenemos que mandar llamar "get" para traer los datos:

select( $columns )

Parámetros:

$columns Lista de columnas separadas por comas. Acepta nomenclatura "colName AS MyColumn"

from( $tableName )

Parámetros:

$tableName El nombre de la tabla a seleccionar

    
      //  Instanciamos un asistente
      //  Si no pasamos parámetro, toma la conexión "default"
      $db = new Db();

      //  Realiza un SELECT * FROM orders;
      $resultSet =
        $db->
          select('id, customer, date')->
          from('orders')->
          get();

Claúsula Where

El método "where" acepta dos tipos de argumentos:

Nombre de columna y valor

where( $columnName, $value ).

Parámetros:

$columnName El nombre de la columna
$value El valor a comparar (usando operador "==")

          
            //  Instanciamos un asistente
            //  Si no pasamos parámetro, toma la conexión "default"
            $db = new Db();

            //  Realiza un SELECT * FROM orders WHERE id = 1001;
            $resultSet =
              $db->
                select('id, customer, date')->
                from('orders')->
                where('id', 1001)->
                get();

Arreglo asociativo

where( $array ).

Parámetros:

$array El arreglo asociativo, colección par clave-valor, donde clave es el nombre de la columna.

          
            //  Instanciamos un asistente
            //  Si no pasamos parámetro, toma la conexión "default"
            $db = new Db();

            //  Realiza un SELECT * FROM orders WHERE customer = 999 AND date = '20160101';
            $params['customer'] = 999;
            $params['date'] = '20160101';

            $resultSet =
              $db->
                select('id, customer, date')->
                from('orders')->
                where($params)->
                get();

And's & Or's

Utilizamos "andWhere" para incluir claúsulas "AND WHERE ...", y "orWhere" para incluir cláusilas del tipo " OR WHERE ...".

andWhere( $columnName, $value ).
orWhere( $columnName, $value ).

Parámetros:

$columnName El nombre de la columna
$value El valor a comparar (usando operador "==")

    
      //  Instanciamos un asistente
      //  Si no pasamos parámetro, toma la conexión "default"
      $db = new Db();

      //  Realiza un SELECT * FROM orders WHERE customer = 999 AND date = '20160101';
      $resultSet =
        $db->
          select('id, customer, date')->
          from('orders')->
          where('customer', 999)->
          andWhere('date', '20160101')->
          get();

      //  Realiza un SELECT * FROM orders WHERE customer = 999 OR date = '20160101';
      $resultSet =
        $db->
          select('id, customer, date')->
          from('orders')->
          where('customer', 999)->
          orWhere('date', '20160101')->
          get();

Claúsula Like

El método "like" genera una claúsula "WHERE LIKE '%value%'". Tambien existe el método "orLike", que genera una cláusula "OR LIKE '%value%'" y "andLike" que genera una cláusula "AND LIKE '%value%'"

like( $columnName, $value ).
andLike( $columnName, $value ).
orLike( $columnName, $value ).

Parámetros:

$columnName El nombre de la columna
$value El valor a comparar usando wilcards ('%$value%')

    
      //  Instanciamos un asistente
      //  Si no pasamos parámetro, toma la conexión "default"
      $db = new Db();

      //  Realiza un SELECT id, name, email FROM customers WHERE name LIKE '%Luis%' AND email LIKE '%espino%';
      $resultSet =
        $db->
          select('id, name, email')->
          from('customers')->
          like('name', 'Luis')->
          andLike('email', 'espino')->
          get();

      //  Realiza un SELECT id, name, email FROM customers WHERE name LIKE '%Luis%' OR email LIKE '%espino%';
      $resultSet =
      $db->
        select('id, name, email')->
        from('customers')->
        like('name', 'Luis')->
        orLike('email', 'espino')->
        get();

Claúsula Order By

El método "orderBy" nos permite establecer ordenamientos. Sus argumentos son el nombre de la columna y, opcionalmente, "asc" o "desc".

orderBy( $columnName, $ascDesc = null ).

Parámetros:

$columnName El nombre de la columna
$ascDesc El texto "asc" o "desc". Opcional

    
      //  Instanciamos un asistente
      //  Si no pasamos parámetro, toma la conexión "default"
      $db = new Db();

      //  Realiza un SELECT id, name, email FROM customers ORDER BY name ASC;
      $resultSet =
        $db->
          select('id, name, email')->
          from('customers')->
          orderBy('name', 'asc')->
          get();

      //  Realiza un SELECT id, name, email FROM customers ORDER BY name DESC;
      $resultSet =
        $db->
          select('id, name, email')->
          from('customers')->
          orderBy('name', 'desc')->
          get();

Claúsula Top

El método "top" nos permite limitar el número de registros que devolverá la consulta. En caso de utilizar la base de datos MySql o PostgreSql, generará consultas con "LIMIT", para Sql Server utilizará "TOP".

top( $limit, $startAt = null ).

Parámetros:

$limit El número de registros a devolver
$startAt El número de registro inicial, donde comienza a contar para el límite. Opcional

    
      //  Instanciamos un asistente
      //  Si no pasamos parámetro, toma la conexión "default"
      $db = new Db();

      //  Realiza un SELECT id, name, email FROM customers LIMIT 10;
      $resultSet =
        $db->
          select('id, name, email')->
          top(10)->
          from('customers')->
          get();

      //  Realiza un SELECT id, name, email FROM customers WHERE LIMIT 10, 20;
      $resultSet =
        $db->
          select('id, name, email')->
          top(10, 20)->
          from('customers')->
          get();

Claúsula Join

El método "join" nos permite unir tablas. Utiliza opcionalmente el método "on" de forma consecutiva (con excepción de CROSS JOIN)

join( $tableName, $leftField, $operator, $rightField ).
leftJoin( $tableName, $leftField, $operator, $rightField ).
rightJoin( $tableName, $leftField, $operator, $rightField ).
crossJoin( $tableName ).

Parámetros:

$tableName El nombre de la tabla a unir
$leftField El nombre del campo de la tabla de la izquierda con el que se realizará la unión
$operator El operador con el que se realizará la comparación ( =, >=, <=, etc.)
$rightField El nombre del campo de la tabla de la derecha con el que se realizará la unión

    
      //  Instanciamos un asistente
      //  Si no pasamos parámetro, toma la conexión "default"
      $db = new Db();

      //  Realiza un 'O.id as order_id, c.name as customer_name FROM orders as O
      //  INNER JOIN customers as C ON C.id = O.custumer
      $resultSet =
        $db->
          select('O.id as order_id, c.name as customer_name')->
          from('orders as O')->
          join('customers as C', 'C.id', '=', 'O.custumer')->
          get();

      //  Realiza un 'O.id as order_id, c.name as customer_name FROM orders as O
      //  LEFT JOIN customers as C ON C.id = O.custumer
      $resultSet =
        $db->
          select('O.id as order_id, c.name as customer_name')->
          from('orders as O')->
          leftJoin('customers as C', 'C.id', '=', 'O.custumer')->
          get();

      //  Realiza un 'O.id as order_id, c.name as customer_name FROM orders as O
      //  RIGHT JOIN customers as C ON C.id = O.custumer
      $resultSet =
        $db->
          select('O.id as order_id, c.name as customer_name')->
          from('orders as O')->
          rightJoin('customers as C', 'C.id', '=', 'O.custumer')->
          get();

      //  Realiza un 'O.id as order_id, c.name as customer_name FROM orders as O
      //  CROSS JOIN customers
      $resultSet =
        $db->
          select('O.id as order_id, c.name as customer_name')->
          from('orders as O')->
          crossJoin('customers as C')->
          get();

Manipulación de Datos, Registro Activo

La manipulación de datos incluye funciones para crear, actualizar y eliminar registros.

Inserción de Datos

El método "insert" nos permite insertar un registro en una tabla específica.

insert( $tableName, $params ).

Parámetros:

$tableName El nombre de la tabla en la que se realizará la inserción
$params Arreglo asociativo, colección de pares clave-valor, donde la clave es el nombre de la columna, y el valor es el valor a insertar.

    
      //  Instanciamos un asistente
      //  Si no pasamos parámetro, toma la conexión "default"
      $db = new Db();

      //  Los parámetros, el arreglo columna - valor a insertar;
      $params['id'] = 1;
      $params['customer'] = 999;
      $params['date'] = 20160101;

      //  Realizamos la inserción
      $db->insert( 'orders', $params );

Actualización de Datos

El método "update" nos permite actualizar un registro en una tabla específica.

update( $tableName, $params, $whereParams ).

Parámetros:

$tableName El nombre de la tabla en la que se realizará la inserción
$params Arreglo asociativo, colección de pares clave-valor, donde la clave es el nombre de la columna, y el valor es el valor a actualizar.
$whereParams Arreglo asociativo de columnas llave de la tabla, colección de pares clave-valor, donde la clave es el nombre de la columna, y el valor es el valor a de la columna clave.

    
      //  Instanciamos un asistente
      //  Si no pasamos parámetro, toma la conexión "default"
      $db = new Db();

      //  Los parámetros de la clausula where, condiciones para buscar los registros
      //  es un arreglo columna - valor a actualizar;
      $whereParams['id'] = 1;
      //  Los parámetros, el arreglo columna - valor a actualizar;
      $params['customer'] = 999;
      $params['date'] = 20160101;

      //  Realizamos la actualización
      $db->update( 'orders', $params, $whereParams );

Actualización/Inserción de Datos

El método "upsert" nos permite actualizar o insertar un registro en una tabla específica, dependiendo si este ya existe o nó.

upsert( $tableName, $params, $whereParams = null ).

Parámetros:

$tableName El nombre de la tabla en la que se realizará la inserción
$params Arreglo asociativo, colección de pares clave-valor, donde la clave es el nombre de la columna, y el valor es el valor a actualizar.
$whereParams (Opciona) Arreglo asociativo de columnas llave de la tabla, colección de pares clave-valor, donde la clave es el nombre de la columna, y el valor es el valor a de la columna clave. Si se excluye, se realizará una inserción con $params

    
      //  Instanciamos un asistente
      //  Si no pasamos parámetro, toma la conexión "default"
      $db = new Db();

      //  Los parámetros de la clausula where, condiciones para buscar los registros
      //  es un arreglo columna - valor a actualizar;
      $whereParams['id'] = 1;
      //  Los parámetros, el arreglo columna - valor a actualizar;
      $params['customer'] = 999;
      $params['date'] = 20160101;

      //  Realizamos la actualización
      //  Si el registro no existe, lo insertará
      $db->upsert( 'orders', $params, $whereParams );

Eliminación de Datos

El método "delete" nos permite eliminar un registro en una tabla específica.

delete( $tableName, $whereParams ).

Parámetros:

$tableName El nombre de la tabla en la que se realizará la inserción
$whereParams Arreglo asociativo de columnas llave de la tabla, colección de pares clave-valor, donde la clave es el nombre de la columna, y el valor es el valor a de la columna clave.

    
      //  Instanciamos un asistente
      //  Si no pasamos parámetro, toma la conexión "default"
      $db = new Db();

      //  Los parámetros, el arreglo columna - valor de columna clave;
      $whereParams['id'] = 1;

      //  Realizamos la eliminación
      $db->delete( 'orders', $whereParams );

Documentación