Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Initial docs

  • Loading branch information...
commit ec1e927bcdec38b010b4c9f5f3da3827d6ab2272 1 parent f000f82
Ralph Schindler ralphschindler authored
289 documentation/manual/en/module_specs/Zend_Db-Adapter.xml
... ... @@ -0,0 +1,289 @@
  1 +<?xml version="1.0" encoding="utf-8"?>
  2 +<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="zend.db.adapter"><info><title>Zend\Db\Adapter</title></info>
  3 +
  4 + <para>
  5 + The Adapter object is the most important sub-component of Zend\Db.
  6 + It is responsible for adapting any code written in or for Zend\Db
  7 + to the targeted php extensions and vendor databases. In doing this,
  8 + it creates an abstraction layer for the PHP extensions, which is called
  9 + the "Driver" portion of the Zend\Db adapter. It also creates a lightweight
  10 + abstraction layer for the various idiosyncrasies that each vendor specific
  11 + platform might have in it's SQL/RDBMS implementation which is called the
  12 + "Platform" portion of the adapter.
  13 + </para>
  14 +
  15 + <section xml:id="zend.db.adapter.quickstart"><info><title>Creating an Adapter (Quickstart)</title></info>
  16 +
  17 + <para>
  18 + Creating an adapter can simply be done by instantiating the
  19 + Zend\Db\Adapter\Adapter class. The most common use case, while not the
  20 + most explicit, is to pass an array of information to the Adapter.
  21 + </para>
  22 +
  23 + <programlisting language="php"><![CDATA[
  24 + $adapter = new Zend\Db\Adapter\Adapter($driverArray);
  25 +]]></programlisting>
  26 +
  27 + <para>
  28 + This driver array is an abstraction for the extension level required
  29 + parameters. Here is a table for the
  30 + </para>
  31 +
  32 + <para>
  33 + driver required Mysqli, Sqlsrv, Pdo_Sqlite, Pdo_Mysql, Pdo-OtherPdoDriver
  34 + database generally required the name of the database (schema)
  35 + username generally required the connection username
  36 + password generally required the connection password
  37 + hostname not generally requried the ip address or hostname to connect to
  38 + port not generally required the port to connect to (if applicable)
  39 + characterset not generally required the character set to use
  40 + others*
  41 + </para>
  42 +
  43 + <para>
  44 + * other names will work as well. Effectively, if the PHP manual
  45 + uses a particular naming, this naming will be supported by our Driver.
  46 + For example, dbname in most cases will also work for 'database'. Another
  47 + example is that in the case of Sqlsrv, UID will work in place of username.
  48 + Which format you chose is up to you, but the above table represents the
  49 + offical abstraction names.
  50 + </para>
  51 +
  52 + <para>
  53 + So, for example, a MySQL connection using ext/mysqli:
  54 + </para>
  55 +
  56 + <programlisting language="php"><![CDATA[
  57 + $adapter = new Zend\Db\Adapter\Adapter(array(
  58 + 'driver' => 'Mysqli',
  59 + 'database' => 'zend_db_example',
  60 + 'username' => 'developer',
  61 + 'password' => 'developer-password'
  62 + ));
  63 +]]></programlisting>
  64 +
  65 + <para>
  66 + Another example, of a Sqlite connection via PDO:
  67 + </para>
  68 +
  69 + <programlisting language="php"><![CDATA[
  70 + $adapter = new Zend\Db\Adapter\Adapter(array(
  71 + 'driver' => 'Pdo_Sqlite',
  72 + 'database' => 'path/to/sqlite.db'
  73 + ));
  74 +]]></programlisting>
  75 +
  76 + <para>
  77 + It is important to know that by using this style of adapter creation, the Adapter
  78 + will attempt to create any dependencies that were not explicitly provided. A Driver
  79 + object will be created from the contents of the $driver array provided in the
  80 + constructor. A Platform object will be created based off the type of Driver object
  81 + that was instantiated. And lastly, a default ResultSet object is created and utilized.
  82 + Any of these objects can be injected, to do this, see the next section.
  83 + </para>
  84 +
  85 +
  86 + </section>
  87 +
  88 + <section xml:id="zend.db.adapter.instantiating"><info><title>Creating an Adapter (By Injecting Dependencies)</title></info>
  89 +
  90 + <para>
  91 + The more expressive and explicit way of creating an adapter is by injecting all your
  92 + dependencies up front. Zend\Db\Adapter\Adapter uses constructor injection, and all
  93 + required dependencies are injected through the constructor, which has the following
  94 + signature (in pseudo-code):
  95 + </para>
  96 +
  97 +
  98 + <programlisting language="php"><![CDATA[
  99 + use Zend\Db\Adapter\Platform\PlatformInterface,
  100 + Zend\Db\ResultSet\ResultSet;
  101 +
  102 + class Zend\Db\Adapter\Adapter {
  103 + public function __construct($driver, PlatformInterface $platform = null, ResultSet $queryResultSetPrototype = null)
  104 + }
  105 +]]></programlisting>
  106 +
  107 + <para>
  108 + What can be injected:
  109 + </para>
  110 +
  111 + <para>
  112 + $driver - an array or an instance of Zend\Db\Adapter\Driver\DriverInterface
  113 + $platform - (optional) an instance of Zend\Db\Platform\PlatformInterface, the default will be created based off the driver implementation
  114 + $queryResultSetPrototype - (optional) an instance of Zend\Db\ResultSet\ResultSet, to understand this object's role, see the section below on querying through the adapter
  115 + </para>
  116 +
  117 + </section>
  118 +
  119 + <section xml:id="zend.db.adapter.query-preparing"><info><title>Query Preparation Through Zend\Db\Adapter\Adapter::query()</title></info>
  120 +
  121 + <para>
  122 + By default, query() prefers that you use "preparation" as a means for processing SQL
  123 + statements. This generally means that you will supply a SQL statement with the values
  124 + substituted by placeholders, and then the parameters for those placeholders are
  125 + supplied separately. An example of this workflow with Zend\Db\Adapter\Adapter is:
  126 + </para>
  127 +
  128 + <programlisting language="php"><![CDATA[
  129 + $adapter->query('SELECT * FROM `artist` WHERE `id` = ?', array(5));
  130 +]]></programlisting>
  131 +
  132 + <para>
  133 + The above example will go through the following steps:
  134 + </para>
  135 +
  136 + <para>
  137 + 1. create a new Statement object
  138 + 2. prepare an array into a ParameterContainer if necessary
  139 + 3. inject the ParameterContainer into the Statement object
  140 + 4. execute the Statement object, producing a Result object
  141 + 5. check the Result object to check if the supplied sql was a "query", or a result set producing statement
  142 + 6. if it is a result set producing query, clone the ResultSet prototype, inject Result as datasource, return it
  143 + 7. else, return the Result
  144 + </para>
  145 +
  146 +
  147 + </section>
  148 +
  149 +
  150 + <section xml:id="zend.db.adapter.query-execution"><info><title>Query Execution Through Zend\Db\Adapter\Adapter::query()</title></info>
  151 +
  152 + <para>
  153 + In some cases, you have to execute statements directly. The primary purpose for
  154 + needing to execute sql instead of prepare and execute a sql statement, might be
  155 + because you are attempting to execute a DDL statement (which in most extensions
  156 + and vendor platforms), are un-preparable. An example of executing:
  157 + </para>
  158 +
  159 +
  160 + <programlisting language="php"><![CDATA[
  161 + $adapter->query('ALTER TABLE ADD INDEX(`foo_index`) ON (`foo_column`))', Adapter::QUERY_MODE_EXECUTE);
  162 +]]></programlisting>
  163 +
  164 + <para>
  165 + The primary difference to notice is that you must provide the Adapter::QUERY_MODE_EXECUTE
  166 + (execute) as the second parameter.
  167 + </para>
  168 +
  169 + </section>
  170 +
  171 +
  172 + <section xml:id="zend.db.adapter.statement-creation"><info><title>Creating Statements</title></info>
  173 +
  174 + <para>
  175 + While query() is highly useful for one-off and quick querying of a
  176 + database through Adapter, it generally makes more sense to create a
  177 + statement and interact with it directly, so that you have greater control
  178 + over the prepare-then-execute workflow. To do this, Adapter gives you a
  179 + routine called createStatement() that allows you to create a Driver
  180 + specific Statement to use so you can manage your own prepare-then-execute workflow.
  181 + </para>
  182 +
  183 + <programlisting language="php"><![CDATA[
  184 + $statement = $adapter->createStatement($sql, $optionalParameters);
  185 + $result = $statement->execute();
  186 +]]></programlisting>
  187 +
  188 + </section>
  189 +
  190 +
  191 + <section xml:id="zend.db.adapter.platform"><info><title>Using The Platform Object</title></info>
  192 +
  193 + <para>
  194 + The Platform object provides an API to assist in crafting queries in a way that
  195 + is specific to the SQL implemetation of a particular vendor. Nuances such
  196 + as how identifiers or values are quoted, or what the identifier separator
  197 + character is are handled by this object. To get an idea of the capabilities,
  198 + the interface for a platform object looks like this:
  199 + </para>
  200 +
  201 + <programlisting language="php"><![CDATA[
  202 + interface Zend\Db\Adapter\Platform\PlatformInterface
  203 + {
  204 + public function getName();
  205 + public function getQuoteIdentifierSymbol();
  206 + public function quoteIdentifier($identifier);
  207 + public function getQuoteValueSymbol();
  208 + public function quoteValue($value);
  209 + public function getIdentifierSeparator();
  210 + public function quoteIdentifierInFragment($identifier, array $additionalSafeWords = array());
  211 + }
  212 +]]></programlisting>
  213 +
  214 + <para>
  215 + For example, to quote a column name, specific to MySQL's way of quoting:
  216 + </para>
  217 +
  218 + <programlisting language="php"><![CDATA[
  219 + $platform = new Zend\Db\Adapter\Platform\Mysql;
  220 + $column = $platform->quoteIdentifier('first_name'); // returns `first_name`
  221 +]]></programlisting>
  222 +
  223 + <para>
  224 + Generally speaking, it is easier to get the proper Platform instance from the adapter:
  225 + </para>
  226 +
  227 + <programlisting language="php"><![CDATA[
  228 + $platform = $adapter->getPlatform();
  229 + // or
  230 + $platform = $adapter->platform; // magic property access
  231 +]]></programlisting>
  232 +
  233 + </section>
  234 +
  235 +
  236 + <section xml:id="zend.db.adapter.parameter-container"><info><title>Using The Parameter Container</title></info>
  237 +
  238 + <para>
  239 + The ParameterContainer object is a container for the various parameters that
  240 + need to be passed into a Statement object to fulfill all the various
  241 + parameterized parts of the SQL statement. This object implements the
  242 + ArrayAccess interface.
  243 + </para>
  244 +
  245 + </section>
  246 +
  247 + <section xml:id="zend.db.adapter.parameter-container.examples"><info><title>Examples</title></info>
  248 +
  249 + <para>
  250 + Creating a Driver and Vendor portable Query, Preparing and Iterating Result
  251 + </para>
  252 +
  253 + <programlisting language="php"><![CDATA[
  254 + $adapter = new Zend\Db\Adapter\Adapter($driverConfig);
  255 +
  256 + $qi = function($name) use ($adapter) { return $adapter->platform->quoteIdentifier($name); };
  257 + $fp = function($name) use ($adapter) { return $adapter->driver->formatParameterName($name); };
  258 +
  259 + $sql = 'UPDATE ' . $qi('artist')
  260 + . ' SET ' . $qi('name') . ' = ' . $fp('name')
  261 + . ' WHERE ' . $qi('id') . ' = ' . $fp('id');
  262 +
  263 + /* @var $statement Zend\Db\Adapter\DriverStatementInterface */
  264 + $statement = $adapter->query($sql);
  265 +
  266 + $parameters = array(
  267 + 'name' => 'Updated Artist',
  268 + 'id' => 1
  269 + );
  270 +
  271 + $statement->execute($parameters);
  272 +
  273 + // DATA INSERTED, NOW CHECK
  274 +
  275 + /* @var $statement Zend\Db\Adapter\DriverStatementInterface */
  276 + $statement = $adapter->query('SELECT * FROM '
  277 + . $qi('artist')
  278 + . ' WHERE id = ' . $fp('id'));
  279 +
  280 + /* @var $results Zend\Db\ResultSet\ResultSet */
  281 + $results = $statement->execute(array('id' => 1));
  282 +
  283 + $row = $results->current();
  284 + $name = $row['name'];
  285 +]]></programlisting>
  286 +
  287 + </section>
  288 +
  289 +</section>
