lib/MECON/DBO.php

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