1. What is PDO
2. What Databases does PDO support
3. Where do I begin?
4. Connect to a Database
   • Connect to PgSQL
   • Connect to SQLite
   • Connect to MySQL
   • Connect to Firebird
   • Connect to Informix
   • Connect to Oracle
   • Connect to ODBC
   • Connect to DBLIB
   • Connect to IBM
5. There is no five
6. Close a Database Connection
7. Query a Database
   • INSERT
   • SELECT
   • UPDATE
8. Fetch Modes
   • FETCH ASSOC
   • FETCH NUM
   • FETCH BOTH
   • FETCH OBJECT
   • FETCH LAZY
   • FETCH CLASS
   • FETCH INTO
9. Error Handling
10. Prepared Statements
11. Transactions
12. Get Last Insert ID
13. Global Instance
14. Conclusions

What is PDO.

PDO is a PHP extension to formalise PHP's database connections by creating a uniform interface. This allows developers to create code which is portable across many databases and platforms. PDO is _not_ just another abstraction layer like PearDB although PearDB may use PDO as a backend. Those of you familiar with Perls DBI may find the syntax disturbingly familiar.

NOTE: YOUR MUST READ THE SECTION ON ERROR HANDLINGTO BENIFIT FROM THIS TUTORIAL

During this tutorial we will be using a database called animals, which, as you might have guessed, is a database of animals, genius! The animals table is described here.

What databases does PDO support?

PDO supports many of the popular databases as seen on the list below.