137 documentation/manual/en/module_specs/Zend_Db-TableGateway.xml
... ... @@ -0,0 +1,137 @@
  1 +<?xml version="1.0" encoding="utf-8"?>
  2 +<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="zend.db.tablegateway"><info><title>Zend\Db\TableGateway</title></info>
  3 +
  4 + <para>
  5 + The Table Gateway object is intended to provide an object
  6 + that represents a table in a database, and the methods of
  7 + this object mirror the most common operations on a database
  8 + table. In code, the interface for such an object looks like this:
  9 + </para>
  10 +
  11 + <programlisting language="php"><![CDATA[
  12 + interface Zend\Db\TableGateway\TableGatewayInterface
  13 + {
  14 + public function getTableName();
  15 + public function select($where = null);
  16 + public function insert($set);
  17 + public function update($set, $where = null);
  18 + public function delete($where);
  19 + }
  20 +]]></programlisting>
  21 +
  22 +
  23 + <section xml:id="zend.db.tablegateway.by-example"><info><title>Examples</title></info>
  24 +
  25 +
  26 + <para>
  27 + Here are a few examples of TableGateway usage
  28 + </para>
  29 +
  30 +
  31 + <section xml:id="zend.db.tablegateway.by-example.select"><info><title>Selecting Rows</title></info>
  32 +
  33 + <programlisting language="php"><![CDATA[
  34 + $artistTable = new Zend\Db\TableGateway\TableGateway('artist', $adapter);
  35 + $rowset = $artistTable->select(array('id' => 2));
  36 + $row = $rowset->current();
  37 +
  38 + $name = $row['name'];
  39 + $name2 = $row->name;
  40 +]]></programlisting>
  41 +
  42 + </section>
  43 +
  44 + <section xml:id="zend.db.tablegateway.by-example.insert"><info><title>Inserting Rows</title></info>
  45 +
  46 + <programlisting language="php"><![CDATA[
  47 + $artistTable = new Zend\Db\TableGateway\TableGateway('artist', $adapter);
  48 + $result = $artistTable->insert(array(
  49 + 'name' => 'New Artist',
  50 + 'history' => 'This is the history'
  51 + ));
  52 +
  53 + // $result is rows affected by the insert
  54 +
  55 + $lastId = $artistTable->getLastInsertId();
  56 +]]></programlisting>
  57 +
  58 + </section>
  59 +
  60 +
  61 + <section xml:id="zend.db.tablegateway.by-example.update"><info><title>Updating Rows</title></info>
  62 +
  63 + <programlisting language="php"><![CDATA[
  64 + $artistTable = new Zend\Db\TableGateway\TableGateway('artist', $adapter);
  65 + $result = $artistTable->update(array('name' => 'New Artist'), array('id' => 2));
  66 +
  67 + $name = $row['name'];
  68 +]]></programlisting>
  69 +
  70 + </section>
  71 +
  72 +
  73 + <section xml:id="zend.db.tablegateway.by-example.delete"><info><title>Deleting Rows</title></info>
  74 +
  75 + <programlisting language="php"><![CDATA[
  76 + $artistTable = new Zend\Db\TableGateway\TableGateway('artist', $adapter);
  77 + $result = $artistTable->delete(array('id' => 2));
  78 +]]></programlisting>
  79 +
  80 + </section>
  81 +
  82 +
  83 + <section xml:id="zend.db.tablegateway.by-example.select-with-where"><info><title>Using a Fluent Where With Select</title></info>
  84 +
  85 + <programlisting language="php"><![CDATA[
  86 + $artistTable = new TableGateway('artist', $adapter);
  87 + $where = $select->where;
  88 + $where->like('name', 'Bar%');
  89 + $rowset = $artistTable->select($where);
  90 + $row = $rowset->current();
  91 +]]></programlisting>
  92 +
  93 + </section>
  94 +
  95 +
  96 + <section xml:id="zend.db.tablegateway.by-example.select-with-closure"><info><title>Using a Closure With Select</title></info>
  97 +
  98 + <programlisting language="php"><![CDATA[
  99 + $artistTable = new TableGateway('artist', $adapter);
  100 + $rowset = $artistTable->select(function (Select $select) {
  101 + $select->where->like('name', 'Bar%');
  102 + });
  103 + $row = $rowset->current();
  104 +]]></programlisting>
  105 +
  106 + </section>
  107 +
  108 +
  109 + <section xml:id="zend.db.tablegateway.by-example.row-gateway"><info><title>Row Gateway Integration</title></info>
  110 +
  111 + <programlisting language="php"><![CDATA[
  112 + $artistTable = new Zend\Db\TableGateway\TableGateway('artist', $adapter);
  113 + $artistTable->setSelectResultPrototype(
  114 + new Zend\Db\ResultSet\ResultSet(new Zend\Db\RowGateway\RowGateway($artistTable, 'id'))
  115 + );
  116 +
  117 + // find and update
  118 + $rowset = $artistTable->select(array('id' => 2));
  119 + $row = $rowset->current();
  120 + $row['name'] = 'New Artist'; // array notation
  121 + $affected = $row->save();
  122 +
  123 + // check
  124 + $rowset = $artistTable->select(array('id' => 2));
  125 + $row = $rowset->current();
  126 +]]></programlisting>
  127 +
  128 +
  129 +
  130 +
  131 + </section>
  132 +
  133 +
  134 +
  135 +
  136 +
  137 +</section>
