classes/plfilter.php

   1 <?php
   2 /***************************************************************************
   3  *  Copyright (C) 2003-2010 Polytechnique.org                              *
   4  *  http://opensource.polytechnique.org/                                   *
   5  *                                                                         *
   6  *  This program is free software; you can redistribute it and/or modify   *
   7  *  it under the terms of the GNU General Public License as published by   *
   8  *  the Free Software Foundation; either version 2 of the License, or      *
   9  *  (at your option) any later version.                                    *
  10  *                                                                         *
  11  *  This program is distributed in the hope that it will be useful,        *
  12  *  but WITHOUT ANY WARRANTY; without even the implied warranty of         *
  13  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the          *
  14  *  GNU General Public License for more details.                           *
  15  *                                                                         *
  16  *  You should have received a copy of the GNU General Public License      *
  17  *  along with this program; if not, write to the Free Software            *
  18  *  Foundation, Inc.,                                                      *
  19  *  59 Temple Place, Suite 330, Boston, MA  02111-1307  USA                *
  20  ***************************************************************************/
  21
  22 __autoload('xdb');
  23
  24 // {{{ class PlLimit
  25 class PlLimit
  26 {
  27     private $count = null;
  28     private $from  = null;
  29
  30     public function __construct($count = null, $from = null)
  31     {
  32         $this->count = $count;
  33         $this->from  = $from;
  34     }
  35
  36     public function getSql()
  37     {
  38         if (!is_null($this->count) && $this->count != 0) {
  39             if (!is_null($this->from) && $this->from != 0) {
  40                 return XDB::format('LIMIT {?}, {?}', (int)$this->from, (int)$this->count);
  41             } else {
  42                 return XDB::format('LIMIT {?}', (int)$this->count);
  43             }
  44         }
  45         return '';
  46     }
  47 }
  48 // }}}
  49
  50 // {{{ class PlSqlJoin
  51 class PlSqlJoin
  52 {
  53     private $mode;
  54     private $table;
  55     private $condition;
  56
  57     const MODE_LEFT  = 'LEFT';
  58     const MODE_RIGHT = 'RIGHT';
  59     const MODE_INNER = 'INNER';
  60
  61     private function __construct($mode, $params)
  62     {
  63         $table = array_shift($params);
  64         $condition = call_user_func_array(array('XDB', 'format'), $params);
  65         if ($mode != self::MODE_LEFT && $mode != self::MODE_RIGHT && $mode != self::MODE_INNER) {
  66             Platal::page()->kill("Join mode error: unknown mode $mode");
  67             return;
  68         }
  69         $this->mode = $mode;
  70         $this->table = $table;
  71         $this->condition = $condition;
  72     }
  73
  74     public function mode()
  75     {
  76         return $this->mode;
  77     }
  78
  79     public function table()
  80     {
  81         return $this->table;
  82     }
  83
  84     public function condition()
  85     {
  86         return $this->condition;
  87     }
  88
  89     /** Replace all "metas" in the condition with their translation.
  90      * $ME always becomes the alias of the table
  91      * @param $key The name the joined table will have in the final query
  92      * @param $joinMetas An array of meta => conversion to apply to the condition
  93      */
  94     public function replaceJoinMetas($key, $joinMetas = array())
  95     {
  96         $joinMetas['$ME'] = $key;
  97         return str_replace(array_keys($joinMetas), $joinMetas, $this->condition);
  98     }
  99
 100     /** Create a join command from an array of PlSqlJoin
 101      * @param $joins The list of 'join' to convert into an SQL query
 102      * @param $joinMetas An array of ('$META' => 'conversion') to apply to the joins.
 103      */
 104     public static function formatJoins(array $joins, array $joinMetas)
 105     {
 106         $str = '';
 107         foreach ($joins as $key => $join) {
 108             if (!($join instanceof PlSqlJoin)) {
 109                 Platal::page()->kill("Error: not a join: $join");
 110             }
 111             $mode  = $join->mode();
 112             $table = $join->table();
 113             $str .= ' ' . $mode . ' JOIN ' . $table . ' AS ' . $key;
 114             if ($join->condition() != null) {
 115                 $str .= ' ON (' . $join->replaceJoinMetas($key, $joinMetas) . ')';
 116             }
 117             $str .= "\n";
 118         }
 119         return $str;
 120     }
 121
 122     /** Build a left join
 123      * @param table The name of the table.
 124      * @param condition The condition of the jointure
 125      */
 126     public static function left()
 127     {
 128         $params = func_get_args();
 129         return new PlSqlJoin(self::MODE_LEFT, $params);
 130     }
 131
 132     /** Build a right join
 133      * @param table The name of the table.
 134      * @param condition The condition of the jointure
 135      */
 136     public static function right()
 137     {
 138         $params = func_get_args();
 139         return new PlSqlJoin(self::MODE_RIGHT, $params);
 140     }
 141
 142     /** Build a inner join
 143      * @param table The name of the table.
 144      * @param condition The condition of the jointure
 145      */
 146     public static function inner()
 147     {
 148         $params = func_get_args();
 149         return new PlSqlJoin(self::MODE_INNER, $params);
 150     }
 151 }
 152 // }}}
 153
 154 // {{{ class PlFilterOrder
 155 /** Base class for ordering results of a query.
 156  * Parameters for the ordering must be given to the constructor ($desc for a
 157  *     descending order).
 158  * The getSortTokens function is used to get actual ordering part of the query.
 159  */
 160 abstract class PlFilterOrder
 161 {
 162     protected $desc = false;
 163     public function __construct($desc = false)
 164     {
 165         $this->desc = $desc;
 166         $this->_tokens = null;
 167     }
 168
 169     public function toggleDesc()
 170     {
 171         $this->desc = !$this->desc;
 172     }
 173
 174     public function setDescending($desc = true)
 175     {
 176         $this->desc = $desc;
 177     }
 178
 179     public function buildSort(PlFilter &$pf)
 180     {
 181         $sel = $this->getSortTokens($pf);
 182         $this->_tokens = $sel;
 183         if (!is_array($sel)) {
 184             $sel = array($sel);
 185         }
 186         if ($this->desc) {
 187             foreach ($sel as $k => $s) {
 188                 $sel[$k] = $s . ' DESC';
 189             }
 190         }
 191         return $sel;
 192     }
 193
 194     /** This function must return the tokens to use for ordering
 195      * @param &$pf The PlFilter whose results must be ordered
 196      * @return The name of the field to use for ordering results
 197      */
 198     abstract protected function getSortTokens(PlFilter &$pf);
 199 }
 200 // }}}
 201
 202 // {{{ class PlFilterGroupableOrder
 203 /** Extension of a PlFilterOrder, for orders where the value on which ordering
 204  * is done could be used for grouping results (promo, country, ...)
 205  */
 206 abstract class PlFilterGroupableOrder extends PlFilterOrder
 207 {
 208     /** This function will be called when trying to retrieve groups;
 209      * the returned token will be used to group the values.
 210      * It will always be called AFTER getSortTokens().
 211      */
 212     public function getGroupToken(PlFilter &$pf)
 213     {
 214         return $this->_tokens;
 215     }
 216 }
 217 // }}}
 218
 219 // {{{ class PFO_Random
 220 class PFO_Random extends PlFilterOrder
 221 {
 222     private $seed = null;
 223
 224     public function __construct($seed = null, $desc = false)
 225     {
 226         parent::__construct($desc);
 227         $this->seed = $seed;
 228     }
 229
 230     protected function getSortTokens(PlFilter &$pf)
 231     {
 232         if ($this->seed == null) {
 233             return 'RAND()';
 234         } else {
 235             return XDB::format('RAND({?})', $this->seed);
 236         }
 237     }
 238 }
 239 // }}}
 240
 241 // {{{ interface PlFilterCondition
 242 interface PlFilterCondition
 243 {
 244     const COND_TRUE  = 'TRUE';
 245     const COND_FALSE = 'FALSE';
 246
 247     public function buildCondition(PlFilter &$pf);
 248 }
 249 // }}}
 250
 251 // {{{ class PFC_OneChild
 252 abstract class PFC_OneChild implements PlFilterCondition
 253 {
 254     protected $child;
 255
 256     public function __construct(&$child = null)
 257     {
 258         if (!is_null($child) && ($child instanceof PlFilterCondition)) {
 259             $this->setChild($child);
 260         }
 261     }
 262
 263     public function setChild(PlFilterCondition &$cond)
 264     {
 265         $this->child =& $cond;
 266     }
 267 }
 268 // }}}
 269
 270 // {{{ class PFC_NChildren
 271 abstract class PFC_NChildren implements PlFilterCondition
 272 {
 273     protected $children = array();
 274
 275     public function __construct()
 276     {
 277         $this->addChildren(pl_flatten(func_get_args()));
 278     }
 279
 280     public function addChildren(array $conds)
 281     {
 282         foreach ($conds as &$cond) {
 283             if (!is_null($cond) && ($cond instanceof PlFilterCondition)) {
 284                 $this->addChild($cond);
 285             }
 286         }
 287     }
 288
 289     public function addChild(PlFilterCondition &$cond)
 290     {
 291         $this->children[] =& $cond;
 292     }
 293
 294     protected function catConds(array $cond, $op, $fallback)
 295     {
 296         if (count($cond) == 0) {
 297             return $fallback;
 298         } else if (count($cond) == 1) {
 299             return $cond[0];
 300         } else {
 301             return '(' . implode(') ' . $op . ' (', $cond) . ')';
 302         }
 303     }
 304 }
 305 // }}}
 306
 307 // {{{ class PFC_True
 308 class PFC_True implements PlFilterCondition
 309 {
 310     public function buildCondition(PlFilter &$uf)
 311     {
 312         return self::COND_TRUE;
 313     }
 314 }
 315 // }}}
 316
 317 // {{{ class PFC_False
 318 class PFC_False implements PlFilterCondition
 319 {
 320     public function buildCondition(PlFilter &$uf)
 321     {
 322         return self::COND_FALSE;
 323     }
 324 }
 325 // }}}
 326
 327 // {{{ class PFC_Not
 328 class PFC_Not extends PFC_OneChild
 329 {
 330     public function buildCondition(PlFilter &$uf)
 331     {
 332         $val = $this->child->buildCondition($uf);
 333         if ($val == self::COND_TRUE) {
 334             return self::COND_FALSE;
 335         } else if ($val == self::COND_FALSE) {
 336             return self::COND_TRUE;
 337         } else {
 338             return 'NOT (' . $val . ')';
 339         }
 340     }
 341 }
 342 // }}}
 343
 344 // {{{ class PFC_And
 345 class PFC_And extends PFC_NChildren
 346 {
 347     public function buildCondition(PlFilter &$uf)
 348     {
 349         if (empty($this->children)) {
 350             return self::COND_FALSE;
 351         } else {
 352             $true = self::COND_FALSE;
 353             $conds = array();
 354             foreach ($this->children as &$child) {
 355                 $val = $child->buildCondition($uf);
 356                 if ($val == self::COND_TRUE) {
 357                     $true = self::COND_TRUE;
 358                 } else if ($val == self::COND_FALSE) {
 359                     return self::COND_FALSE;
 360                 } else {
 361                     $conds[] = $val;
 362                 }
 363             }
 364             return $this->catConds($conds, 'AND', $true);
 365         }
 366     }
 367 }
 368 // }}}
 369
 370 // {{{ class PFC_Or
 371 class PFC_Or extends PFC_NChildren
 372 {
 373     public function buildCondition(PlFilter &$uf)
 374     {
 375         if (empty($this->children)) {
 376             return self::COND_TRUE;
 377         } else {
 378             $true = self::COND_TRUE;
 379             $conds = array();
 380             foreach ($this->children as &$child) {
 381                 $val = $child->buildCondition($uf);
 382                 if ($val == self::COND_TRUE) {
 383                     return self::COND_TRUE;
 384                 } else if ($val == self::COND_FALSE) {
 385                     $true = self::COND_FALSE;
 386                 } else {
 387                     $conds[] = $val;
 388                 }
 389             }
 390             return $this->catConds($conds, 'OR', $true);
 391         }
 392     }
 393 }
 394 // }}}
 395
 396 // {{{ class PlFilter
 397 abstract class PlFilter
 398 {
 399     /** Filters objects matching the PlFilter
 400      * @param $objects The objects to filter
 401      * @param $limit The portion of the matching objects to show
 402      */
 403     public abstract function filter(array $objects, $limit = null);
 404
 405     public abstract function setCondition(PlFilterCondition &$cond);
 406
 407     public abstract function addSort(PlFilterOrder &$sort);
 408
 409     public abstract function getTotalCount();
 410
 411     /** Whether this PlFilter can return grouped results through
 412      * $this->getGroups();
 413      */
 414     public abstract function hasGroups();
 415
 416     /** Used to retrieve value/amount resulting from grouping by the first
 417      * given order.
 418      */
 419     public abstract function getGroups();
 420
 421     /** Get objects, selecting only those within a limit
 422      * @param $limit The portion of the matching objects to select
 423      */
 424     public abstract function get($limit = null);
 425
 426     /** PRIVATE FUNCTIONS
 427      */
 428
 429     /** List of metas to replace in joins:
 430      * '$COIN' => 'pan.x' means 'replace $COIN with pan.x in the condition of the joins'
 431      *
 432      * "$ME" => "joined table alias" is always added to these.
 433      */
 434     protected $joinMetas = array();
 435
 436     protected $joinMethods = array();
 437
 438     /** Build the 'join' part of the query
 439      * This function will call all methods declared in self::$joinMethods
 440      * to get an array of PlSqlJoin objects to merge
 441      */
 442     protected function buildJoins()
 443     {
 444         $joins = array();
 445         foreach ($this->joinMethods as $method) {
 446             $joins = array_merge($joins, $this->$method());
 447         }
 448         return PlSqlJoin::formatJoins($joins, $this->joinMetas);
 449     }
 450
 451 }
 452 // }}}
 453
 454 // vim:set et sw=4 sts=4 sws=4 foldmethod=marker enc=utf-8:
 455 ?>