• DBLIB: FreeTDS / Microsoft SQL Server / Sybase
• Firebird (http://firebird.sourceforge.net/): Firebird/Interbase 6
• IBM (IBM DB2)
• INFORMIX - IBM Informix Dynamic Server
• MYSQL (http://www.mysql.com/): MySQL 3.x/4.0
• OCI (http://www.oracle.com): Oracle Call Interface
• ODBC: ODBC v3 (IBM DB2 and unixODBC)
• PGSQL (http://www.postgresql.org/): PostgreSQL
• SQLITE (http://sqlite.org/): SQLite 3.x

To see if the PDO driver is available for your database, check phpinfo() and you should have a section named PDO and another pdo_mysql or pdo_sqlite depending on your choice of database. You may also check the available drivers with the static method PDO::getAvailableDrivers().

To enable PDO simply configure enable-pdo and with-pdo_sqlite with_pdo_mysql or whatever database needs supporting by PDO.

Windows users will need to un-comment the appropriate line in php.ini and restart the web server.

Where do I begin?

If you are reading this you are more than likely to have connected to a database using PHP before using a database specific function such as mysql_connect() or pg_connect or, for the truely evolved coder, SQLite. To use PDO with your database you need to have the correct PDO driver installed for it. For the SQLite PDO driver you need to configure PHP with-pdo-sqlite. If you are using a RPM based system there are pdo-sqlite.rpm's available. Before we go any further, lets connect to a database and see what all the fuss is about.

Connect to a database

Every interaction with a database begins with a connection. Regardless of the database you use, you must connect first and establish a database handler. After connecting you your database of choice, much of the PDO methods are similar. This is why PDO is such a powerful and useful tool for PHP. Here we show how to connect to various databases and establish a database handler object that we can use for further interaction with the database.

Connect with PgSQL

As mentioned above, you may have previously tried to connect to a PgSQL database using pg_connect. Here we connect with PDO.

So that was a bit of a no-brainer to start with, we see the use of "new" to create the PDO object followed by the database type username and password. This should be familiar to most people who have connected to a database before using traditional methods.. As we have used try{} and catch(){} we see upon failure that an exception is thrown with the error message "could not find driver". This tells us the PDO_PGSQL driver is not present and needs to be loaded. As noted, an exception is thrown. PDO can handle errors in several ways, more on this later.
How did it connect to the database?
The database connection is handled internally by PDO's __construct() and this represents our database connection.

Lets see what happens if we try to connect to database as we did above without catching the exception and see what happens..

From the above snippet you will get a result something like this below

This is the default behaviour when an exception is not caught, a backtrace is generated and the script is terminated. As you can see, all the information is dumped including the file path and the database username and password. It is the responsibility of the coder to catch exceptions or to deal with the errors using set_exception_handler() function to prevent this happening. More about handling errors and exceptions later.

Connect to SQLite

When PDO is used with SQLite, database creation becomes even easier. Simply specify the path to the database file and it will be loaded. If the database file does not exist, PDO will attempt to create it. Lets see how we go with the same code but change the database to SQLite.

Because the database path does not exist and cannot be created, an exception is thrown, the exception is caught in the catch block and the error message is displayed with $e->Message(). Now that we know how to create a database, we can create tables and INSERT some data.

Another feature of SQLite is the ability to create tables in memory. This can be amazingly helpful if you wish to create tempory databases or tables or even for development code.

We see above that a database is created in memory and a message is displayed to let us know. If the creation of the database failed, a PDO exception would be thrown and the script terminated at that point, passing control to the catch block.

Connect to MySQL

MySQL is the choice of many web developers and will be used as the database of choice for much of this tutorial. Here we see how to connect to a MySQL database.

Connect to Firebird

Often used by developers using windows, Firebird is a good database and connection is just as simple as the examples above.

Connect to Informix

Informix is popular with many windows users also, this example shows how to connect to an informix database cataloged as InformixDB in odbc.ini:

Connect to Oracle

The Oracle database is used by many 'enterprise' companies but these days there are sleeker options. Lets see a simple connection to Oracle

This works fine for a simple Oracle connection. The oracle driver may take two optional parameters, The database name, and the character set. To connect with a database name of "accounts" and a charset of UTF-8 the following code should be used.

Connect to ODBC

There are many connections ODBC can create, here we show how to connect to a MS Access database named accounts. The specified path is c:accounts.mdb.

Connect to DBLIB

Once again a Windows specific database, DBLIB can be used as follows

Connect to IBM

This example shows connecting to an IBM DB2 database named accounts

Close a Database Connection

Up to this point we have seen how to connect to a database using PDO. But of course, we also need to disconnect when we have finished. To close the connection the object needs to be destroyed so that no reference to it remains. This is normally done at the end of a script where PHP will automatically close the connection. However, the connection may be close implicitly by assigning the value of null to the object as seen below.

 

If the database connection fails, the code to assign a null value is never called as the exception throws control to the catch block.

PDO Query

Now that we can open and close a connection to the database with PDO, we can make use of it for what databases are made for, storing and retrieving information. The simplest form of query is the PDO query method. As the name suggests, this is used to perform database queries. Before we begin to query a database, lets create a small database with a table for animals. This will be a MySQL database for use throughout much of this tutorial. Remember, because PDO provides a common set of tools for databases, once we have the correct connection, the rest of the code is the same, regardless of the database you choose. When using PDO to query a database, the function used to do so depends on the statement you wish to send to the database. Below we will see three queries on how to INSERT, SELECT and UPDATE.

INSERT

To gather information from a database, we first need to put some info into it. We use the same code from above to connect and disconnect from the database and the INSERT query is accomplished using the PDO::exec method.

The output of the script above will look like this:

This shows us that we connected successfully to the database and then we have displayed the number of affected rows. PDO::exec returns the number of affected rows if successful, or zero (0) if no rows are affected. This may cause issues if you are checking for a boolean value and why it is recommended using === when to check for type also, as zero (0) may evaluate to boolean FALSE.

The PDO::exec method should be used for SQL statements that do not return a result set. We could use this same method to INSERT many more animals to our database, but a more effecient method would be to use a transaction. This is covered in the section on Transactions.

SELECT

Unlike PDO::exec the PDO::query method returns a result set, that is, a group of information from the database in the form of a PDOStatement object. Our database should look a little like the example in the What is PDO section. Using this we can SELECT information.

From the script above, we can expect the results to look like this:

You will have noticed that we can iterate over the result set directly with foreach. This is because internally the PDO statement implements the SPL traversble iterator, thus giving all the benifits of using SPL. For more on SPL refer to the Introduction to SPL page. The greatest benifit of this is that SPL iterators know only one element at a time and thus large result sets become manageable without hogging memory.

UPDATE

To update a field in a database with PDO we once again use the PDO::exec method in the same manner as we did with the INSERT

Once again we see that the connection is made to the database and one row is affected as now the kiwi has become a true Australian like the rest of the creatures. PDO::exec should be used for all database queries where no result set is required.

FETCH Modes

The section above showed how using PDO::query we can fetch information from the database. The PDO::query method returns a PDOStatement object that can be utilized in much the same was as mysql_fetch_object() or pg_fetch_object(). Of course there are times when an numerical index is needed or an associative index. PDO::query provides for this also by allowing the coder to set the fetch mode for via the PDOStatement object or via PDOStatement::setFetchMode().

FETCH ASSOC

To fetch an associative array from our results the constant PDO::FETCH_ASSOC is used and returns the column names as indexes or keys of the resulting array.

The above code will give a result like this:

PDO has returned the results as a PDOStatement object that we can iterate over directly. The resulting indexes are the names of the fields within the animals database.

FETCH NUM

Like PDO::FETCH_ASSOC, the PDO::FETCH_NUM produces a numerical index of the result set rather than the field names.

The above code will give a result like this:

As you can see above the indexes are now numeric in the result set

FETCH BOTH

There may be times you need to fetch both numerical and associative indexes. PDO::FETCH_BOTH produces a numerical and associative index of the result set so you can use either, or both.

Now we see the results have included both indexes.

FETCH OBJECT

This little gem takes the result set and returns it as an anonymous object or stdClass and maps the field names from the database as object properties with the values the values of stored in the database.

The above code gives the results like this:

The use of the field names as class properties makes integrating results into an Object Oriented envioronment simple.

FETCH LAZY

PDO::FETCH_LAZY is odd as it combines PDO::FETCH_BOTH and PDO::FETCH_OBJ. I am unsure why you would want to do this, but it must have been important enough for somebody to create it. The code below is that of PDO::FETCH_BOTH and is reproduced here for examples sake.

The above code will give a result the same as that of PDO::FETCH_BOTH. Genius!

FETCH CLASS

PDO::FETCH_CLASS instantiates a new instance of the specified class. The field names are mapped to properties (variables) within the class called. This saves quite a bit of code and speed is enhanced as the mappings are dealt with internally.

The code above produces a list of animal types, with the first letter capitalized like this:

The PDO::FETCH_CLASS constant has fetched the results directly into the animals class where we were able to directly manipulate the results, nifty.

PDO provides an alternative to PDO::fetch and PDO::FETCH_CLASS. PDOStatement::fetchObject() will bundle them together to give the same result as shown here.

The above code gives the results like this:

Note that we have called the animals::capitalizeType() method to show that we are in fact working with an instance of the animals class. PDO::fetchObject() will also work as a substitute for PDO::FETCH_OBJ.

FETCH INTO

The PDO::FETCH_INTO constant allows us to fetch the data into an existing instance of a class. Like PDO::FETCH_CLASS the field names are mapped to the class properties. With this in mind, we should be able to replicate the behaviour of PDO::FETCH_CLASS by instantiating the new object when setting the fetch mode. In this instance, the fetch mode is set using PDO::setFetchMode() method.

Once again, the above code produces a list of animal types, with the first letter capitalized like this:

Error Handling

PDO error handling is comes in several flavours. Previously in this tutorial we have have only used the simplest of try{} catch(){} blocks to catch an error in the database connection, but what of other errors? perhaps a field name does not exist? Lets see how we go with a simple error with the previous code.

The above script will produce an error such as this:

This is because there is no error handling. The SELECT statement has a field name 'username' which does not exist and an error is generated by the database. The only default error handling is done with the initial connection. Unless we deal with the error, we have a problem with displaying full path to the world. To deal with this we need to set an attribute to the type of error handling we wish to utilize. The types of error handling are
Exception
Warning
Silent
Lets begin with exception as we have the try{} catch(){} blocks in place already.

Now with the error mode set to Exception the error generated looks like this:

Normally we would not show this type of error to the end user, and the exception would be handled perhaps with message saying No Results Found or something vague, but this does show how we can set the error mode as we wish. To set the error mode to Warning should look easy from here.

Now a different error is displayed.

Here and E_WARNING has been generated and if display_errors is on the error would be seen by an end user. It is hoped that if you are in a production environment this is not the case.

Lastly, there is the Silent mode. As the name suggests, this mode silences the errors so no output is sent from the error. However, it does not stop the code at the point of error and any further errors are still sent.

Now we see the script above produces the following output.

As you can see, the error has been silenced, but the following error has not been attended to, and would need further checks to ensure the value passed to the foreach is a valid arguement.

As we saw with the exception code, the SQLSTATE code was part of the error message. This error code is also available with the PDO::errorCode() method.

The code above shows the error code relevant to the SQLSTATE. This is a five character string as defined by the ANSI SQL standard.

Further information about an error may be gained from the PDO::errorInfo() method. This returns an array containing the SQLSTATE, the error code, and the error message.

With this code, the error information looks like this:

If there is no error, the SQLSTATE will be the only value shown, with a value of 00000.

Prepared statements

What is a prepared statement? A prepared statement is a pre-compiled SQL statement that accepts zero or more named parameters. Ok, so thats my attempt at describing what it is, if you have a better description, let us know.

The SQL is prepared for execution. This is especially useful when using the same statement or query multiple times with different parameters, or field values. The boost in speed is hidden from userland code as the PDO driver allows client and server side caching of the query and meta data. It also helps prevent SQL injection by calling the PDO::quote() method internally.

 

PDO accepts two kinds of parameter markers.
named - :name
question mark - ?
You must choose one or the other, they cannot be mixed.

Lets dive in and have a look at how PDO::prepare and PDOStatement::execute work together.

The above code will produce the following:

Errr, what was that?
What is this name = :variable business
What we have done is bind the variable named $animal_id and $animal_name to the statement. Remember this as many find it difficult to grasp. You are not binding the value of the variable, you are binding the variable itself. Lets change the value of the animal_id after the variable is bound and see what happens..

Now see the results have changed

Because we have bound the variable $animal_id to the $stmt object any change to the value of that varible will be reflected in the statement. This format can be used for both SELECT and INSERT statements. But this is a bit cumbersome for a single query and the above PDO query could have done the job equally as well, so lets run the query multiple times. Ssimply by changing the animal_id and animal_name variables we can run the query over and over without re-writing as it is already 'prepared'.

Now we have run the query 3 times using the same prepared statement. The results look like this:

The second result set is missing as there is no animal named 'kevin', all Australians are named 'bruce'. Note also in the above code we have changed the loop from foreach and PDOStatement::fetchAll() to a while loop using PDOStatement::fetch()As has been mentioned we can run this over and over, but while it is shorter than coding the query over and over, we can also use an array of values!

Transactions

At the beginning of this tutorial was saw multiple INSERT statements to set up the initial database. This works fine but is code intensive and with a database like SQLite a problem arises with file locking for each access. The process can be bundled into a single access by using a transaction. Transactions are quite simple and have the benifit of rolling back changes should an error occur, perhaps a system crash.

A PDO transaction begins with the with PDO::beginTransaction() method. This method turns off auto-commit and any database statements or queries are not committed to the database until the transaction is committed with PDO::commit. When PDO::commit is called, all statements/queries are enacted and the database connection is returned to auto-commit mode.

This example shows how we might set up the animals database used in this tutorial.

Get Last Insert Id

This is a common task required when you need to get the id of the last INSERT. This is done with PDO::lastInserId() method as shown here.

A Global Instance

Ever need a global instance of your database connection? Here we achieve this with the use of the Singleton design patern. The goal of a singleton is to ensure the class has only a single instance and provide a global point of access to it. Here we use the getInstance() method to achieve this. A new instance is only created the first time it is accessed and all subsequent accesses are simply returned the existing instance.

The above code will produce a result like this:

This method of access saves the overhead created when a new instance of an object is called each time it is referenced, so you have have few references to it. Also, if you wish to pass the objects state from one reference to another there is no need to create from the initial state.

Note that the constructor and clone methods have been made private to ensure that an instance of the class cannot be instantiated or cloned.

Conclusions.

If you have got this far you will have seen how to create a connection, prepare a statement and exceute, and to bind Params using bindParam(). This is what most folks will be using to begin with and shows the effectiveness of using PDO to make code more portable. We highly recommend you visit http://www.php.net/manual/en/ref.pdo.php and read up on all that PDO has to offer.

Kaynak

• https://www.phpro.org/tutorials/Introduction-to-PHP-PDO.html