2,445 documentation/manual/en/module_specs/Zend_Db_Adapter.xml
0 additions, 2,445 deletions not shown
86 documentation/manual/en/module_specs/Zend_Db_Profiler-Firebug.xml
... ... @@ -1,86 +0,0 @@
1   -<?xml version="1.0" encoding="utf-8"?>
2   -<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="zend.db.profiler.profilers.firebug"><info><title>Profiling with Firebug</title></info>
3   -
4   -
5   - <para>
6   - <classname>Zend_Db_Profiler_Firebug</classname> sends profiling infomation to the
7   - <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.getfirebug.com/">Firebug</link> <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://getfirebug.com/logging.html">Console</link>.
8   - </para>
9   -
10   - <para>
11   - All data is sent via the <classname>Zend_Wildfire_Channel_HttpHeaders</classname>
12   - component which uses <acronym>HTTP</acronym> headers to ensure the page content is not
13   - disturbed. Debugging <acronym>AJAX</acronym> requests that require clean
14   - <acronym>JSON</acronym> and <acronym>XML</acronym> responses is possible with this approach.
15   - </para>
16   -
17   - <para>
18   - Requirements:
19   - </para>
20   -
21   - <itemizedlist>
22   - <listitem>
23   - <para>
24   - Firefox Browser ideally version 3 but version 2 is also supported.
25   - </para>
26   - </listitem>
27   -
28   - <listitem>
29   - <para>
30   - Firebug Firefox Extension which you can download from <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://addons.mozilla.org/en-US/firefox/addon/1843">https://addons.mozilla.org/en-US/firefox/addon/1843</link>.
31   - </para>
32   - </listitem>
33   -
34   - <listitem>
35   - <para>
36   - FirePHP Firefox Extension which you can download from <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://addons.mozilla.org/en-US/firefox/addon/6149">https://addons.mozilla.org/en-US/firefox/addon/6149</link>.
37   - </para>
38   - </listitem>
39   - </itemizedlist>
40   -
41   - <example xml:id="zend.db.profiler.profilers.firebug.example.with_front_controller"><info><title>DB Profiling with Zend_Controller_Front</title></info>
42   -
43   -
44   - <programlisting language="php"><![CDATA[
45   -// In your bootstrap file
46   -
47   -$profiler = new Zend_Db_Profiler_Firebug('All DB Queries');
48   -$profiler->setEnabled(true);
49   -
50   -// Attach the profiler to your db adapter
51   -$db->setProfiler($profiler)
52   -
53   -// Dispatch your front controller
54   -
55   -// All DB queries in your model, view and controller
56   -// files will now be profiled and sent to Firebug
57   -]]></programlisting>
58   - </example>
59   -
60   - <example xml:id="zend.db.profiler.profilers.firebug.example.without_front_controller"><info><title>DB Profiling without Zend_Controller_Front</title></info>
61   -
62   -
63   - <programlisting language="php"><![CDATA[
64   -$profiler = new Zend_Db_Profiler_Firebug('All DB Queries');
65   -$profiler->setEnabled(true);
66   -
67   -// Attach the profiler to your db adapter
68   -$db->setProfiler($profiler)
69   -
70   -$request = new Zend_Controller_Request_Http();
71   -$response = new Zend_Controller_Response_Http();
72   -$channel = Zend_Wildfire_Channel_HttpHeaders::getInstance();
73   -$channel->setRequest($request);
74   -$channel->setResponse($response);
75   -
76   -// Start output buffering
77   -ob_start();
78   -
79   -// Now you can run your DB queries to be profiled
80   -
81   -// Flush profiling data to browser
82   -$channel->flush();
83   -$response->sendHeaders();
84   -]]></programlisting>
85   - </example>
86   -</section>
420 documentation/manual/en/module_specs/Zend_Db_Profiler.xml
... ... @@ -1,420 +0,0 @@
1   -<?xml version="1.0" encoding="utf-8"?>
2   -<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="zend.db.profiler"><info><title>Zend_Db_Profiler</title></info>
3   -
4   -
5   - <section xml:id="zend.db.profiler.introduction"><info><title>Introduction</title></info>
6   -
7   -
8   - <para>
9   - <classname>Zend_Db_Profiler</classname> can be enabled to allow profiling of
10   - queries. Profiles include the queries processed by the adapter as
11   - well as elapsed time to run the queries, allowing inspection of the
12   - queries that have been performed without needing to add extra
13   - debugging code to classes. Advanced usage also allows the
14   - developer to filter which queries are profiled.
15   - </para>
16   -
17   - <para>
18   - Enable the profiler by either passing a directive to the adapter
19   - constructor, or by asking the adapter to enable it later.
20   - </para>
21   -
22   - <programlisting language="php"><![CDATA[
23   -$params = array(
24   - 'host' => '127.0.0.1',
25   - 'username' => 'webuser',
26   - 'password' => 'xxxxxxxx',
27   - 'dbname' => 'test'
28   - 'profiler' => true // turn on profiler
29   - // set to false to disable (disabled by default)
30   -);
31   -
32   -$db = Zend_Db::factory('PDO_MYSQL', $params);
33   -
34   -// turn off profiler:
35   -$db->getProfiler()->setEnabled(false);
36   -
37   -// turn on profiler:
38   -$db->getProfiler()->setEnabled(true);
39   -]]></programlisting>
40   -
41   - <para>
42   - The value of the '<property>profiler</property>' option is flexible. It is interpreted
43   - differently depending on its type. Most often, you should use a simple boolean value,
44   - but other types enable you to customize the profiler behavior.
45   - </para>
46   -
47   - <para>
48   - A boolean argument sets the profiler to enabled if it is a <constant>TRUE</constant>
49   - value, or disabled if <constant>FALSE</constant>. The profiler class is the adapter's
50   - default profiler class, <classname>Zend_Db_Profiler</classname>.
51   - </para>
52   -
53   - <programlisting language="php"><![CDATA[
54   -$params['profiler'] = true;
55   -$db = Zend_Db::factory('PDO_MYSQL', $params);
56   -]]></programlisting>
57   -
58   - <para>
59   - An instance of a profiler object makes the adapter use that object. The object type must
60   - be <classname>Zend_Db_Profiler</classname> or a subclass thereof. Enabling the profiler
61   - is done separately.
62   - </para>
63   -
64   - <programlisting language="php"><![CDATA[
65   -$profiler = MyProject_Db_Profiler();
66   -$profiler->setEnabled(true);
67   -$params['profiler'] = $profiler;
68   -$db = Zend_Db::factory('PDO_MYSQL', $params);
69   -]]></programlisting>
70   -
71   - <para>
72   - The argument can be an associative array containing any or all of the keys
73   - '<property>enabled</property>', '<property>instance</property>', and
74   - '<property>class</property>'. The '<property>enabled</property>' and
75   - '<property>instance</property>' keys correspond to the boolean and instance types
76   - documented above. The '<property>class</property>' key is used to name a class to
77   - use for a custom profiler. The class must be <classname>Zend_Db_Profiler</classname> or
78   - a subclass. The class is instantiated with no constructor arguments. The
79   - '<property>class</property>' option is ignored when the '<property>instance</property>'
80   - option is supplied.
81   - </para>
82   -
83   - <programlisting language="php"><![CDATA[
84   -$params['profiler'] = array(
85   - 'enabled' => true,
86   - 'class' => 'MyProject_Db_Profiler'
87   -);
88   -$db = Zend_Db::factory('PDO_MYSQL', $params);
89   -]]></programlisting>
90   -
91   - <para>
92   - Finally, the argument can be an object of type <classname>Zend_Config</classname>
93   - containing properties, which are treated as the array keys described above. For example,
94   - a file "<filename>config.ini</filename>" might contain the following data:
95   - </para>
96   -
97   - <programlisting language="ini"><![CDATA[
98   -[main]
99   -db.profiler.class = "MyProject_Db_Profiler"
100   -db.profiler.enabled = true
101   -]]></programlisting>
102   -
103   - <para>
104   - This configuration can be applied by the following <acronym>PHP</acronym> code:
105   - </para>
106   -
107   - <programlisting language="php"><![CDATA[
108   -$config = new Zend_Config_Ini('config.ini', 'main');
109   -$params['profiler'] = $config->db->profiler;
110   -$db = Zend_Db::factory('PDO_MYSQL', $params);
111   -]]></programlisting>
112   -
113   - <para>
114   - The '<property>instance</property>' property may be used as in the following:
115   - </para>
116   -
117   - <programlisting language="php"><![CDATA[
118   -$profiler = new MyProject_Db_Profiler();
119   -$profiler->setEnabled(true);
120   -$configData = array(
121   - 'instance' => $profiler
122   - );
123   -$config = new Zend_Config($configData);
124   -$params['profiler'] = $config;
125   -$db = Zend_Db::factory('PDO_MYSQL', $params);
126   -]]></programlisting>
127   - </section>
128   -
129   - <section xml:id="zend.db.profiler.using"><info><title>Using the Profiler</title></info>
130   -
131   -
132   - <para>
133   - At any point, grab the profiler using the adapter's
134   - <methodname>getProfiler()</methodname> method:
135   - </para>
136   -
137   - <programlisting language="php"><![CDATA[
138   -$profiler = $db->getProfiler();
139   -]]></programlisting>
140   -
141   - <para>
142   - This returns a <classname>Zend_Db_Profiler</classname> object instance. With
143   - that instance, the developer can examine your queries using a
144   - variety of methods:
145   - </para>
146   -
147   - <itemizedlist>
148   - <listitem>
149   - <para>
150   - <methodname>getTotalNumQueries()</methodname> returns the total number
151   - of queries that have been profiled.
152   - </para>
153   - </listitem>
154   -
155   - <listitem>
156   - <para>
157   - <methodname>getTotalElapsedSecs()</methodname> returns the total
158   - number of seconds elapsed for all profiled queries.
159   - </para>
160   - </listitem>
161   -
162   - <listitem>
163   - <para>
164   - <methodname>getQueryProfiles()</methodname> returns an array of all
165   - query profiles.
166   - </para>
167   - </listitem>
168   -
169   - <listitem>
170   - <para>
171   - <methodname>getLastQueryProfile()</methodname> returns the last (most
172   - recent) query profile, regardless of whether or not the query
173   - has finished (if it hasn't, the end time will be <constant>NULL</constant>)
174   - </para>
175   - </listitem>
176   -
177   - <listitem>
178   - <para>
179   - <methodname>clear()</methodname> clears any past query profiles
180   - from the stack.
181   - </para>
182   - </listitem>
183   - </itemizedlist>
184   -
185   - <para>
186   - The return value of <methodname>getLastQueryProfile()</methodname> and the
187   - individual elements of <methodname>getQueryProfiles()</methodname> are
188   - <classname>Zend_Db_Profiler_Query</classname> objects, which provide the
189   - ability to inspect the individual queries themselves:
190   - </para>
191   -
192   - <itemizedlist>
193   - <listitem>
194   - <para>
195   - <methodname>getQuery()</methodname> returns the <acronym>SQL</acronym> text of
196   - the query. The <acronym>SQL</acronym> text of a prepared statement with
197   - parameters is the text at the time the query was prepared, so it contains
198   - parameter placeholders, not the values used when the
199   - statement is executed.
200   - </para>
201   - </listitem>
202   -
203   - <listitem>
204   - <para>
205   - <methodname>getQueryParams()</methodname> returns an array of
206   - parameter values used when executing a prepared query.
207   - This includes both bound parameters and arguments to the
208   - statement's <methodname>execute()</methodname> method. The keys of
209   - the array are the positional (1-based) or named (string)
210   - parameter indices.
211   - </para>
212   - </listitem>
213   -
214   - <listitem>
215   - <para>
216   - <methodname>getElapsedSecs()</methodname> returns the number of
217   - seconds the query ran.
218   - </para>
219   - </listitem>
220   - </itemizedlist>
221   -
222   - <para>
223   - The information <classname>Zend_Db_Profiler</classname> provides is useful for
224   - profiling bottlenecks in applications, and for debugging queries
225   - that have been run. For instance, to see the exact query that was
226   - last run:
227   - </para>
228   -
229   - <programlisting language="php"><![CDATA[
230   -$query = $profiler->getLastQueryProfile();
231   -
232   -echo $query->getQuery();
233   -]]></programlisting>
234   -
235   - <para>
236   - Perhaps a page is generating slowly; use the profiler to determine
237   - first the total number of seconds of all queries, and then step
238   - through the queries to find the one that ran longest:
239   - </para>
240   -
241   - <programlisting language="php"><![CDATA[
242   -$totalTime = $profiler->getTotalElapsedSecs();
243   -$queryCount = $profiler->getTotalNumQueries();
244   -$longestTime = 0;
245   -$longestQuery = null;
246   -
247   -foreach ($profiler->getQueryProfiles() as $query) {
248   - if ($query->getElapsedSecs() > $longestTime) {
249   - $longestTime = $query->getElapsedSecs();
250   - $longestQuery = $query->getQuery();
251   - }
252   -}
253   -
254   -echo 'Executed ' . $queryCount . ' queries in ' . $totalTime .
255   - ' seconds' . "\n";
256   -echo 'Average query length: ' . $totalTime / $queryCount .
257   - ' seconds' . "\n";
258   -echo 'Queries per second: ' . $queryCount / $totalTime . "\n";
259   -echo 'Longest query length: ' . $longestTime . "\n";
260   -echo "Longest query: \n" . $longestQuery . "\n";
261   -]]></programlisting>
262   - </section>
263   -
264   - <section xml:id="zend.db.profiler.advanced"><info><title>Advanced Profiler Usage</title></info>
265   -
266   -
267   - <para>
268   - In addition to query inspection, the profiler also allows the
269   - developer to filter which queries get profiled. The following
270   - methods operate on a <classname>Zend_Db_Profiler</classname> instance:
271   - </para>
272   -
273   - <section xml:id="zend.db.profiler.advanced.filtertime"><info><title>Filter by query elapsed time</title></info>
274   -
275   -
276   - <para>
277   - <methodname>setFilterElapsedSecs()</methodname> allows the developer to set
278   - a minimum query time before a query is profiled. To remove the
279   - filter, pass the method a <constant>NULL</constant> value.
280   - </para>
281   -
282   - <programlisting language="php"><![CDATA[
283   -// Only profile queries that take at least 5 seconds:
284   -$profiler->setFilterElapsedSecs(5);
285   -
286   -// Profile all queries regardless of length:
287   -$profiler->setFilterElapsedSecs(null);
288   -]]></programlisting>
289   - </section>
290   -
291   - <section xml:id="zend.db.profiler.advanced.filtertype"><info><title>Filter by query type</title></info>
292   -
293   -
294   - <para>
295   - <methodname>setFilterQueryType()</methodname> allows the developer to set
296   - which types of queries should be profiled; to profile multiple
297   - types, logical OR them. Query types are defined as the following
298   - <classname>Zend_Db_Profiler</classname> constants:
299   - </para>
300   -
301   - <itemizedlist>
302   - <listitem>
303   - <para>
304   - <constant>Zend_Db_Profiler::CONNECT</constant>: connection
305   - operations, or selecting a database.
306   - </para>
307   - </listitem>
308   -
309   - <listitem>
310   - <para>
311   - <constant>Zend_Db_Profiler::QUERY</constant>: general database
312   - queries that do not match other types.
313   - </para>
314   - </listitem>
315   -
316   - <listitem>
317   - <para>
318   - <constant>Zend_Db_Profiler::INSERT</constant>: any query that
319   - adds new data to the database, generally <acronym>SQL</acronym>
320   - <acronym>INSERT</acronym>.
321   - </para>
322   - </listitem>
323   -
324   - <listitem>
325   - <para>
326   - <constant>Zend_Db_Profiler::UPDATE</constant>: any query that
327   - updates existing data, usually <acronym>SQL</acronym>
328   - <acronym>UPDATE</acronym>.
329   - </para>
330   - </listitem>
331   -
332   - <listitem>
333   - <para>
334   - <constant>Zend_Db_Profiler::DELETE</constant>: any query that
335   - deletes existing data, usually <acronym>SQL</acronym>
336   - <constant>DELETE</constant>.
337   - </para>
338   - </listitem>
339   -
340   - <listitem>
341   - <para>
342   - <constant>Zend_Db_Profiler::SELECT</constant>: any query that
343   - retrieves existing data, usually <acronym>SQL</acronym>
344   - <acronym>SELECT</acronym>.
345   - </para>
346   - </listitem>
347   -
348   - <listitem>
349   - <para>
350   - <constant>Zend_Db_Profiler::TRANSACTION</constant>: any
351   - transactional operation, such as start transaction, commit,
352   - or rollback.
353   - </para>
354   - </listitem>
355   - </itemizedlist>
356   -
357   - <para>
358   - As with <methodname>setFilterElapsedSecs()</methodname>, you can remove any
359   - existing filters by passing <constant>NULL</constant> as the sole
360   - argument.
361   - </para>
362   -
363   - <programlisting language="php"><![CDATA[
364   -// profile only SELECT queries
365   -$profiler->setFilterQueryType(Zend_Db_Profiler::SELECT);
366   -
367   -// profile SELECT, INSERT, and UPDATE queries
368   -$profiler->setFilterQueryType(Zend_Db_Profiler::SELECT |
369   - Zend_Db_Profiler::INSERT |
370   - Zend_Db_Profiler::UPDATE);
371   -
372   -// profile DELETE queries
373   -$profiler->setFilterQueryType(Zend_Db_Profiler::DELETE);
374   -
375   -// Remove all filters
376   -$profiler->setFilterQueryType(null);
377   -]]></programlisting>
378   - </section>
379   -
380   - <section xml:id="zend.db.profiler.advanced.getbytype"><info><title>Retrieve profiles by query type</title></info>
381   -
382   -
383   - <para>
384   - Using <methodname>setFilterQueryType()</methodname> can cut down on the
385   - profiles generated. However, sometimes it can be more useful to
386   - keep all profiles, but view only those you need at a given
387   - moment. Another feature of <methodname>getQueryProfiles()</methodname> is
388   - that it can do this filtering on-the-fly, by passing a query
389   - type (or logical combination of query types) as its first
390   - argument; see <link linkend="zend.db.profiler.advanced.filtertype">this
391   - section</link> for a list of the query type constants.
392   - </para>
393   -
394   - <programlisting language="php"><![CDATA[
395   -// Retrieve only SELECT query profiles
396   -$profiles = $profiler->getQueryProfiles(Zend_Db_Profiler::SELECT);
397   -
398   -// Retrieve only SELECT, INSERT, and UPDATE query profiles
399   -$profiles = $profiler->getQueryProfiles(Zend_Db_Profiler::SELECT |
400   - Zend_Db_Profiler::INSERT |
401   - Zend_Db_Profiler::UPDATE);
402   -
403   -// Retrieve DELETE query profiles
404   -$profiles = $profiler->getQueryProfiles(Zend_Db_Profiler::DELETE);
405   -]]></programlisting>
406   - </section>
407   - </section>
408   -
409   - <section xml:id="zend.db.profiler.profilers"><info><title>Specialized Profilers</title></info>
410   -
411   -
412   - <para>
413   - A Specialized Profiler is an object that inherits from
414   - <classname>Zend_Db_Profiler</classname>. Specialized Profilers treat
415   - profiling information in specific ways.
416   - </para>
417   -
418   - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Zend_Db_Profiler-Firebug.xml"/>
419   - </section>
420   -</section>
1,440 documentation/manual/en/module_specs/Zend_Db_Select.xml
... ... @@ -1,1440 +0,0 @@
1   -<?xml version="1.0" encoding="utf-8"?>
2   -<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="zend.db.select"><info><title>Zend_Db_Select</title></info>
3   -
4   -
5   - <section xml:id="zend.db.select.introduction"><info><title>Introduction</title></info>
6   -
7   -
8   - <para>
9   - The <classname>Zend_Db_Select</classname> object represents a <acronym>SQL</acronym>
10   - <acronym>SELECT</acronym> query statement. The class has methods for adding individual
11   - parts to the query. You can specify some parts of the query using <acronym>PHP</acronym>
12   - methods and data structures, and the class forms the correct <acronym>SQL</acronym>
13   - syntax for you. After you build a query, you can execute the query as if you had written
14   - it as a string.
15   - </para>
16   -
17   - <para>
18   - The value offered by <classname>Zend_Db_Select</classname> includes:
19   - </para>
20   -
21   - <itemizedlist>
22   - <listitem>
23   - <para>
24   - Object-oriented methods for specifying <acronym>SQL</acronym> queries in a
25   - piece-by-piece manner;
26   - </para>
27   - </listitem>
28   -
29   - <listitem>
30   - <para>
31   - Database-independent abstraction of some parts of the <acronym>SQL</acronym>
32   - query;
33   - </para>
34   - </listitem>
35   -
36   - <listitem>
37   - <para>
38   - Automatic quoting of metadata identifiers in most cases, to support identifiers
39   - containing <acronym>SQL</acronym> reserved words and special characters;
40   - </para>
41   - </listitem>
42   -
43   - <listitem>
44   - <para>
45   - Quoting identifiers and values, to help reduce risk of <acronym>SQL</acronym>
46   - injection attacks.
47   - </para>
48   - </listitem>
49   - </itemizedlist>
50   -
51   - <para>
52   - Using <classname>Zend_Db_Select</classname> is not mandatory. For very simple
53   - <acronym>SELECT</acronym> queries, it is usually simpler to specify the entire
54   - <acronym>SQL</acronym> query as a string and execute it using Adapter methods like
55   - <methodname>query()</methodname> or <methodname>fetchAll()</methodname>. Using
56   - <classname>Zend_Db_Select</classname> is helpful if you need to assemble a
57   - <acronym>SELECT</acronym> query procedurally, or based on conditional logic in your
58   - application.
59   - </para>
60   - </section>
61   -
62   - <section xml:id="zend.db.select.creating"><info><title>Creating a Select Object</title></info>
63   -
64   -
65   - <para>
66   - You can create an instance of a <classname>Zend_Db_Select</classname> object using the
67   - <methodname>select()</methodname> method of a
68   - <classname>Zend_Db_Adapter_Abstract</classname> object.
69   - </para>
70   -
71   - <example xml:id="zend.db.select.creating.example-db"><info><title>Example of the database adapter's select() method</title></info>
72   -
73   -
74   - <programlisting language="php"><![CDATA[
75   -$db = Zend_Db::factory( ...options... );
76   -$select = $db->select();
77   -]]></programlisting>
78   - </example>
79   -
80   - <para>
81   - Another way to create a <classname>Zend_Db_Select</classname> object is with its
82   - constructor, specifying the database adapter as an argument.
83   - </para>
84   -
85   - <example xml:id="zend.db.select.creating.example-new"><info><title>Example of creating a new Select object</title></info>
86   -
87   -
88   - <programlisting language="php"><![CDATA[
89   -$db = Zend_Db::factory( ...options... );
90   -$select = new Zend_Db_Select($db);
91   -]]></programlisting>
92   - </example>
93   - </section>
94   -
95   - <section xml:id="zend.db.select.building"><info><title>Building Select queries</title></info>
96   -
97   -
98   - <para>
99   - When building the query, you can add clauses of the query one by one. There is a
100   - separate method to add each clause to the <classname>Zend_Db_Select</classname> object.
101   - </para>
102   -
103   - <example xml:id="zend.db.select.building.example"><info><title>Example of the using methods to add clauses</title></info>
104   -
105   -
106   - <programlisting language="php"><![CDATA[
107   -// Create the Zend_Db_Select object
108   -$select = $db->select();
109   -
110   -// Add a FROM clause
111   -$select->from( ...specify table and columns... )
112   -
113   -// Add a WHERE clause
114   -$select->where( ...specify search criteria... )
115   -
116   -// Add an ORDER BY clause
117   -$select->order( ...specify sorting criteria... );
118   -]]></programlisting>
119   - </example>
120   -
121   - <para>