lib/MLIB/DBO.php

   1 <?php /* vim: set binary expandtab tabstop=4 shiftwidth=4 textwidth=80:
   2 -------------------------------------------------------------------------------
   3                                     mlib
   4 -------------------------------------------------------------------------------
   5 This file is part of mlib.
   6
   7 mlib is free software; you can redistribute it and/or modify it under
   8 the terms of the GNU General Public License as published by the Free
   9 Software Foundation; either version 2 of the License, or (at your option)
  10 any later version.
  11
  12 mlib is distributed in the hope that it will be useful, but WITHOUT
  13 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  14 FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License; if not,
  17 write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330,
  18 Boston, MA  02111-1307  USA
  19 -------------------------------------------------------------------------------
  20 Creado: Thu Aug 28 16:33:47 2003
  21 Autor:  Leandro Lucarella <llucar@mecon.gov.ar>
  22 -------------------------------------------------------------------------------
  23 $Id$
  24 -----------------------------------------------------------------------------*/
  25
  26 /**
  27  * Indica que las condiciones deben concatenarse con <tt>OR</tt>.
  28  */
  29 define('MLIB_DBO_OR', 'OR');
  30
  31 /**
  32  * Indica que las condiciones deben concatenarse con <tt>AND</tt>.
  33  */
  34 define('MLIB_DBO_AND', 'AND');
  35
  36 /**
  37  * @example DBO.php
  38  * Ejemplo de uso de DBO. Por ahora el ejemplo sólo implementa las funciones
  39  * para consulta.
  40  */
  41
  42 // +X2C Class 16 :MLIB_DBO
  43 /**
  44  * Interfaz genérica para objetos que pueden ser guardados y/o operan con bases de datos.
  45 Utilizando esta interfaz se pueden hacer objetos genericos que manejen DBO, como por ejemplo tablas para listarlos. La forma común de recorrer una serie de resultados de una búsqueda de DBO puede verse en el método buscar().
  46  *
  47  * @access public
  48  * @abstract
  49  */
  50 class MLIB_DBO {
  51     // ~X2C
  52
  53     // +X2C Operation 17
  54     /**
  55      * Carga el objeto desde una base de datos.
  56 Si hay un error, devuelve un PEAR_Error, si no devuelve la cantidad de objetos encontrados y carga el primero (si hay al menos un resultado).
  57 En el caso típico, se setea la propiedad que es la clave de la base de datos (siendo el resto nulas). Por ejemplo:
  58 @code
  59 class miDBO extends MLIB_DBO {
  60         // Definición...
  61 }
  62 $db = DB::connect('mi DSN');
  63 $miDBO = new MiDBO();
  64 $miDBO->id = 5;
  65 $e =$miDBO->cargar($db);
  66 if (PEAR::isError($e)) {
  67         echo 'Hubo un error: ' . $e->getMessage();
  68 } elseif (!$e) {
  69         echo 'No existe en la base de datos.';
  70 } elseif ($e == 1) {
  71         var_dump($miDBO);
  72 } else {
  73         echo "Se encontraron $e elementos!';
  74 }
  75 @endcode
  76 @see buscar()
  77 @internal
  78 En el caso general, se hace un <tt>SELECT</tt> con un <tt>WHERE</tt> basado en los atributos no nulos concatenados con <tt>AND</tt>.
  79      *
  80      * @param  mixed $db DB o DB_Result a usar para la carga.
  81      *
  82      * @return mixed
  83      * @access public
  84      * @abstract
  85      */
  86     function cargar($db = null) // ~X2C
  87     {
  88         trigger_error('Not implemented!', E_USER_WARNING);
  89     }
  90     // -X2C
  91
  92     // +X2C Operation 18
  93     /**
  94      * Guarda el objeto en una base de datos.
  95 Si alguna clave es <tt>null</tt>, generalmente se guarda un objeto nuevo autoincrementando la clave en <tt>null</tt>. Si todas las claves son distintas de <tt>null</tt> y existe un objeto con las mismas claves, se modifica del existente los campos que el objeto no tenga en <tt>null</tt>; si no existe da error a menos que se use el indicador <tt>\$nuevo</tt>, en cuyo caso se agrega como nuevo. Si hay un error, devuelve un PEAR_Error. Si se guardan los datos bien, devuelve <tt>true</tt>.
  96 Por ejemplo:
  97 @code
  98 class miDBO extends MLIB_DBO {
  99         // Definición...
 100 }
 101 $db = DB::connect('mi DSN');
 102 $miDBO = new MiDBO();
 103 $miDBO->id = 5;
 104 $miDBO->nombre = 'Petete';
 105 $miDBO->edad = 65;
 106 // Crea una nueva entrada en la DB.
 107 $e =$miDBO->guardar($db, true);
 108 if ($e === true) {
 109         echo 'Se guardó bien.';
 110 } else {
 111         echo 'Hubo un error: ' . $e->getMessage();
 112 }
 113 // Cambia la edad del objeto recién guardado.
 114 $miDBO->edad = 56;
 115 $e =$miDBO->guardar($db);
 116 if ($e === true) {
 117         echo 'Se actualizó bien.';
 118 } else {
 119         echo 'Hubo un error: '. $e->getMessage();
 120 }
 121 @endcode
 122 @internal
 123 En el caso general, se hace un <tt>UPDATE</tt> con un <tt>WHERE</tt> basado en la(s) clave(s) concatenadas con </tt>AND</tt>, y un <tt>SET</tt> con los atributos no <tt>nulos</tt>.
 124      *
 125      * @param  DB $db Base de datos a usar para guardar el objeto.
 126      * @param  bool $nuevo Indica si debe forzarse a guardar una entrada nueva en la DB. Se usa típicamente en bases cuya clave es externa y no puede especificarse un elemento nuevo con \c null en la clave.
 127      *
 128      * @return mixed
 129      * @access public
 130      * @abstract
 131      */
 132     function guardar($db = null, $nuevo = false) // ~X2C
 133     {
 134         trigger_error('Not implemented!', E_USER_WARNING);
 135     }
 136     // -X2C
 137
 138     // +X2C Operation 19
 139     /**
 140      * Borra el objeto de una base de datos.
 141 Si hay un error, devuelve un PEAR_Error. Si no, devuelve la cantidad de objetos borrados de la base de datos.
 142 Por ejemplo:
 143 @code
 144 class miDBO extends MLIB_DBO {
 145         // Definición...
 146 }
 147 $db = DB::connect('mi DSN');
 148 $miDBO = new MiDBO();
 149 $miDBO->id = 5;
 150 $e =$miDBO->borrar($db);
 151 if (PEAR::isError($e)) {
 152         echo 'Hubo un error: ' . $e->getMessage();
 153 } elseif (!$e) {
 154         echo 'No estaba en la base de datos.';
 155 } elseif ($e == 1) {
 156         echo 'Se borró de la base de datos';
 157 } else {
 158         echo "Se borraron $e elementos!';
 159 }
 160 @endcode
 161 @internal
 162 En el caso general, se hace un <tt>DELETE</tt> con un <tt>WHERE</tt> basado en los atributos no nulos concatenados con <tt>AND</tt>.
 163      *
 164      * @param  DB $db Base de datos de donde borrar el objeto.
 165      *
 166      * @return mixed
 167      * @access public
 168      * @abstract
 169      */
 170     function borrar($db = null) // ~X2C
 171     {
 172         trigger_error('Not implemented!', E_USER_WARNING);
 173     }
 174     // -X2C
 175
 176     // +X2C Operation 20
 177     /**
 178      * Busca un objeto en una base de datos.
 179 Si hay un error, devuelve un PEAR_Error. Si no, devuelve un DB_Result con los resultados de la búsqueda.
 180 Por ejemplo:
 181 @code
 182 class miDBO extends MLIB_DBO {
 183         // Definición...
 184 }
 185 $db = DB::connect('mi DSN');
 186 $miDBO = new MiDBO();
 187 $miDBO->nombre = 'rez';
 188 $res = $miDBO->buscar($db, MLIB_DBO_AND, 'nombre ASC');
 189 if (PEAR::isError($res)) {
 190         echo 'Hubo un error.';
 191 } else {
 192         echo 'Se encontraron ' . $res->numRows() . ' elementos.';
 193         while (($miDBO->cargar($res) = $e) === true) {
 194                 var_dump($miDBO);
 195         }
 196         if (PEAR::isError($e)) {
 197                 echo 'Hubo un error: ' . $e->getMessage();
 198         }
 199 }
 200 @endcode
 201 @see cargar()
 202 @example DBO.php
 203 @internal
 204 Es similar a cargar, ya que se hace un <tt>SELECT</tt> con un <tt>WHERE</tt> basado en los atributos no nulos pero puede concatenarse con <tt>AND</tt> u <tt>OR</tt> y se busca con <tt>LIKE</tt> para que dea más general.
 205      *
 206      * @param  DB $db Base de datos a utilizar en la búsqueda.
 207      * @param  int $operador Indica que operador se usa para la búsqueda. Puede ser MLIB_DBO_AND o MLIB_DBO_OR.
 208      * @param  mixed $orden Campos por los cuales ordenar. El formato es <tt>campo (ASC|DESC)</tt> (siedo <tt>ASC</tt> si se lo ordena de forma ascendente y <tt>DESC</tt> si se lo ordena de forma descendente). Puede pasarse un <em>string</em> o un <em>array</em> con varios <em>strings</em> con este formato para ordenarlo por más de un campo a la vez.
 209      *
 210      * @return mixed
 211      * @access public
 212      * @abstract
 213      */
 214     function buscar($db = null, $operador = MLIB_DBO_OR, $orden = '') // ~X2C
 215     {
 216         trigger_error('Not implemented!', E_USER_WARNING);
 217     }
 218     // -X2C
 219
 220 } // -X2C Class :MLIB_DBO
 221
 222 ?>