Packages

Source for file DibiResult.php

Documentation is available at DibiResult.php

1: <?php
2:
3: /**
4: * dibi - tiny'n'smart database abstraction layer
5: * ----------------------------------------------
6: *
7: * @copyright Copyright (c) 2005, 2010 David Grudl
8: * @license http://dibiphp.com/license dibi license
9: * @link http://dibiphp.com
10: * @package dibi
11: */
12:
13:
14:
15: /**
16: * dibi result set.
17: *
18: * <code>
19: * $result = dibi::query('SELECT * FROM [table]');
20: *
21: * $row = $result->fetch();
22: * $value = $result->fetchSingle();
23: * $table = $result->fetchAll();
24: * $pairs = $result->fetchPairs();
25: * $assoc = $result->fetchAssoc('id');
26: * $assoc = $result->fetchAssoc('active,#,id');
27: *
28: * unset($result);
29: * </code>
30: *
31: * @copyright Copyright (c) 2005, 2010 David Grudl
32: * @package dibi
33: *
34: * @property-read mixed $resource
35: * @property-read IDibiResultDriver $driver
36: * @property-read int $rowCount
37: * @property-read DibiResultIterator $iterator
38: * @property string $rowClass
39: * @property-read DibiResultInfo $info
40: */
41: class DibiResult extends DibiObject implements IDataSource
42: {
43: /** @var array IDibiResultDriver */
44: private $driver;
45:
46: /** @var array Translate table */
47: private $types;
48:
49: /** @var DibiResultInfo */
50: private $meta;
51:
52: /** @var bool Already fetched? Used for allowance for first seek(0) */
53: private $fetched = FALSE;
54:
55: /** @var string returned object class */
56: private $rowClass = 'DibiRow';
57:
58: /** @var string date-time format */
59: private $dateFormat = '';
60:
61:
62:
63: /**
64: * @param IDibiResultDriver
65: * @param array
66: */
67: public function __construct($driver, $config)
68: {
69: $this->driver = $driver;
70:
71: if (!empty($config['detectTypes'])) {
72: $this->detectTypes();
73: }
74:
75: if (!empty($config['formatDateTime'])) {
76: $this->dateFormat = is_string($config['formatDateTime']) ? $config['formatDateTime'] : '';
77: }
78: }
79:
80:
81:
82: /**
83: * Automatically frees the resources allocated for this result set.
84: * @return void
85: */
86: public function __destruct()
87: {
88: @$this->free(); // intentionally @
89: }
90:
91:
92:
93: /**
94: * Returns the result set resource.
95: * @return mixed
96: */
97: final public function getResource()
98: {
99: return $this->getDriver()->getResultResource();
100: }
101:
102:
103:
104: /**
105: * Frees the resources allocated for this result set.
106: * @return void
107: */
108: final public function free()
109: {
110: if ($this->driver !== NULL) {
111: $this->driver->free();
112: $this->driver = $this->meta = NULL;
113: }
114: }
115:
116:
117:
118: /**
119: * Safe access to property $driver.
120: * @return IDibiResultDriver
121: * @throws InvalidStateException
122: */
123: private function getDriver()
124: {
125: if ($this->driver === NULL) {
126: throw new InvalidStateException('Result-set was released from memory.');
127: }
128:
129: return $this->driver;
130: }
131:
132:
133:
134: /********************* rows ****************d*g**/
135:
136:
137:
138: /**
139: * Moves cursor position without fetching row.
140: * @param int the 0-based cursor pos to seek to
141: * @return boolean TRUE on success, FALSE if unable to seek to specified record
142: * @throws DibiException
143: */
144: final public function seek($row)
145: {
146: return ($row !== 0 || $this->fetched) ? (bool) $this->getDriver()->seek($row) : TRUE;
147: }
148:
149:
150:
151: /**
152: * Required by the Countable interface.
153: * @return int
154: */
155: final public function count()
156: {
157: return $this->getDriver()->getRowCount();
158: }
159:
160:
161:
162: /**
163: * Returns the number of rows in a result set.
164: * @return int
165: */
166: final public function getRowCount()
167: {
168: return $this->getDriver()->getRowCount();
169: }
170:
171:
172:
173: /**
174: * Returns the number of rows in a result set. Alias for getRowCount().
175: * @deprecated
176: */
177: final public function rowCount()
178: {
179: return $this->getDriver()->getRowCount();
180: }
181:
182:
183:
184: /**
185: * Required by the IteratorAggregate interface.
186: * @return DibiResultIterator
187: */
188: final public function getIterator()
189: {
190: if (func_num_args()) {
191: trigger_error(__METHOD__ . ' arguments $offset & $limit have been dropped; use SQL clauses instead.', E_USER_WARNING);
192: }
193: return new DibiResultIterator($this);
194: }
195:
196:
197:
198: /********************* fetching rows ****************d*g**/
199:
200:
201:
202: /**
203: * Set fetched object class. This class should extend the DibiRow class.
204: * @param string
205: * @return DibiResult provides a fluent interface
206: */
207: public function setRowClass($class)
208: {
209: $this->rowClass = $class;
210: return $this;
211: }
212:
213:
214:
215: /**
216: * Returns fetched object class name.
217: * @return string
218: */
219: public function getRowClass()
220: {
221: return $this->rowClass;
222: }
223:
224:
225:
226: /**
227: * Fetches the row at current position, process optional type conversion.
228: * and moves the internal cursor to the next position
229: * @return DibiRow|FALSE array on success, FALSE if no next record
230: */
231: final public function fetch()
232: {
233: $row = $this->getDriver()->fetch(TRUE);
234: if (!is_array($row)) return FALSE;
235:
236: $this->fetched = TRUE;
237:
238: // types-converting?
239: if ($this->types !== NULL) {
240: foreach ($this->types as $col => $type) {
241: if (isset($row[$col])) {
242: $row[$col] = $this->convert($row[$col], $type);
243: }
244: }
245: }
246:
247: return new $this->rowClass($row);
248: }
249:
250:
251:
252: /**
253: * Like fetch(), but returns only first field.
254: * @return mixed value on success, FALSE if no next record
255: */
256: final public function fetchSingle()
257: {
258: $row = $this->getDriver()->fetch(TRUE);
259: if (!is_array($row)) return FALSE;
260: $this->fetched = TRUE;
261: $value = reset($row);
262:
263: // types-converting?
264: $key = key($row);
265: if (isset($this->types[$key])) {
266: return $this->convert($value, $this->types[$key]);
267: }
268:
269: return $value;
270: }
271:
272:
273:
274: /**
275: * Fetches all records from table.
276: * @param int offset
277: * @param int limit
278: * @return array of DibiRow
279: */
280: final public function fetchAll($offset = NULL, $limit = NULL)
281: {
282: $limit = $limit === NULL ? -1 : (int) $limit;
283: $this->seek((int) $offset);
284: $row = $this->fetch();
285: if (!$row) return array(); // empty result set
286:
287: $data = array();
288: do {
289: if ($limit === 0) break;
290: $limit--;
291: $data[] = $row;
292: } while ($row = $this->fetch());
293:
294: return $data;
295: }
296:
297:
298:
299: /**
300: * Fetches all records from table and returns associative tree.
301: * Examples:
302: * - associative descriptor: col1[]col2->col3
303: * builds a tree: $tree[$val1][$index][$val2]->col3[$val3] = {record}
304: * - associative descriptor: col1|col2->col3=col4
305: * builds a tree: $tree[$val1][$val2]->col3[$val3] = val4
306: * @param string associative descriptor
307: * @return DibiRow
308: * @throws InvalidArgumentException
309: */
310: final public function fetchAssoc($assoc)
311: {
312: if (strpos($assoc, ',') !== FALSE) {
313: return $this->oldFetchAssoc($assoc);
314: }
315:
316: $this->seek(0);
317: $row = $this->fetch();
318: if (!$row) return array(); // empty result set
319:
320: $data = NULL;
321: $assoc = preg_split('#(\[\]|->|=|\|)#', $assoc, NULL, PREG_SPLIT_DELIM_CAPTURE | PREG_SPLIT_NO_EMPTY);
322:
323: // check columns
324: foreach ($assoc as $as) {
325: // offsetExists ignores NULL in PHP 5.2.1, isset() surprisingly NULL accepts
326: if ($as !== '[]' && $as !== '=' && $as !== '->' && $as !== '|' && !property_exists($row, $as)) {
327: throw new InvalidArgumentException("Unknown column '$as' in associative descriptor.");
328: }
329: }
330:
331: if ($as === '->') { // must not be last
332: array_pop($assoc);
333: }
334:
335: if (empty($assoc)) {
336: $assoc[] = '[]';
337: }
338:
339: // make associative tree
340: do {
341: $x = & $data;
342:
343: // iterative deepening
344: foreach ($assoc as $i => $as) {
345: if ($as === '[]') { // indexed-array node
346: $x = & $x[];
347:
348: } elseif ($as === '=') { // "value" node
349: $x = $row->{$assoc[$i+1]};
350: continue 2;
351:
352: } elseif ($as === '->') { // "object" node
353: if ($x === NULL) {
354: $x = clone $row;
355: $x = & $x->{$assoc[$i+1]};
356: $x = NULL; // prepare child node
357: } else {
358: $x = & $x->{$assoc[$i+1]};
359: }
360:
361: } elseif ($as !== '|') { // associative-array node
362: $x = & $x[$row->$as];
363: }
364: }
365:
366: if ($x === NULL) { // build leaf
367: $x = $row;
368: }
369:
370: } while ($row = $this->fetch());
371:
372: unset($x);
373: return $data;
374: }
375:
376:
377:
378: /**
379: * @deprecated
380: */
381: private function oldFetchAssoc($assoc)
382: {
383: $this->seek(0);
384: $row = $this->fetch();
385: if (!$row) return array(); // empty result set
386:
387: $data = NULL;
388: $assoc = explode(',', $assoc);
389:
390: // strip leading = and @
391: $leaf = '@'; // gap
392: $last = count($assoc) - 1;
393: while ($assoc[$last] === '=' || $assoc[$last] === '@') {
394: $leaf = $assoc[$last];
395: unset($assoc[$last]);
396: $last--;
397:
398: if ($last < 0) {
399: $assoc[] = '#';
400: break;
401: }
402: }
403:
404: do {
405: $x = & $data;
406:
407: foreach ($assoc as $i => $as) {
408: if ($as === '#') { // indexed-array node
409: $x = & $x[];
410:
411: } elseif ($as === '=') { // "record" node
412: if ($x === NULL) {
413: $x = $row->toArray();
414: $x = & $x[ $assoc[$i+1] ];
415: $x = NULL; // prepare child node
416: } else {
417: $x = & $x[ $assoc[$i+1] ];
418: }
419:
420: } elseif ($as === '@') { // "object" node
421: if ($x === NULL) {
422: $x = clone $row;
423: $x = & $x->{$assoc[$i+1]};
424: $x = NULL; // prepare child node
425: } else {
426: $x = & $x->{$assoc[$i+1]};
427: }
428:
429:
430: } else { // associative-array node
431: $x = & $x[$row->$as];
432: }
433: }
434:
435: if ($x === NULL) { // build leaf
436: if ($leaf === '=') {
437: $x = $row->toArray();
438: } else {
439: $x = $row;
440: }
441: }
442:
443: } while ($row = $this->fetch());
444:
445: unset($x);
446: return $data;
447: }
448:
449:
450:
451: /**
452: * Fetches all records from table like $key => $value pairs.
453: * @param string associative key
454: * @param string value
455: * @return array
456: * @throws InvalidArgumentException
457: */
458: final public function fetchPairs($key = NULL, $value = NULL)
459: {
460: $this->seek(0);
461: $row = $this->fetch();
462: if (!$row) return array(); // empty result set
463:
464: $data = array();
465:
466: if ($value === NULL) {
467: if ($key !== NULL) {
468: throw new InvalidArgumentException("Either none or both columns must be specified.");
469: }
470:
471: // autodetect
472: $tmp = array_keys($row->toArray());
473: $key = $tmp[0];
474: if (count($row) < 2) { // indexed-array
475: do {
476: $data[] = $row[$key];
477: } while ($row = $this->fetch());
478: return $data;
479: }
480:
481: $value = $tmp[1];
482:
483: } else {
484: if (!property_exists($row, $value)) {
485: throw new InvalidArgumentException("Unknown value column '$value'.");
486: }
487:
488: if ($key === NULL) { // indexed-array
489: do {
490: $data[] = $row[$value];
491: } while ($row = $this->fetch());
492: return $data;
493: }
494:
495: if (!property_exists($row, $key)) {
496: throw new InvalidArgumentException("Unknown key column '$key'.");
497: }
498: }
499:
500: do {
501: $data[ $row[$key] ] = $row[$value];
502: } while ($row = $this->fetch());
503:
504: return $data;
505: }
506:
507:
508:
509: /********************* meta info ****************d*g**/
510:
511:
512:
513: /**
514: * Define column type.
515: * @param string column
516: * @param string type (use constant Dibi::*)
517: * @return DibiResult provides a fluent interface
518: */
519: final public function setType($col, $type)
520: {
521: $this->types[$col] = $type;
522: return $this;
523: }
524:
525:
526:
527: /**
528: * Autodetect column types.
529: * @return void
530: */
531: final public function detectTypes()
532: {
533: foreach ($this->getInfo()->getColumns() as $col) {
534: $this->types[$col->getName()] = $col->getType();
535: }
536: }
537:
538:
539:
540: /**
541: * Define multiple columns types.
542: * @param array
543: * @return DibiResult provides a fluent interface
544: * @ignore internal
545: */
546: final public function setTypes(array $types)
547: {
548: $this->types = $types;
549: return $this;
550: }
551:
552:
553:
554: /**
540: /**
541: * Returns column type.
542: * @return string
557: */
558: final public function getType($col)
559: {
560: return isset($this->types[$col]) ? $this->types[$col] : NULL;
561: }
562:
563:
564:
565: /**
566: * Converts value to specified type and format.
567: * @param mixed value
568: * @param int type
569: * @return mixed
570: */
571: protected function convert($value, $type)
572: {
573: if ($value === NULL || $value === FALSE) {
574: return NULL;
575: }
576:
577: switch ($type) {
578: case dibi::TEXT:
579: return (string) $value;
580:
581: case dibi::BINARY:
582: return $this->getDriver()->unescape($value, $type);
583:
584: case dibi::INTEGER:
585: return (int) $value;
586:
587: case dibi::FLOAT:
588: return (float) $value;
589:
590: case dibi::DATE:
591: case dibi::DATETIME:
592: if ((int) $value === 0) { // '', NULL, FALSE, '0000-00-00', ...
593: return NULL;
594:
595: } elseif ($this->dateFormat === '') { // return DateTime object (default)
596: return new DateTime53(is_numeric($value) ? date('Y-m-d H:i:s', $value) : $value);
597:
598: } elseif ($this->dateFormat === 'U') { // return timestamp
599: return is_numeric($value) ? (int) $value : strtotime($value);
600:
601: } elseif (is_numeric($value)) { // formatted date
602: return date($this->dateFormat, $value);
603:
604: } else {
605: $value = new DateTime53($value);
606: return $value->format($this->dateFormat);
607: }
608:
609: case dibi::BOOL:
610: return ((bool) $value) && $value !== 'f' && $value !== 'F';
611:
612: default:
613: return $value;
614: }
615: }
616:
617:
618:
619: /**
620: * Returns a meta information about the current result set.
621: * @return DibiResultInfo
622: */
623: public function getInfo()
624: {
625: if ($this->meta === NULL) {
626: $this->meta = new DibiResultInfo($this->getDriver());
627: }
628: return $this->meta;
629: }
630:
631:
632:
633: /**
634: * @deprecated
635: */
636: final public function getColumns()
637: {
638: return $this->getInfo()->getColumns();
639: }
640:
641:
642:
643: /**
644: * @deprecated
645: */
646: public function getColumnNames($fullNames = FALSE)
647: {
648: return $this->getInfo()->getColumnNames($fullNames);
649: }
650:
651:
652:
653: /********************* misc tools ****************d*g**/
654:
655:
656:
657: /**
658: * Displays complete result set as HTML table for debug purposes.
659: * @return void
660: */
661: final public function dump()
662: {
663: $i = 0;
664: $this->seek(0);
665: while ($row = $this->fetch()) {
666: if ($i === 0) {
667: echo "\n<table class=\"dump\">\n<thead>\n\t<tr>\n\t\t<th>#row</th>\n";
668:
669: foreach ($row as $col => $foo) {
670: echo "\t\t<th>" . htmlSpecialChars($col) . "</th>\n";
671: }
672:
673: echo "\t</tr>\n</thead>\n<tbody>\n";
674: }
675:
676: echo "\t<tr>\n\t\t<th>", $i, "</th>\n";
677: foreach ($row as $col) {
678: //if (is_object($col)) $col = $col->__toString();
679: echo "\t\t<td>", htmlSpecialChars($col), "</td>\n";
680: }
681: echo "\t</tr>\n";
682: $i++;
683: }
684:
685: if ($i === 0) {
686: echo '<p><em>empty result set</em></p>';
687: } else {
688: echo "</tbody>\n</table>\n";
689: }
690: }
691:
692: }

dibi API documentation

Packages

Source for file DibiResult.php