1 : <?php
2 : /**
3 : * PHPDevShell is a RAD Framework aimed at developing administrative applications.
4 : *
5 : * @package PHPDevShell
6 : * @link http://www.phpdevshell.org
7 : * @copyright Copyright (C) 2007 Jason Schoeman, All rights reserved.
8 : * @license GNU/LGPL, see readme/licensed_under_lgpl or http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html
9 : * @author Jason Schoeman, Contact: titan [at] phpdevshell [dot] org.
10 : *
11 : * This is an abstraction class to help you deal with SQL queries. Look at http://wiki.phpdevshell.org/wiki/Queries.
12 : *
13 : * Copyright notice: See readme/notice
14 : * By using PHPDevShell you agree to notice and license, if you dont agree to this notice/license you are not allowed to use PHPDevShell.
15 : */
16 :
17 : /**
18 : * PHPDevShell official Query handler.
19 : *
20 : * @author Greg
21 : */
22 : class PHPDS_query extends PHPDS_dependant
23 : {
24 : /**
25 : * The explicit SQL query
26 : *
27 : * This value, if present, is used when not overiden by an array in the field named "fields"
28 : * It can be accessed from the outside world thought the sql() method.
29 : * @see $fields
30 : * @see sql()
31 : * @var string,
32 : */
33 : protected $sql;
34 :
35 : /**
36 : * The name of the field to use as a key.
37 : *
38 : * By default this is set to the special value '__auto__', which means the class have to figure out what's to be used.
39 : * @var string
40 : */
41 : protected $keyField = '__auto__';
42 :
43 : /**
44 : * Make a field the point of interest
45 : *
46 : * This field changes the way some arrays are returned:
47 : * - if $focus contains a field name, a row will be the value of this field (scalar) instead of an array of all values in the row
48 : * - if the row doesn't contain a field an empty value is used for the row
49 : * @var string
50 : */
51 : protected $focus = ''; // can be empty for 'no' or any other value for field name
52 :
53 : /**
54 : * strips any row with no content
55 : * @var boolean
56 : */
57 : protected $noEmptyRow = false;
58 :
59 : /**
60 : * Guidelines to typecast/forcecast the result data
61 : *
62 : * @var string | array of strings
63 : */
64 : protected $typecast;
65 :
66 : /**
67 : * The first line of the result is returned instead of a one-line array
68 : *
69 : * @var boolean
70 : */
71 : protected $singleRow = false;
72 :
73 : /**
74 : * Automatically escape bad chars for all in-parameters
75 : * @var boolean
76 : */
77 : protected $autoProtect = false;
78 :
79 : /**
80 : * Instead of the query result, returns the last_insert_id()
81 : * @var boolean
82 : */
83 : protected $returnId = false;
84 :
85 : /**
86 : * Return one value from the asked field of the asked line
87 : * @var boolean
88 : */
89 : protected $singleValue = false;
90 :
91 : /**
92 : * A link between the query and the actual database server.
93 : *
94 : * Don't mess up with this.
95 : * @var PHPDS_db_connector, the connector used to carry the query
96 : */
97 : private $connector;
98 :
99 : /**
100 : * The list of fields to study
101 : *
102 : * If present, this associative array contains the fields which will be present in the SELECT ... clause.
103 : * This will override the $sql field; however if you use the sql('something') method after prebuild() the new query string will override the fields
104 : * @see $sql
105 : * @var array (optional)
106 : */
107 : protected $fields;
108 :
109 : /**
110 : * The WHERE clause
111 : *
112 : * A default WHERE clause; note you can use the addWhere() method to concatenate after this value
113 : * @var string (optional)
114 : */
115 : protected $where;
116 : protected $groupby = '';
117 : protected $orderby = '';
118 : protected $limit = '';
119 :
120 : /**
121 : * In some specific case (namely debugging) this will contain a cached version of the results
122 : * AVOID playing with that
123 : * @date 20110218 (greg) added
124 : * @var array
125 : */
126 : protected $cachedResult;
127 :
128 : //////////////////////////////////////////////////////////////////////////////
129 : //////////////////////////////////////////////////////////////////////////////
130 : //////////// DEPRECATED DUE TO WRONG NAMING CONVENTION ///////////////////////
131 : //////////// DONT USE THESE METHODS !!!!!!!!!!!!!!!!! ////////////////////////
132 : //////////////////////////////////////////////////////////////////////////////
133 : /**
134 : * @deprecated
135 : * @var boolean
136 : */
137 : protected $single_value;
138 : /**
139 : * @deprecated
140 : * @var boolean
141 : */
142 : protected $return_id;
143 : /**
144 : * @deprecated
145 : * @var boolean
146 : */
147 : protected $auto_protect;
148 : /**
149 : * @deprecated
150 : * @var boolean
151 : */
152 : protected $single_row;
153 : /**
154 : * @deprecated
155 : * @var boolean
156 : */
157 : protected $no_empty_row;
158 : //////////////////////////////////////////////////////////////////////////////
159 : //////////////////////////////////////////////////////////////////////////////
160 : //////////////////////////////////////////////////////////////////////////////
161 : //////////////////////////////////////////////////////////////////////////////
162 :
163 : /**
164 : * Backwards compatible variables.
165 : */
166 : public function __construct ()
167 : {
168 57 : if (isset($this->no_empty_row))
169 57 : $this->noEmptyRow = $this->no_empty_row;
170 57 : if (isset($this->single_row))
171 57 : $this->singleRow = $this->single_row;
172 57 : if (isset($this->auto_protect))
173 57 : $this->autoProtect = $this->auto_protect;
174 57 : if (isset($this->return_id))
175 57 : $this->returnId = $this->return_id;
176 57 : if (isset($this->single_value))
177 57 : $this->singleValue = $this->single_value;
178 57 : }
179 :
180 : public function connector($connector = null)
181 : {
182 57 : if (is_a($connector, 'PHPDS_dbConnector')) $this->connector = $connector;
183 57 : return $this->connector = $connector;
184 : }
185 :
186 : /**
187 : * The usual process of a query: check the parameters, send the query to the server, check the results
188 : *
189 : * Return the results as an array (for SELECT queries), true for other successfull queries, false on failure
190 : *
191 : * @version 1.1.1
192 : * @date 20100709 (greg) (v1.1.1) changed is_resource() to !empty() because it may return something else
193 : * @param mixed $parameters
194 : * @return array or boolean
195 : */
196 : public function invoke($parameters = null)
197 : {
198 : try {
199 21 : if ($this->checkParameters($parameters)) {
200 21 : $res = $this->query($parameters);
201 : // Fix to prevent invoke from returning false if INSERT REPLACE DELETE etc... is executed on success.
202 1 : if ($res === true && empty($this->returnId))
203 : // Check affected rows.
204 1 : return $this->connector->affectedRows();
205 0 : if (!empty($res)) {
206 0 : $results = $this->getResults();
207 0 : if ($this->checkResults($results))
208 0 : return $results;
209 0 : } else return $res;
210 0 : }
211 0 : return false;
212 20 : } catch (Exception $e) {
213 20 : $msg = '<p>The faulty query source sql is:<br /><pre class="ui-state-highlight ui-corner-all">'.$this->sql().'</pre><br />';
214 20 : if (!empty($parameters)) $msg .= 'The parameters were:<br /><tt>'.PU_dumpArray($parameters).'</tt></p>';
215 20 : throw new PHPDS_databaseException($msg, 0, $e);
216 : }
217 : }
218 :
219 : /**
220 : * Build and send the query to the database
221 : *
222 : * @since 20100219
223 : * @version 1.0.3
224 : * @date 20110216 (greg) (v1.0.3) added a log of the sql + the class name
225 : * @date 20110731 (greg) altered to use $this->querySQL
226 : * @author greg
227 : * @param mixed $parameters (optional)array, the parameters to inject into the query
228 : * @return void
229 : */
230 : public function query($parameters = null)
231 : {
232 :
233 21 : $sql = $this->build($parameters);
234 21 : return $this->querySQL($sql);
235 : }
236 :
237 : /**
238 : * Direclty send the query to the database
239 : *
240 : * @since 20110731
241 : * @version 1.0
242 : * @date 20110731 (greg) added based on old $this->query
243 : * @author greg
244 : * @param string $sql, the sql request
245 : * @return void
246 : */
247 : public function querySQL($sql)
248 : {
249 : try {
250 21 : $result = $this->connector->query($sql);
251 :
252 1 : $this->queryDebug($sql);
253 :
254 1 : return $result;
255 20 : } catch (Exception $e) {
256 20 : $msg = '<p>The faulty query REAL SQL was:<br /><pre class="ui-state-highlight ui-corner-all">' . $sql . '</pre><br />';
257 20 : throw new PHPDS_databaseException($msg, 0, $e);
258 : }
259 : }
260 :
261 : public function queryDebug($sql)
262 : {
263 1 : $debug = $this->debugInstance();
264 1 : $firephp = $this->errorHandler->getFirePHP();
265 1 : if ($debug->enable() && $firephp && !headers_sent()) {
266 :
267 : $flags =
268 0 : ($this->singleRow ? ' singleRow' : '' ).($this->singleValue ? ' singleValue' : '' ).($this->noEmptyRow ? ' noEmptyRow ' : '' )
269 0 : .(empty($this->focus) ? '' : ' focus='.$this->focus).(empty($this->keyField) ? '' : ' keyField='.$this->keyField).(empty($this->typeCast) ? '' : ' typeCast='.$this->typeCast);
270 :
271 0 : $table = array();
272 0 : $table[] = array('','');
273 0 : $table[] = array('SQL', $sql);
274 0 : $table[] = array('count', $this->count(). ' rows');
275 0 : $table[] = array('flags', $flags);
276 :
277 0 : $firephp->table('Query: '.get_class($this), $table);
278 :
279 : /*$firephp->group('Query: '.get_class($this),
280 : array('Collapsed' => true,
281 : 'Color' => '#64c40a'));
282 :
283 : $firephp->log($sql, '[ SQL ]');
284 : $firephp->log($this->count(). ' rows', '[ count ]');
285 : $firephp->log($flags,'[ flags ]');
286 : //$firephp->log($this->asWhole(), '[ '.$this->count(). ' rows ]');
287 : $firephp->groupEnd();*/
288 0 : }
289 1 : }
290 :
291 : /**
292 : * Build a query combination of columns and rows specifically designed to write rows of data to the database.
293 : *
294 : * @since 20100226
295 : * @since 20100226
296 : * @version 1.0.0
297 : * @param array Holds columns in the order they need to be written.
298 : */
299 : public function rows($parameters = null)
300 : {
301 : // Loop and build rows.
302 0 : $r = '';
303 0 : $build = '';
304 0 : foreach ($parameters as $col) {
305 0 : foreach ($col as $row) {
306 0 : $r .= "'" . $row . "',";
307 0 : }
308 0 : $r = rtrim($r, ',');
309 0 : $build .= "($r),";
310 0 : $r = '';
311 0 : }
312 0 : $parameters = rtrim($build, ',');
313 0 : if (! empty($parameters)) {
314 0 : return $parameters;
315 : } else {
316 0 : return false;
317 : }
318 : }
319 :
320 : /**
321 : * Get/set actual sql string.
322 : *
323 : * You may want to override this to alter the sql string as whole, and/or build it from various sources.
324 : * Note this is only the first part of the query (SELECT ... FROM ...), NOT including WHERE, GROUP BY, ORDER BY, LIMIT
325 : *
326 : * @param string $sql (optional) if given, stored into the object's sql string
327 : * @return string the sql text
328 : * @version 1.0
329 : * @author greg
330 : */
331 : public function sql($sql = null)
332 : {
333 21 : if (!empty($sql)) $this->sql = $sql;
334 21 : return $this->sql;
335 : }
336 :
337 : /**
338 : * Build the query based on the private sql and the parameters
339 : *
340 : * @since 20100216
341 : * @since 20100428 (v1.0.1) (greg) use sql() instead of sql
342 : * @date 20100630 (v1.0.2) (greg) use array_compact to avoid null values
343 : * @version 1.0.2
344 : * @author greg
345 : * @param $parameters (optional)array, the parameters to inject into the query
346 : * @return string, the sql query string
347 : */
348 : public function build($parameters = null)
349 : {
350 21 : $sql = '';
351 :
352 : try {
353 : // Pre built.
354 21 : $this->preBuild();
355 21 : $sql = $this->sql() . $this->extraBuild($parameters);
356 :
357 21 : if (!empty($parameters)) {
358 20 : if (is_scalar($parameters)) $parameters = array($parameters);
359 :
360 20 : if (is_array($parameters)) {
361 : // Todo: Currently breaks code as we do double protection in security.class.php.
362 20 : if ($this->autoProtect) $parameters = $this->protectArray($parameters);
363 : //$sql = vsprintf($sql, PU_array_compact($parameters));
364 20 : $sql = PU_sprintfn($sql, PU_array_compact($parameters));
365 20 : }
366 : //TODO is parameters is neither scalar nor array what should we do?
367 20 : }
368 21 : } catch (Exception $e) {
369 0 : throw new PHPDS_databaseException('Error building sql for <tt>' . get_class() . '</tt>', 0 ,$e);
370 : }
371 21 : return $sql;
372 : }
373 :
374 : /**
375 : * Construct the extra part of the query (WHERE ... GROUP BY ... ORDER BY...)
376 : * Doesn't change $this->sql
377 : *
378 : * @param array $parameters
379 : * @return string (sql)
380 : * @version 1.0
381 : * @author greg
382 : */
383 : public function extraBuild($parameters = null)
384 : {
385 21 : $extra_sql = '';
386 :
387 21 : if (!empty($this->where)) $extra_sql .= ' WHERE '.$this->where.' ';
388 21 : if (!empty($this->groupby)) $extra_sql .= ' GROUP BY '.$this->groupby.' ';
389 21 : if (!empty($this->orderby)) $extra_sql .= ' ORDER BY '.$this->orderby.' ';
390 21 : if (!empty($this->limit)) $extra_sql .= ' LIMIT '.$this->limit.' ';
391 :
392 21 : return $extra_sql;
393 : }
394 :
395 : /**
396 : * If the fields list has been set, construct the SELECT statement (or else do nothing)
397 : *
398 : * @version 1.0.1
399 : * @author greg
400 : * @date 20100628 (v1.0.1) (greg) the build sql string replaces the obejct's sql field, instead of being appended
401 : * @return nothing
402 : */
403 : public function preBuild()
404 : {
405 21 : $fields = $this->fields;
406 21 : if (!empty($fields)) {
407 0 : $sql = '';
408 0 : $key = $this->getKey();
409 0 : if ($key && !in_array($key, $fields)) $fields[$key] = true;
410 0 : foreach(array_keys($fields) as $key) if (!is_numeric($key)) $sql .= $key.', ';
411 0 : $sql = 'SELECT '.rtrim($sql, ', ');
412 :
413 0 : if (!empty($this->tables)) $sql .= ' FROM ' . $this->tables;
414 0 : $this->sql = $sql;
415 0 : }
416 21 : }
417 :
418 : /**
419 : * Add a subclause to the main WHERE clause of the query
420 : *
421 : * @param string $sql
422 : * @return self
423 : */
424 : public function addWhere($sql, $mode = 'AND')
425 : {
426 0 : if (empty($this->where)) $this->where = '1';
427 0 : $this->where .= " $mode $sql ";
428 0 : return $this;
429 : }
430 :
431 : /**
432 : * Protect a array of strings from possible hacker (i.e. escape possible harmfull chars)
433 : *
434 : * @since 20100216
435 : * @version 1.0
436 : * @author greg
437 : * @param $a array, the strings to protect
438 : * @return array, the same string but safe
439 : */
440 : public function protectArray(array $a)
441 : {
442 0 : foreach($a as $index => $value) {
443 0 : $v = null;
444 0 : if (is_array($value)) {
445 0 : $v = $this->protectArray($value);
446 0 : }
447 0 : if (is_scalar($value)) {
448 0 : $v = $this->connector->protect($value);
449 0 : }
450 0 : if (!empty($v)) {
451 0 : $a[$index] = $v;
452 0 : }
453 0 : }
454 :
455 0 : return $a;
456 : }
457 :
458 : /**
459 : * Protect a strings from possible hacker (i.e. escape possible harmfull chars)
460 : *
461 : * @since 20101109
462 : * @version 1.0
463 : * @author Jason
464 : * @param string the strings to protect
465 : * @return string the same string but safe
466 : */
467 : public function protectString($string)
468 : {
469 0 : $clean = $this->connector->protect($string);
470 0 : return $clean;
471 : }
472 :
473 : /**
474 : * Try to figure out which is the key field.
475 : *
476 : * @param array $row, a sample row to study
477 : * @return string (or null), the key field name
478 : * @version 1.0
479 : * @author greg
480 : */
481 : public function getKey($row = null)
482 : {
483 0 : $key = $this->keyField;
484 0 : if (is_array($row)) {
485 0 : if ('__auto__' == $key) {
486 0 : $keys = array_keys($row);
487 0 : $key = array_shift($keys);
488 0 : }
489 0 : return ($key && !empty($row[$key])) ? $row[$key] : null;
490 : } else {
491 0 : return '__auto__' != $key ? $key : null;
492 : }
493 : }
494 :
495 : /**
496 : * Returns all lines from the result as a big array of arrays
497 : *
498 : * @since 20100216 (v1.0) (greg)
499 : * @since 20100428 (v1.1) (greg) use the focus parameter; use the smart key
500 : * @since 20100607 (v1.2) (greg) renamed compact to focus, use the noEmptyRow/single_line parameters
501 : * @version 1.1
502 : * @author greg
503 : * @return array, all the lines as arrays
504 : */
505 : public function asWhole()
506 : {
507 0 : $result = array();
508 :
509 0 : while ($row = $this->asLine()) {
510 0 : $key = $this->getKey($row);
511 0 : if (!empty($this->focus)) {
512 0 : $row = (isset($row[$this->focus])) ? $row[$this->focus] : null;
513 0 : }
514 0 : if ($row || !empty($this->noEmptyRow)) {
515 0 : if ($key) $result[$key] = $row; else $result[] = $row;
516 0 : }
517 0 : }
518 0 : return $result;
519 : }
520 :
521 : /**
522 : *
523 : * @param <type> $values
524 : * @param <type> $key
525 : * @return <type>
526 : */
527 : public function typeCast($values, $key = null)
528 : {
529 35 : if (!empty($this->typecast)) {
530 35 : if (is_array($values)) {
531 1 : foreach($values as $key => $value) $values[$key] = $this->typeCast($value, $key);
532 1 : } else {
533 35 : $type = is_array($this->typecast) ? (!empty($this->typecast[$key]) ? $this->typecast[$key] : null) : $this->typecast;
534 : switch ($type) {
535 35 : case 'string':
536 5 : $values = (string)$values; break;
537 31 : case 'int':
538 31 : case 'integer':
539 11 : $values = (int)$values; break;
540 21 : case 'bool':
541 21 : case 'boolean':
542 11 : $values = (bool)$values; break;
543 10 : case 'float':
544 10 : case 'double':
545 10 : $values = (float)$values; break;
546 : // default is to NOT change the $value
547 : }
548 :
549 : }
550 35 : }
551 35 : return $values;
552 : }
553 :
554 : /**
555 : * Deal with all special cases (i.e flags) regarding how results should be returned
556 : *
557 : * The special cases handled are these (in order of precedence):
558 : * - returnId (instead of the actual result, lastId is returned)
559 : * - singleValue (only the first value is returned as a scalar)
560 : * - singleRow (the first row is returned as a an one-dimension array)
561 : *
562 : * Cell-specific handling is done elsewhere
563 : *
564 : * In the absence of special case, the whole result is returned as an array of arrays (by calling as_whole() )
565 : *
566 : * @version 1.1
567 : *
568 : * @date 20100610 (greg) (v1.0) added, based on Jason's work
569 : * @date 20100617 (jason) (v1.0.1) added support for "string" setting
570 : * @date 20100620 (greg) (v1.0.2) cleaned up using class methods
571 : * @date 20100708 (greg) (v1.1) clean up with definitive API
572 : *
573 : * @return usually an array, although can be false, or int for an ID
574 : */
575 : public function getResults()
576 : {
577 : // connection ID could be returned whatever the result size
578 0 : if (! empty($this->returnId))
579 0 : return $this->connector->lastId();
580 :
581 0 : if (!empty($this->singleValue))
582 0 : return $this->asOne();
583 :
584 0 : if (!empty($this->singleRow))
585 0 : return $this->asLine();
586 :
587 : // Special case when result is actualy empty.
588 0 : if ($this->count() == 0) return false;
589 :
590 : // Default return as whole.
591 0 : return $this->asWhole();
592 : }
593 :
594 : /**
595 : * Returns a single field from every line, resulting in an array of values (ie some kind of "vertical" fetching)
596 : *
597 : * Note: this is different from as_whole, since only ONE value is present in each line
598 : *
599 : * @since 20100216
600 : * @version 1.0
601 : * @author greg
602 : * @param $field string, the field to extract on each line
603 : * @return array, all the values
604 : */
605 : public function asArray($field)
606 : {
607 0 : $a = array();
608 :
609 0 : while ($row = $this->connector->fetchAssoc()) {
610 0 : if (!empty($row[$field])) {
611 0 : $value = $row[$field];
612 :
613 0 : if (!empty($row[$this->keyField])) $a[$row[$this->keyField]] = $value;
614 0 : else $a[] = $value;
615 0 : }
616 0 : }
617 0 : return $a;
618 : }
619 :
620 : /**
621 : * Returns the asked line as an array
622 : *
623 : * You can either ask for the next line (no parameter) or given a row number in the result.
624 : *
625 : * Note: the row number is based on the result, it may not be same as the row number in the complete table
626 : *
627 : * @since 3.0
628 : * @version 1.0.1
629 : * @author greg
630 : *
631 : * @date 20100810 (v1.0.1) (greg) return null if the resultset is empty
632 :
633 : * @param integer $row_number (optional)
634 : * @return array| null, the line or null if the resultset is empty
635 : */
636 : public function asLine($row_number = null)
637 : {
638 0 : if ($this->count() > 0) {
639 0 : if (is_integer($row_number)) $this->connector->seek($row_number);
640 0 : $row = $this->connector->fetchAssoc();
641 :
642 0 : return $this->typeCast($row);
643 : }
644 0 : }
645 :
646 : /**
647 : * Return one value from the asked field of the asked line
648 : *
649 : * @since 3.0
650 : * @version 1.0.3
651 : * @author greg
652 : *
653 : * @date 20100620 (v1.0.1) (greg) made parameters optional (no "field" means first field)
654 : * @date 20100630 (v1.0.2) (greg) object's focus is used if "$field" parameter is empty
655 : * @date 20100810 (v1.0.3) (greg) return null if the resultset is empty
656 : *
657 : * @param integer $row_number (optional)
658 : * @param string $field field name (optional)
659 : * @return string | null
660 : */
661 : public function asOne($row_number = null, $field = null)
662 : {
663 0 : if ($this->count() > 0) {
664 0 : $row = $this->asLine($row_number);
665 0 : if (!empty($field)) $field = $this->focus;
666 0 : if (!empty($field)) return (isset($row[$field]) ? $row[$field] : null);
667 0 : else return array_shift($row);
668 : }
669 0 : }
670 :
671 : /**
672 : * Return the number of lines in a result
673 : *
674 : * @since 20100216
675 : * @version 1.0
676 : * @author greg
677 : * @return integer, the number of rows
678 : */
679 : public function count()
680 : {
681 0 : return $this->connector->numrows();
682 : }
683 :
684 : /**
685 : * Limits query.
686 : *
687 : * @param int $limit
688 : */
689 : public function limit($limit)
690 : {
691 : // TODO: check parameter
692 0 : $this->limit = $limit;
693 0 : }
694 :
695 : /* THESE METHODS ARE MEANT TO BE OVERRIDEN */
696 :
697 : /**
698 : * Allows daughter classes to check the parameters array before the query is sent
699 : *
700 : * @param $parameters array, the unprotected parameters
701 : * @return boolean true is it's ok to sent, false otherwise
702 : */
703 : public function checkParameters(&$parameters = null)
704 : {
705 1 : return true;
706 : }
707 :
708 : /**
709 : * Allows daughter classes to check the results array before it's sent back
710 : *
711 : * @param $parameters array, the unprotected results
712 : * @return boolean true is it's ok to sent, false otherwise
713 : */
714 : public function checkResults(&$results = null)
715 : {
716 0 : return true;
717 : }
718 :
719 :
720 : public function debugInstance($domain = null)
721 : {
722 1 : return parent::debugInstance(empty($domain) ? 'QUERY%'.get_class($this): $domain);
723 : }
724 :
725 : //////////////////////////////////////////////////////////////////////////////
726 : //////////////////////////////////////////////////////////////////////////////
727 : //////////// DEPRECATED DUE TO WRONG NAMING CONVENTION ///////////////////////
728 : //////////// DONT USE THESE METHODS !!!!!!!!!!!!!!!!! ////////////////////////
729 : //////////////////////////////////////////////////////////////////////////////
730 : /**
731 : * Construct the extra part of the query (WHERE ... GROUP BY ... ORDER BY...)
732 : * Doesn't change $this->sql
733 : *
734 : * @deprecated
735 : * @param array $parameters
736 : * @return string (sql)
737 : * @version 1.0
738 : * @author greg
739 : */
740 : public function extra_build($parameters = null)
741 : {
742 0 : return $this->extraBuild($parameters);
743 : }
744 :
745 : /**
746 : * Protect a array of strings from possible hacker (i.e. escape possible harmfull chars)
747 : *
748 : * @deprecated
749 : * @since 20100216
750 : * @version 1.0
751 : * @author greg
752 : * @param $a array, the strings to protect
753 : * @return array, the same string but safe
754 : */
755 : public function protect_array(array $a)
756 : {
757 0 : return $this->protectArray($a);
758 : }
759 :
760 : /**
761 : * Try to figure out which is the key field.
762 : *
763 : * @deprecated
764 : * @param array $row, a sample row to study
765 : * @return string (or null), the key field name
766 : * @version 1.0
767 : * @author greg
768 : */
769 : public function get_key($row = null)
770 : {
771 0 : return $this->getKey($row);
772 : }
773 :
774 : /**
775 : * Returns all lines from the result as a big array of arrays
776 : *
777 : * @deprecated
778 : * @since 20100216 (v1.0) (greg)
779 : * @since 20100428 (v1.1) (greg) use the focus parameter; use the smart key
780 : * @since 20100607 (v1.2) (greg) renamed compact to focus, use the noEmptyRow/single_line parameters
781 : * @version 1.1
782 : * @author greg
783 : * @return array, all the lines as arrays
784 : */
785 : public function as_whole()
786 : {
787 0 : return $this->asWhole();
788 : }
789 :
790 : /**
791 : * Deal with all special cases (i.e flags) regarding how results should be returned
792 : *
793 : * The special cases handled are these (in order of precedence):
794 : * - returnId (instead of the actual result, last_id is returned)
795 : * - single_value (only the first value is returned as a scalar)
796 : * - singleRow (the first row is returned as a an one-dimension array)
797 : *
798 : * Cell-specific handling is done elsewhere
799 : *
800 : * In the absence of special case, the whole result is returned as an array of arrays (by calling as_whole() )
801 : *
802 : * @deprecated
803 : * @version 1.1
804 : *
805 : * @date 20100610 (greg) (v1.0) added, based on Jason's work
806 : * @date 20100617 (jason) (v1.0.1) added support for "string" setting
807 : * @date 20100620 (greg) (v1.0.2) cleaned up using class methods
808 : * @date 20100708 (greg) (v1.1) clean up with definitive API
809 : *
810 : * @return usually an array, although can be false, or int for an ID
811 : */
812 : public function get_results()
813 : {
814 0 : return $this->getResults();
815 : }
816 :
817 : /**
818 : * Returns a single field from every line, resulting in an array of values (ie some kind of "vertical" fetching)
819 : *
820 : * Note: this is different from as_whole, since only ONE value is present in each line
821 : *
822 : * @deprecated
823 : * @since 20100216
824 : * @version 1.0
825 : * @author greg
826 : * @param $field string, the field to extract on each line
827 : * @return array, all the values
828 : */
829 : public function as_array($field)
830 : {
831 0 : return $this->asArray($field);
832 : }
833 :
834 : /**
835 : * Returns the asked line as an array
836 : *
837 : * You can either ask for the next line (no parameter) or given a row number in the result.
838 : *
839 : * Note: the row number is based on the result, it may not be same as the row number in the complete table
840 : *
841 : * @deprecated
842 : * @since 3.0
843 : * @version 1.0.1
844 : * @author greg
845 : *
846 : * @date 20100810 (v1.0.1) (greg) return null if the resultset is empty
847 :
848 : * @param integer $row_number (optional)
849 : * @return array| null, the line or null if the resultset is empty
850 : */
851 : public function as_line($row_number = null)
852 : {
853 0 : return $this->asLine($row_number);
854 : }
855 :
856 : /**
857 : * Return one value from the asked field of the asked line
858 : *
859 : * @deprecated
860 : * @since 3.0
861 : * @version 1.0.3
862 : * @author greg
863 : *
864 : * @date 20100620 (v1.0.1) (greg) made parameters optional (no "field" means first field)
865 : * @date 20100630 (v1.0.2) (greg) object's focus is used if "$field" parameter is empty
866 : * @date 20100810 (v1.0.3) (greg) return null if the resultset is empty
867 : *
868 : *
869 : * @param integer $row_number (optional)
870 : * @param string $field field name (optional)
871 : * @return string | null
872 : */
873 : public function as_one($row_number = null, $field = null)
874 : {
875 0 : return $this->asOne($row_number, $field);
876 : }
877 : //////////////////////////////////////////////////////////////////////////////
878 : //////////////////////////////////////////////////////////////////////////////
879 : //////////// END DEPRECATED NAMING CONVENTIONS ///////////////////////////////
880 : //////////////////////////////////////////////////////////////////////////////
881 : //////////////////////////////////////////////////////////////////////////////
882 : }
883 :
884 :
885 :
886 :
887 :
|