Author: plavin
Date: 2007-08-09 00:33:25 +0200 (Thu, 09 Aug 2007)
New Revision: 7391
Log:
Getting there
Modified:
trunk/userguide/php-pdo.xml
Modified: trunk/userguide/php-pdo.xml
===================================================================
--- trunk/userguide/php-pdo.xml 2007-08-08 21:32:17 UTC (rev 7390)
+++ trunk/userguide/php-pdo.xml 2007-08-08 22:33:25 UTC (rev 7391)
Changed blocks: 21, Lines Added: 163, Lines Deleted: 101; 20026 bytes
@@ -1,39 +1,88 @@
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
+[
+<!ENTITY % all.entities SYSTEM "../refman-common/all-entities.ent">
+%all.entities;
+]>
<chapter id="php-pdo">
<title>Using MySQL with PDO</title>
- <section id="first">
+ <section id="prerequisites">
- <title>Outline</title>
+ <title>Prerequisites for Using PDO</title>
<para>
- object-oriented many built-in classes using PDO, SimpleXMLElement
+ PDO is a PHP extension providing a data-access abstraction layer
+ that can be used with a variety of databases. This gives you the
+ flexibility of changing the database backend without having to
+ alter your access methods. Even if you use MySQL exclusively, PDO
+ can provide advantages; you can use the same data-access methods
+ regardless of the MySQL version. This does away with the need for
+ using the standard MySQL extension with older versions of MySQL
+ and using the MySQLi extension for later versions. An additional advantage,
+ is the ability to use object-oriented code regardless of the version of
+ MySQL.
</para>
- </section>
+ <para>
+ PDO requires the object-oriented capabilities of PHP 5, so PHP 5.0
+ or higher is a prerequisite. It ships with binary versions of PHP
+ 5.1 and 5.2 and is very simple to implement on most operating
+ systems.
+ </para>
- <section>
+ <para>
+ Compiling PHP from source is the one sure way to customize PHP to
+ your exact specifications and ensure that you have not only PDO
+ but also the drivers you need. However, the package managers of
+ most current Linux distributions make it easy to add
+ support—if it's not already there. Under Ubuntu (feisty
+ fawn) and openSuSE (10.2) the <literal>php5-pdo</literal> module
+ provides support for PDO and the <literal>php5-mysql</literal>
+ module provides the PDO driver for MySQL. If you are already using
+ MySQL with PHP you already have the PDO driver. You only need
+ check that you have the PDO module loaded.
+ </para>
- <title>Prerequisites</title>
-
<para>
- PDO ships with binary versions of PHP 5.1 and higher
+ If you are running PHP 5 with Windows you'll need to do a little
+ more work to enable the PDO extensions but the instructions given
+ at <ulink url="http://www.php.net/manual/en/ref.pdo.php"/> are
+ simple and clear—add references to the extensions section of
+ your Apache web server configuration file and make sure that the
+ <filename>dll</filename> extensions are in the correct location.
+ This URL also provides instructions for using PDO with PHP 5.0
+ regardless of your operating system.
</para>
+ </section>
+
+ <section id="project-outline">
+
+ <title>Project Outline</title>
+
<para>
- PDO requires the object-oriented capabilities of PHP 5 so you
- cannot use with earlier versions of PHP. for using PDO with
- earlier versions see the instructions at php.net
+ The PDO extension is entirely object-oriented,
+ there is no procedural version of this extension,
+ so some knowledge of object-oriented programming is
+ assumed.
</para>
<para>
- If you are not compiling PHP from source most current Linux
- distributions make it easy to using the package manager you can
- load Ubuntu and SuSE the <literal>php2-mysql</literal> module
- provides the PDO driver for MySQL
+ The project examined in this article
+ uses PDO to select from and insert into a database
+ of PHP classes. XML representations of
+ PHP classes, both internal and user-defined,
+ are transformed into SQL INSERT statements using
+ the SimpleXMLElement class.
+ </para>
+
+ <para>
+ Even if your XML skills are
+ weak, you'll find the SimpleXMLElement easy to
+ understand and use. blah blah
</para>
</section>
@@ -43,14 +92,14 @@
<title>The XML Document Format</title>
<para>
- Using PHP's Reflection classes you can quickly build an XML file
- of a PHP class. We won't concern ourselves here with the details
- of how to do this; we'll review an example file in this section
- and include other examples in the appendixes at the end of this
- article. However, our treatment is constrained by what the
- reflection classes are capable of. The reflection classes are
- capable of revealing Javadoc style comments for user-defined
- classes, methods, and
+ Using PHP's reflection classes you can automate building an XML
+ file of a PHP class. We won't concern ourselves here with the
+ details of how to do this; we'll review an example file in this
+ section and include other examples in the appendix at the end of
+ this article. However, our treatment is constrained by the
+ capabilities of the reflection classes. For example, Javadoc style
+ comments can be captured for user-defined classes, methods, and
+ data members but not for constants.
</para>
<para>
@@ -63,9 +112,8 @@
</para>
<para>
- In the example that follows, the
- <literal>mysqli_sql_exception</literal> class has been convert to
- an XML document.
+ The following example is an XML representation of what reflection
+ reveals about the <literal>mysqli_sql_exception</literal> class.
</para>
<programlisting>
@@ -77,14 +125,14 @@
<type final="" abstract="">class</type>
<origin mod_date="" num_lines="">internal</origin>
<parent_class>RuntimeException</parent_class>
- <class_doccomments/>
+ <class_doc_comments/>
<interfaces_list/>
<methods_list>
<method static="0" final="1" abstract="0" declaring_class="Exception" priority="2">
<method_name>__clone</method_name>
<method_origin>internal</method_origin>
<visibility>private</visibility>
- <method_doccomment/>
+ <method_doc_comment/>
</method>
<method static="0" final="0" abstract="0" declaring_class="Exception" priority="2">
<method_name>__construct</method_name>
@@ -92,14 +140,14 @@
<visibility>public</visibility>
<param classtype="" defaultvalue="" byreference="" isoptional="1">message</param>
<param classtype="" defaultvalue="" byreference="" isoptional="1">code</param>
- <method_doccomment/>
+ <method_doc_comment/>
...
</method>
</methods_list>
<datamembers_list>
<datamember visibility="protected" static="0" defaultvalue="""">
<datamember_name>message</datamember_name>
- <datamember_doccomment/>
+ <datamember_doc_comment/>
</datamember>
...
</datamembers_list>
@@ -108,25 +156,24 @@
</programlisting>
<para>
- The ellipses in the preceding listing indicate missing methods and
- data members but there's enough detail to form an idea of what any
- XML representation of a PHP class might look like.
+ Not all methods or data members are included but there's enough
+ detail to form an idea of what any XML representation of a PHP
+ class might look like.
</para>
<para>
- Most of the tags and attributes are self explanatory — for
- example, the <literal>message</literal> data member is a
- protected, non-static data member with no default value. not spend
- too much tuime examining this file. It's details will become
- apparent when we examine the DDL scripts used to create the
+ Most of the tags and attributes are self explanatory. For example,
+ the <literal>message</literal> data member is a protected,
+ non-static data member with no default value. Details will become
+ more apparent when we examine the DDL scripts used to create the
database tables.
</para>
</section>
- <section id="create-database-script">
+ <section id="dll-statementst">
- <title>Create Database Script</title>
+ <title>Creating the Tables</title>
<para>
An XML class file is effectively a flat-file database. To convert
@@ -192,7 +239,7 @@
`last_modified` DATE default NULL,
`num_lines` VARCHAR(10) NOT NULL default '',
`parent_class` VARCHAR(70) NOT NULL default '',
- `class_doccomment` TINYTEXT,
+ `class_doc_comment` TINYTEXT,
PRIMARY KEY (`id`),
UNIQUE KEY `name` (`name`)
) ENGINE=InnoDB DEFAULT CHARSET=latin1;
@@ -201,10 +248,10 @@
<para>
The <literal>name</literal> field uniquely identifies each record
so could be used as a primary key but an AUTO_INCREMENT field is
- perhaps more convenient. Only two modifiers can be applied to a
- class or interface and these are <literal>final</literal> and
- <literal>abstract</literal>. There are no static classes in PHP so
- there's no need for this modifier.
+ more convenient. Only two modifiers can be applied to a class or
+ interface and these are <literal>final</literal> and
+ <literal>abstract</literal>. (Static classes don't exist in PHP so
+ there's no need for this modifier.)
</para>
<para>
@@ -213,7 +260,7 @@
are only two options; object templates are either classes or
interfaces and these are either user-defined or built-in. The
<literal>last_modified</literal>, <literal>num_lines</literal>,
- and <literal>class_doccomment</literal> fields only apply to
+ and <literal>class_doc_comment</literal> fields only apply to
user-defined classes since reflection cannot capture this
information when used with an internal class.
</para>
@@ -239,8 +286,8 @@
</para>
<para>
- Classes can also have any number of methods. This table is similar
- to the classes table.
+ Classes can also have any number of methods, requiring a table
+ similar to the classes table.
</para>
<programlisting>
@@ -254,7 +301,7 @@
`abstract` TINYINT(1) NOT NULL default '0',
`declaring_class` VARCHAR(70) NOT NULL default '',
`priority` TINYINT(1) NOT NULL default '1',
- `method_doccomment` TINYTEXT,
+ `method_doc_comment` TINYTEXT,
PRIMARY KEY (`class_id`,`method_name`)
) ENGINE=InnoDB DEFAULT CHARSET=latin1;
</programlisting>
@@ -263,10 +310,9 @@
Like the table of classes, this table supports a
<literal>method_origin</literal> field and final and abstract
modifiers. However, methods can also be static and have a
- visibility modofier. The <literal>declaring_class</literal> field
- simply indicates whether a method is inherited as is or overridden
- in the child or entirely new. Methods may have any number of
- parameters, hence the need for a parameters table.
+ visibility modifier. The <literal>declaring_class</literal> field
+ simply indicates whether a method is inherited as is, overridden
+ in the child, or entirely new.
</para>
<para>
@@ -277,6 +323,11 @@
and method name.
</para>
+ <para>
+ Methods may have any number of parameters, hence the need for a
+ parameters table.
+ </para>
+
<programlisting>
CREATE TABLE `tblparameters` (
`class_id` INT(11) NOT NULL,
@@ -296,12 +347,13 @@
be type-hinted so a <literal>class_type</literal> field is also
necessary. Parameter variable names must be unique to the method
and method names must be unique to a class so these two fields
- along with the class id uniquely identify a parameter and so may
- form the primary key.
+ along with the class id uniquely identify a parameter and form the
+ primary key.
</para>
<para>
- The data members table is
+ The data members table incorporates a number of fields common to
+ the other tables.
</para>
<programlisting>
@@ -311,13 +363,14 @@
`visibility` ENUM('public','private', 'protected') NOT NULL,
`isstatic` TINYINT(1) NOT NULL default '0',
`default_value` VARCHAR(50) NOT NULL default '',
- `datamember_doccomment` TINYTEXT NOT NULL,
+ `datamember_doc_comment` TINYTEXT NOT NULL,
PRIMARY KEY (`class_id`,`datamember_name`)
) ENGINE=InnoDB DEFAULT CHARSET=latin1;
</programlisting>
<para>
- A table of constants is much simpler than the data members table.
+ A table of constants is much simpler than the data members table
+ and is made up of three fields only..
</para>
<programlisting>
@@ -331,7 +384,7 @@
<para>
Unlike data members, any comments that accompany constants cannot
- be retrieved so there is no <literal>doccomment</literal> field
+ be retrieved so there is no <literal>doc_comment</literal> field
for the table of constants.
</para>
@@ -348,32 +401,33 @@
<title>Creating a PDO Connection</title>
<para>
- want to create a drop-down list box of existing XML versions of
- PHP classes that are not already included in our database. This
- involves loading an array with the names of XML files and
- comparing this to filenames already contained in our database.
+ Records are added to a database using a web form.
+ Within this form a drop-down list box is
+ populated with the names of classes that are not already included
+ in the database, thereby eliminating duplicate submissions.
</para>
<para>
- connection parameters are contained in the
- <filename>connection.php</filename> file The names of existing XML
- class files are copied from the <filename>xml</filename> directory
- into an array. This array is compared to the classes already
- contained in the database to create drop-down list of files that
- aren't yet included.
+ The names of existing XML class files are copied from a
+ directory into an array. This is
+ done using a user-defined class,
+ <literal>DirectoryItems</literal>, that copies the names of files in a
+ specified directory (<filename>xml</filename> in this particular
+ case) into an array. This array is
+ compared to the classes already contained in the database to
+ create a drop-down list of classes that aren't yet included.
</para>
<programlisting>
-<form name= "select_class" action="adddbrecord.php" method="get" style="padding:5px;">
+<form name= "select_class" action="add_record.php" method="get" style="padding:5px;">
<select style="max-width: 180px; min-width: 180px;" name = "xmlfilename" >
- <?php
- //get files in xml dir
- //select only what not in db use array_diff
- //auto load user-defined classes
+ <?php
+ //autoload user-defined classes
function __autoload($class){
include 'classes/'.$class.'.php';
}
include 'connection.php';
+ //get names of files in the xml dir
$di = new DirectoryItems('xml');
$di->filter('xml');
$arr = $di->getFilearray();
@@ -389,20 +443,23 @@
}catch(PDOException $e){
echo $e;
}
+ //select only what is not in the db
$not_in_db = array_diff( $arr, $arr2);
natcasesort($not_in_db);
foreach($not_in_db as $v){
echo "<option>$v</option>\n";
}
- echo "</select><br /><br />";
- ?>
+ ?>
+ </select><br /><br />
<input type="submit" value="submit" />
</form>
</programlisting>
<para>
- Creating the connection is as simple as specifying the database
- type, the host name, and database credentials.
+ Creating the connection to a MySQL database is as simple as
+ specifying the database type, the host name, and database
+ credentials. These connection parameters are contained in the
+ <filename>connection.php</filename> file.
</para>
<para>
@@ -412,35 +469,34 @@
since you can then enclose all your code in a try block and deal
with errors in one place. The line
<literal>$db->setAttribute(PDO::ATTR_ERRMODE,
- PDO::ERRMODE_EXCEPTION);</literal> does just this. To set the
- error mode you need to create a connection first. Nevertheless, if
- actual creation of the database connection fails an exception is
- still thrown and will be caught by the catch block.
+ PDO::ERRMODE_EXCEPTION);</literal> ensures the creation of
+ exceptions rather than errors . In order to set the error mode you
+ need to create a connection object first. Consequently, failure to
+ create a connection cannot itself throw an exception.
</para>
<para>
- in addition to setting the error mode the
- <literal>setAttribute</literal> method you can for instance force
- column names to upper or lower case
+ The <literal>setAttribute</literal> method performs a number of
+ functions besides setting the error type. it can be used to force
+ column names to upper or lower case and also to set
+ database-specific capabilities such as
+ <literal>MYSQL_ATTR_USE_BUFFERED_QUERY</literal>.
</para>
<para>
- can also be used to set database-specific capabilities such as
- <literal>MYSQL_ATTR_USE_BUFFERED_QUERY</literal>
+ In this case the requirements are fairly simple; use the
+ <literal>query</literal> method of a PDO connection to retrieve
+ the name field of all the classes currently stored in the
+ database.
</para>
<para>
- In this case the requirements are fairly simple; retrieve the name
- field of all the classes currently stored in the database.
- </para>
-
- <para>
- The <literal>query</literal> method of a PDO connection The
- <literal>query</literal> method returns a PDO statement object and
- there are number of ways that we can use this object to perform
- the task at hand. We could use the <literal>fetch</literal> method
+ The <literal>query</literal>method returns a PDOStatement object.
+ There are a number of ways that we can use this object in order to
+ determine all the classes in the database. One possibility is to
+ use the <literal>fetch</literal> method of the PDOStatement class
to return each row and then examine that row to determine whether
- or not a specific class is already in the database.
+ or not the specific class is already in the database.
</para>
<para>
@@ -455,8 +511,8 @@
</para>
<para>
- using the correct method to fetch query results makes it easy to
- populate a drop-down list box with XML files that are not yet
+ Using the appropriate method to fetch query results makes it easy
+ to populate a drop-down list box with XML files that are not yet
included in the database. The next section looks at inserting data
into a database.
</para>
@@ -468,10 +524,16 @@
<title>Moving XML Data into a Database</title>
<para>
+ The <literal>action</literal> attribute of the form in the
+ the previous section is <filename>add_record.php</filename>.
+ This is the file that inserts records into the tables.
+ </para>
+
+ <para>
Converting an XML document of a PHP class into a database format
is done using the XMLFormatToSQL class. This class creates a
SimpleXMLElement object and uses its methods to generate the SQL
- necessary to insert records into the the
+ necessary to insert records into the
<literal>phpclasses</literal> database.
</para>
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r7391 - trunk/userguide | plavin | 9 Aug |
