Packages

Source for file DibiConnection.php

Documentation is available at DibiConnection.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 connection.
17: *
18: * @copyright Copyright (c) 2005, 2010 David Grudl
19: * @package dibi
20: *
21: * @property-read bool $connected
22: * @property-read mixed $config
23: * @property-read IDibiDriver $driver
24: * @property-read int $affectedRows
25: * @property-read int $insertId
26: * @property IDibiProfiler $profiler
27: * @property-read DibiDatabaseInfo $databaseInfo
28: */
29: class DibiConnection extends DibiObject
30: {
31: /** @var array Current connection configuration */
32: private $config;
33:
34: /** @var IDibiDriver */
35: private $driver;
36:
37: /** @var DibiTranslator */
38: private $translator;
39:
40: /** @var IDibiProfiler */
41: private $profiler;
42:
43: /** @var bool Is connected? */
44: private $connected = FALSE;
45:
46:
47:
48: /**
49: * Connection options: (see driver-specific options too)
50: * - lazy (bool) => if TRUE, connection will be established only when required
51: * - result (array) => result set options
52: * - detectTypes (bool) => detect the types of result set fields?
53: * - formatDateTime => date-time format (if empty, DateTime objects will be returned)
54: * - profiler (array or bool)
55: * - run (bool) => enable profiler?
56: * - class => profiler class name (default is DibiProfiler)
57: * - substitutes (array) => map of driver specific substitutes (under development)
58:
59: * @param mixed connection parameters
60: * @param string connection name
61: * @throws DibiException
62: */
63: public function __construct($config, $name = NULL)
64: {
65: // DSN string
66: if (is_string($config)) {
67: parse_str($config, $config);
68:
69: } elseif ($config instanceof Traversable) {
70: $tmp = array();
71: foreach ($config as $key => $val) {
72: $tmp[$key] = $val instanceof Traversable ? iterator_to_array($val) : $val;
73: }
74: $config = $tmp;
75:
76: } elseif (!is_array($config)) {
77: throw new InvalidArgumentException('Configuration must be array, string or object.');
78: }
79:
80: self::alias($config, 'username', 'user');
81: self::alias($config, 'password', 'pass');
82: self::alias($config, 'host', 'hostname');
83: self::alias($config, 'result|detectTypes', 'resultDetectTypes'); // back compatibility
84: self::alias($config, 'result|formatDateTime', 'resultDateTime');
85:
86: if (!isset($config['driver'])) {
87: $config['driver'] = dibi::$defaultDriver;
88: }
89:
90: $driver = preg_replace('#[^a-z0-9_]#', '_', strtolower($config['driver']));
91: $class = "Dibi" . $driver . "Driver";
92: if (!class_exists($class, FALSE)) {
93: include_once dirname(__FILE__) . "/../drivers/$driver.php";
94:
95: if (!class_exists($class, FALSE)) {
96: throw new DibiException("Unable to create instance of dibi driver '$class'.");
97: }
98: }
99:
100: $config['name'] = $name;
101: $this->config = $config;
102: $this->driver = new $class;
103: $this->translator = new DibiTranslator($this->driver);
104:
105: // profiler
106: $profilerCfg = & $config['profiler'];
107: if (is_scalar($profilerCfg)) { // back compatibility
108: $profilerCfg = array(
109: 'run' => (bool) $profilerCfg,
110: 'class' => strlen($profilerCfg) > 1 ? $profilerCfg : NULL,
111: );
112: }
113:
114: if (!empty($profilerCfg['run'])) {
115: $class = isset($profilerCfg['class']) ? $profilerCfg['class'] : 'DibiProfiler';
116: if (!class_exists($class)) {
117: throw new DibiException("Unable to create instance of dibi profiler '$class'.");
118: }
119: $this->setProfiler(new $class($profilerCfg));
120: }
121:
122: if (!empty($config['substitutes'])) {
123: foreach ($config['substitutes'] as $key => $value) {
124: dibi::addSubst($key, $value);
125: }
126: }
127:
128: if (empty($config['lazy'])) {
129: $this->connect();
130: }
131: }
132:
133:
134:
135: /**
136: * Automatically frees the resources allocated for this result set.
137: * @return void
138: */
139: public function __destruct()
140: {
141: // disconnects and rolls back transaction - do not rely on auto-disconnect and rollback!
142: $this->connected && $this->disconnect();
143: }
144:
145:
146:
147: /**
148: * Connects to a database.
149: * @return void
150: */
151: final public function connect()
152: {
153: if ($this->profiler !== NULL) {
154: $ticket = $this->profiler->before($this, IDibiProfiler::CONNECT);
155: }
156: $this->driver->connect($this->config);
157: $this->connected = TRUE;
158: if (isset($ticket)) {
159: $this->profiler->after($ticket);
160: }
161: }
162:
163:
164:
165: /**
166: * Disconnects from a database.
167: * @return void
168: */
169: final public function disconnect()
170: {
171: $this->driver->disconnect();
172: $this->connected = FALSE;
173: }
174:
175:
176:
177: /**
178: * Returns TRUE when connection was established.
179: * @return bool
180: */
181: final public function isConnected()
182: {
183: return $this->connected;
184: }
185:
186:
187:
188: /**
189: * Returns configuration variable. If no $key is passed, returns the entire array.
190: * @see self::__construct
191: * @param string
192: * @param mixed default value to use if key not found
193: * @return mixed
194: */
195: final public function getConfig($key = NULL, $default = NULL)
196: {
197: if ($key === NULL) {
198: return $this->config;
199:
200: } elseif (isset($this->config[$key])) {
201: return $this->config[$key];
202:
203: } else {
204: return $default;
205: }
206: }
207:
208:
209:
210: /**
211: * Apply configuration alias or default values.
212: * @param array connect configuration
213: * @param string key
214: * @param string alias key
215: * @return void
216: */
217: public static function alias(&$config, $key, $alias)
218: {
219: $foo = & $config;
220: foreach (explode('|', $key) as $key) $foo = & $foo[$key];
221:
222: if (!isset($foo) && isset($config[$alias])) {
223: $foo = $config[$alias];
224: unset($config[$alias]);
225: }
226: }
227:
228:
229:
230: /**
231: * Returns the driver and connects to a database in lazy mode.
232: * @return IDibiDriver
233: */
234: final public function getDriver()
235: {
236: $this->connected || $this->connect();
237: return $this->driver;
238: }
239:
240:
241:
242: /**
243: * Generates (translates) and executes SQL query.
244: * @param array|mixed one or more arguments
245: * @return DibiResult|int result set object (if any)
246: * @throws DibiException
247: */
248: final public function query($args)
249: {
250: $this->connected || $this->connect();
251: $args = func_get_args();
252: return $this->nativeQuery($this->translator->translate($args));
253: }
254:
255:
256:
257: /**
258: * Generates and returns SQL query.
259: * @param array|mixed one or more arguments
260: * @return string
261: * @throws DibiException
262: */
263: final public function translate($args)
264: {
265: $this->connected || $this->connect();
266: $args = func_get_args();
267: return $this->translator->translate($args);
268: }
269:
270:
271:
272: /** @deprecated */
273: function sql($args)
274: {
275: trigger_error(__METHOD__ . '() is deprecated; use translate() instead.', E_USER_NOTICE);
276: $this->connected || $this->connect();
277: $args = func_get_args();
278: return $this->translator->translate($args);
279: }
280:
281:
282:
283: /**
284: * Generates and prints SQL query.
285: * @param array|mixed one or more arguments
286: * @return bool
287: */
288: final public function test($args)
289: {
290: $this->connected || $this->connect();
291: $args = func_get_args();
292: try {
293: dibi::dump($this->translator->translate($args));
294: return TRUE;
295:
296: } catch (DibiException $e) {
297: dibi::dump($e->getSql());
298: return FALSE;
299: }
300: }
301:
302:
303:
304: /**
305: * Generates (translates) and returns SQL query as DibiDataSource.
306: * @param array|mixed one or more arguments
307: * @return DibiDataSource
308: * @throws DibiException
309: */
310: final public function dataSource($args)
311: {
312: $this->connected || $this->connect();
313: $args = func_get_args();
314: return new DibiDataSource($this->translator->translate($args), $this);
315: }
316:
317:
318:
319: /**
320: * Executes the SQL query.
321: * @param string SQL statement.
322: * @return DibiResult|int result set object (if any)
323: * @throws DibiException
324: */
325: final public function nativeQuery($sql)
326: {
327: $this->connected || $this->connect();
328:
329: if ($this->profiler !== NULL) {
330: $event = IDibiProfiler::QUERY;
331: if (preg_match('#\s*(SELECT|UPDATE|INSERT|DELETE)#i', $sql, $matches)) {
332: static $events = array(
333: 'SELECT' => IDibiProfiler::SELECT, 'UPDATE' => IDibiProfiler::UPDATE,
334: 'INSERT' => IDibiProfiler::INSERT, 'DELETE' => IDibiProfiler::DELETE,
335: );
336: $event = $events[strtoupper($matches[1])];
337: }
338: $ticket = $this->profiler->before($this, $event, $sql);
339: }
340:
341: dibi::$sql = $sql;
342: if ($res = $this->driver->query($sql)) { // intentionally =
343: $res = new DibiResult($res, $this->config['result']);
344: } else {
345: $res = $this->driver->getAffectedRows();
346: }
347:
348: if (isset($ticket)) {
349: $this->profiler->after($ticket, $res);
350: }
351: return $res;
352: }
353:
354:
355:
356: /**
357: * Gets the number of affected rows by the last INSERT, UPDATE or DELETE query.
358: * @return int number of rows
359: * @throws DibiException
360: */
361: public function getAffectedRows()
362: {
363: $this->connected || $this->connect();
364: $rows = $this->driver->getAffectedRows();
365: if (!is_int($rows) || $rows < 0) throw new DibiException('Cannot retrieve number of affected rows.');
366: return $rows;
367: }
368:
369:
370:
371: /**
372: * Gets the number of affected rows. Alias for getAffectedRows().
373: * @return int number of rows
374: * @throws DibiException
375: */
376: public function affectedRows()
377: {
378: return $this->getAffectedRows();
379: }
380:
381:
382:
383: /**
384: * Retrieves the ID generated for an AUTO_INCREMENT column by the previous INSERT query.
385: * @param string optional sequence name
386: * @return int
387: * @throws DibiException
388: */
389: public function getInsertId($sequence = NULL)
390: {
391: $this->connected || $this->connect();
392: $id = $this->driver->getInsertId($sequence);
393: if ($id < 1) throw new DibiException('Cannot retrieve last generated ID.');
394: return (int) $id;
395: }
396:
397:
398:
399: /**
400: * Retrieves the ID generated for an AUTO_INCREMENT column. Alias for getInsertId().
401: * @param string optional sequence name
402: * @return int
403: * @throws DibiException
404: */
405: public function insertId($sequence = NULL)
406: {
407: return $this->getInsertId($sequence);
408: }
409:
410:
411:
412: /**
413: * Begins a transaction (if supported).
414: * @param string optional savepoint name
415: * @return void
416: */
417: public function begin($savepoint = NULL)
418: {
419: $this->connected || $this->connect();
420: if ($this->profiler !== NULL) {
421: $ticket = $this->profiler->before($this, IDibiProfiler::BEGIN, $savepoint);
422: }
423: $this->driver->begin($savepoint);
424: if (isset($ticket)) {
425: $this->profiler->after($ticket);
426: }
427: }
428:
429:
430:
431: /**
432: * Commits statements in a transaction.
433: * @param string optional savepoint name
434: * @return void
435: */
436: public function commit($savepoint = NULL)
437: {
438: $this->connected || $this->connect();
439: if ($this->profiler !== NULL) {
440: $ticket = $this->profiler->before($this, IDibiProfiler::COMMIT, $savepoint);
441: }
442: $this->driver->commit($savepoint);
443: if (isset($ticket)) {
444: $this->profiler->after($ticket);
445: }
446: }
447:
448:
449:
450: /**
451: * Rollback changes in a transaction.
452: * @param string optional savepoint name
453: * @return void
454: */
455: public function rollback($savepoint = NULL)
456: {
457: $this->connected || $this->connect();
458: if ($this->profiler !== NULL) {
459: $ticket = $this->profiler->before($this, IDibiProfiler::ROLLBACK, $savepoint);
460: }
461: $this->driver->rollback($savepoint);
462: if (isset($ticket)) {
463: $this->profiler->after($ticket);
464: }
465: }
466:
467:
468:
469: /********************* fluent SQL builders ****************d*g**/
470:
471:
472:
473: /**
474: * @return DibiFluent
475: */
476: public function command()
477: {
478: return new DibiFluent($this);
479: }
480:
481:
482:
483: /**
484: * @param string column name
485: * @return DibiFluent
486: */
487: public function select($args)
488: {
489: $args = func_get_args();
490: return $this->command()->__call('select', $args);
491: }
492:
493:
494:
495: /**
496: * @param string table
497: * @param array
498: * @return DibiFluent
499: */
500: public function update($table, $args)
501: {
502: if (!(is_array($args) || $args instanceof Traversable)) {
503: throw new InvalidArgumentException('Arguments must be array or Traversable.');
504: }
505: return $this->command()->update('%n', $table)->set($args);
506: }
507:
508:
509:
510: /**
511: * @param string table
512: * @param array
513: * @return DibiFluent
514: */
515: public function insert($table, $args)
516: {
517: if ($args instanceof Traversable) {
518: $args = iterator_to_array($args);
519: } elseif (!is_array($args)) {
520: throw new InvalidArgumentException('Arguments must be array or Traversable.');
521: }
522: return $this->command()->insert()
523: ->into('%n', $table, '(%n)', array_keys($args))->values('%l', $args);
524: }
525:
526:
527:
528: /**
529: * @param string table
530: * @return DibiFluent
531: */
532: public function delete($table)
533: {
534: return $this->command()->delete()->from('%n', $table);
535: }
536:
537:
538:
539: /********************* profiler ****************d*g**/
540:
541:
542:
543: /**
544: * @param IDibiProfiler
545: * @return DibiConnection provides a fluent interface
546: */
547: public function setProfiler(IDibiProfiler $profiler = NULL)
548: {
549: $this->profiler = $profiler;
550: return $this;
551: }
552:
553:
554:
555: /**
556: * @return IDibiProfiler
557: */
558: public function getProfiler()
559: {
560: return $this->profiler;
561: }
562:
563:
564:
565: /********************* shortcuts ****************d*g**/
566:
567:
568:
569: /**
570: * Executes SQL query and fetch result - shortcut for query() & fetch().
571: * @param array|mixed one or more arguments
572: * @return DibiRow
573: * @throws DibiException
574: */
575: public function fetch($args)
576: {
577: $args = func_get_args();
578: return $this->query($args)->fetch();
579: }
580:
581:
582:
583: /**
584: * Executes SQL query and fetch results - shortcut for query() & fetchAll().
585: * @param array|mixed one or more arguments
586: * @return array of DibiRow
587: * @throws DibiException
588: */
589: public function fetchAll($args)
590: {
591: $args = func_get_args();
592: return $this->query($args)->fetchAll();
593: }
594:
595:
596:
597: /**
598: * Executes SQL query and fetch first column - shortcut for query() & fetchSingle().
599: * @param array|mixed one or more arguments
600: * @return string
601: * @throws DibiException
602: */
603: public function fetchSingle($args)
604: {
605: $args = func_get_args();
606: return $this->query($args)->fetchSingle();
607: }
608:
609:
610:
611: /**
612: * Executes SQL query and fetch pairs - shortcut for query() & fetchPairs().
613: * @param array|mixed one or more arguments
614: * @return string
615: * @throws DibiException
616: */
617: public function fetchPairs($args)
618: {
619: $args = func_get_args();
620: return $this->query($args)->fetchPairs();
621: }
622:
623:
624:
625: /********************* misc ****************d*g**/
626:
627:
628:
629: /**
630: * Import SQL dump from file - extreme fast!
631: * @param string filename
632: * @return int count of sql commands
633: */
634: public function loadFile($file)
635: {
636: $this->connected || $this->connect();
637: @set_time_limit(0); // intentionally @
638:
639: $handle = @fopen($file, 'r'); // intentionally @
640: if (!$handle) {
641: throw new FileNotFoundException("Cannot open file '$file'.");
642: }
643:
644: $count = 0;
645: $sql = '';
646: while (!feof($handle)) {
647: $s = fgets($handle);
648: $sql .= $s;
649: if (substr(rtrim($s), -1) === ';') {
650: $this->driver->query($sql);
651: $sql = '';
652: $count++;
653: }
654: }
655: fclose($handle);
656: return $count;
657: }
658:
659:
660:
661: /**
662: * Gets a information about the current database.
663: * @return DibiDatabaseInfo
664: */
665: public function getDatabaseInfo()
666: {
667: $this->connected || $this->connect();
668: return new DibiDatabaseInfo($this->driver->getReflector(), isset($this->config['database']) ? $this->config['database'] : NULL);
669: }
670:
671:
672:
673: /**
674: * Prevents unserialization.
675: */
676: public function __wakeup()
677: {
678: throw new NotSupportedException('You cannot serialize or unserialize ' . $this->getClass() . ' instances.');
679: }
680:
681:
682:
683: /**
684: * Prevents serialization.
685: */
686: public function __sleep()
687: {
688: throw new NotSupportedException('You cannot serialize or unserialize ' . $this->getClass() . ' instances.');
689: }
690:
691: }

dibi API documentation

Packages

Source for file DibiConnection.php