Untitled

'; + * $sql = 'SELECT * FROM qpdb_test'; + * $args = array(); + * $qp = qp(QueryPath::HTML_STUB, 'body') + * ->append('

') // Add a new

+ * ->children() // Select the

+ * ->dbInit($this->dsn) // Initialize the DB + * // BIG LINE: Query the results, run them through the template, and insert them. + * ->queryInto($sql, $args, $template) + * ->doneWithQuery() + * ->writeHTML(); // Write the results as HTML. + * ?> + * @endcode + * + * The simple code above puts the first column of the select statement + * into an unordered list. The example output looks like this: + * + * @code + * + * + * + * + * Untitled + * + * + *

Title 0
Title 1
Title 2
Title 3
Title 4

+ * + * + * @endcode + * + * Typical starting methods for this class are {@link QPDB::baseDB()}, + * {@link QPDB::query()}, and {@link QPDB::queryInto()}. + * + * @ingroup querypath_extensions + */ +class QPDB implements QueryPathExtension { + protected $qp; + protected $dsn; + protected $db; + protected $opts; + protected $row = NULL; + protected $stmt = NULL; + + protected static $con = NULL; + + /** + * Create a new database instance for all QueryPath objects to share. + * + * This method need be called only once. From there, other QPDB instances + * will (by default) share the same database instance. + * + * Normally, a DSN should be passed in. Username, password, and db params + * are all passed in using the options array. + * + * On rare occasions, it may be more fitting to pass in an existing database + * connection (which must be a {@link PDO} object). In such cases, the $dsn + * parameter can take a PDO object instead of a DSN string. The standard options + * will be ignored, though. + * + * Warning: If you pass in a PDO object that is configured to NOT throw + * exceptions, you will need to handle error checking differently. + * + * Remember to always use {@link QPDB::doneWithQuery()} when you are done + * with a query. It gives PDO a chance to clean up open connections that may + * prevent other instances from accessing or modifying data. + * + * @param string $dsn + * The DSN of the database to connect to. You can also pass in a PDO object, which + * will set the QPDB object's database to the one passed in. + * @param array $options + * An array of configuration options. The following options are currently supported: + * - username => (string) + * - password => (string) + * - db params => (array) These will be passed into the new PDO object. + * See the PDO documentation for a list of options. By default, the + * only flag set is {@link PDO::ATTR_ERRMODE}, which is set to + * {@link PDO::ERRMODE_EXCEPTION}. + * @throws PDOException + * An exception may be thrown if the connection cannot be made. + */ + static function baseDB($dsn, $options = array()) { + + $opts = $options + array( + 'username' => NULL, + 'password' => NULL, + 'db params' => array(PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION), + ); + + // Allow this to handle the case where an outside + // connection does the initialization. + if ($dsn instanceof PDO) { + self::$con = $dsn; + return; + } + self::$con = new PDO($dsn, $opts['username'], $opts['password'], $opts['db params']); + } + + /** + * + * This method may be used to share the connection with other, + * non-QueryPath objects. + */ + static function getBaseDB() {return self::$con;} + + /** + * Used to control whether or not all rows in a result should be cycled through. + */ + protected $cycleRows = FALSE; + + /** + * Construct a new QPDB object. This is usually done by QueryPath itself. + */ + public function __construct(QueryPath $qp) { + $this->qp = $qp; + // By default, we set it up to use the base DB. + $this->db = self::$con; + } + + /** + * Create a new connection to the database. Use the PDO DSN syntax for a + * connection string. + * + * This creates a database connection that will last for the duration of + * the QueryPath object. This method ought to be used only in two cases: + * - When you will only run a couple of queries during the life of the + * process. + * - When you need to connect to a database that will only be used for + * a few things. + * Otherwise, you should use {@link QPDB::baseDB} to configure a single + * database connection that all of {@link QueryPath} can share. + * + * Remember to always use {@link QPDB::doneWithQuery()} when you are done + * with a query. It gives PDO a chance to clean up open connections that may + * prevent other instances from accessing or modifying data. + * + * @param string $dsn + * The PDO DSN connection string. + * @param array $options + * Connection options. The following options are supported: + * - username => (string) + * - password => (string) + * - db params => (array) These will be passed into the new PDO object. + * See the PDO documentation for a list of options. By default, the + * only flag set is {@link PDO::ATTR_ERRMODE}, which is set to + * {@link PDO::ERRMODE_EXCEPTION}. + * @return QueryPath + * The QueryPath object. + * @throws PDOException + * The PDO library is configured to throw exceptions, so any of the + * database functions may throw a PDOException. + */ + public function dbInit($dsn, $options = array()) { + $this->opts = $options + array( + 'username' => NULL, + 'password' => NULL, + 'db params' => array(PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION), + ); + $this->dsn = $dsn; + $this->db = new PDO($dsn, $this->opts['username'], $this->opts['password'], $this->opts['db params']); + /* + foreach ($this->opts['db params'] as $key => $val) + $this->db->setAttribute($key, $val); + */ + + return $this->qp; + } + + /** + * Execute a SQL query, and store the results. + * + * This will execute a SQL query (as a prepared statement), and then store + * the results internally for later use. The data can be iterated using + * {@link nextRow()}. QueryPath can also be instructed to do internal iteration + * using the {@link withEachRow()} method. Finally, on the occasion that the + * statement itself is needed, {@link getStatement()} can be used. + * + * Use this when you need to access the results of a query, or when the + * parameter to a query should be escaped. If the query takes no external + * parameters and does not return results, you may wish to use the + * (ever so slightly faster) {@link exec()} function instead. + * + * Make sure you use {@link doneWithQuery()} after finishing with the database + * results returned by this method. + * + * Usage + * + * Here is a simple example: + *


+   *  'myColumn');
+   * qp()->query('SELECT :something FROM foo', $args)->doneWithQuery();
+   * ?>
+   *

'; + + $qp = qp($base, 'table')->addClass($opts['table class'])->find('tr'); + if ($items instanceof TableAble) { + $headers = $items->getHeaders(); + $rows = $items->getRows(); + } + elseif ($items instanceof Traversable) { + $headers = array(); + $rows = $items; + } + else { + $headers = $items['headers']; + $rows = $items['rows']; + } + + // Add Headers: + foreach ($headers as $header) { + $qp->append('' . $header . ''); + } + $qp->top()->find('tr:last'); + + // Add rows and cells. + foreach ($rows as $row) { + $qp->after('')->next(); + foreach($row as $cell) $qp->append('' . $cell . ''); + } + + $this->qp->append($qp->top()); + + return $this->qp; + } + + /** + * Append a list of items into an HTML DOM using one of the HTML list structures. + * This takes a one-dimensional array and converts it into an HTML UL or OL list, + * or it can take an associative array and convert that into a DL list. + * + * In addition to arrays, this works with any Traversable or Iterator object. + * + * OL/UL arrays can be nested. + * + * @param mixed $items + * An indexed array for UL and OL, or an associative array for DL. Iterator and + * Traversable objects can also be used. + * @param string $type + * One of ul, ol, or dl. Predefined constants are available for use. + * @param array $options + * An associative array of configuration options. The supported options are: + * - 'list class': The class that will be assigned to a list. + */ + public function appendList($items, $type = self::UL, $options = array()) { + $opts = $options + array( + 'list class' => 'qplist', + ); + if ($type == self::DL) { + $q = qp('

', 'dl')->addClass($opts['list class']); + foreach ($items as $dt => $dd) { + $q->append('

' . $dt . '

' . $dd . '

'); + } + $q->appendTo($this->qp); + } + else { + $q = $this->listImpl($items, $type, $opts); + $this->qp->append($q->find(':root')); + } + + return $this->qp; + } + + /** + * Internal recursive list generator for appendList. + */ + protected function listImpl($items, $type, $opts, $q = NULL) { + $ele = '<' . $type . '/>'; + if (!isset($q)) + $q = qp()->append($ele)->addClass($opts['list class']); + + foreach ($items as $li) { + if ($li instanceof QueryPath) { + $q = $this->listImpl($li->get(), $type, $opts, $q); + } + elseif (is_array($li) || $li instanceof Traversable) { + $q->append('

Title 0	Body 0	Footer 0
Title 1	Body 1	Footer 1
Title 2	Body 2	Footer 2
Title 3	Body 3	Footer 3
Title 4	Body 4	Footer 4

+ * ->children() // Select the

Title 0

Title