Beruflich Dokumente
Kultur Dokumente
Author Thomas Myer shows experienced PHP developers how to add CouchDB to their
technical toolboxes.
If you're a typical PHP developer, it doesn't take a thorough review of past projects to pick out a
telling pattern: In most (if not all) cases, you're probably getting PHP to talk to a database back end
for all that dynamic data goodness; in 99 percent of those instances, you're using MySQL.
Now, there's nothing wrong with using a relational database. If you're working with highly
structured data with lots of relationships, it's the way to go. You can happily (or unhappily,
depending on your familiarity and comfort with SQL) go through the process of working up
schemas, normalizing data relations, setting up tables, and all the rest.
However, every once in a while, you work on a project where you probably think to yourself,
"Why am I doing all this work?" The project you're working on contains very simple bits of data or
data that's difficult to predict — you might get different data fields on different days or even from
transaction to transaction. If you were to create a schema to predict what's coming down the pike
at you, you'd end up with tables that have lots of empty fields or lots of mapping tables.
For those projects, you need a different approach — something that doesn't involve a relational
database. What you need in these situations is a document-based, schema-free, ad-hoc database
with a flat address space. In short, you need Apache CouchDB.
What is CouchDB?
CouchDB is (according to the Apache CouchDB Web site):
In short, a CouchDB document is an object consisting of named fields. Those field values may
be strings, Boolean values, numbers, dates, ordered lists, or associative maps. Listing 1 shows a
sample resume document.
So far, nothing too far out here if you're used to working with JSON. Even if you aren't, you can
easily map this document to something more comfortable, like a PHP array. In fact, you'll see that
you can use the built-in JSON encode/decode functions to work with CouchDB, or you can use a
more object-oriented path.
To query information from a collection, you can use various comfort-inducing query methods via a
RESTful JSON API. The fact that you're working in JSON simplifies a lot of issues. For one thing,
as a Web developer familiar with JavaScript, Ajax, and JSON, you don't have to know SQL to get
anything done.
Before moving on, it would be good to hit the pause button for a minute to emphasize a few points.
CouchDB isn't a relational database. You've heard me say that, but it's a good idea to emphasize
the point. Don't try to use CouchDB in a relational way, like inserting ID fields that help you make
relationships clear between documents. Instead of creating relationships, stuff the content you
want into your document and keep moving.
Here's something else that CouchDB isn't: an object-oriented database. It's not some kind of native
object, persistent data layer you can use as the underpinning for your object-oriented structures.
Don't do it.
Installing CouchDB
If you're on Mac OS X, the installation process for CouchDB is pretty simple:
Installing in Linux
Your developerWorks editor was able to install CouchDB on his Ubuntu Linux laptop in two
steps:
The software was already in the repository and loaded with no surprises.
This launches the CouchDB server and keeps it running persistently, so it will start up if you
ever restart your Mac.
On a Windows® system, your process will be a bit more convoluted, as you'll need to install
Cygwin, the Microsoft® C compiler, any number of other prerequisites (like cURL, ICU, and
SeaMonkey), download and install the source code for Erlang and Couch, configure those
according to the README files, then do a full installation. This process is described in the
CouchDB wiki (see Related topics). You will also find instructions for Linux®, Berkeley Software
Distribution (BSD), and other environments.
This section shows how to use the cURL command-line tool to issue GET, POST, PUT, and DELETE
requests to CouchDB. Once you've got the hang of the API, a particular PHP wrapper helps you
simplify your development tasks.
The first thing you need to run (again, from a Terminal window) is this command:
curl http://127.0.0.1:5984/. What you should see is a response similar to
{"couchdb":"Welcome","version":"0.10.0"}. This simply tells you that CouchDB is up and
running and which version you're using. If you don't see this message, go back through your
installation and configuration process to get CouchDB up and running.
Now, try listing all the collections set up in CouchDB. Run curl -X GET http://127.0.0.1:5984/
_all_dbs.
If this is a fresh installation of CouchDB, you should see the response [], which means that no
collections or databases are present (the double brackets signify an empty JavaScript array).
Please note that with this cURL command, you use the -X option to specify a GET operation
explicitly.
When you run this, you will see the response {"ok":true}. You now know that you can check for
an ok attribute to make sure of success. Running curl -X GET http://127.0.0.1:5984/_all_dbs
again results in a non-empty array: ["songs"]. Specifically, your CouchDB instance has one
database in it: songs.
Now try to create another database called songs. If you run curl -X PUT http://127.0.0.1:5984/
songs again, you'll get this error message:
So it's easy for you to check for an error attribute to see if any problems have occurred.
Now go ahead and create some documents inside your songs database. True to form, you want
to store some songs in this database, with fields for song title, artist name, and album name. To
create a document, follow this pattern:
curl -X PUT http://127.0.0.1:5984/songs/*id* -d '{ *json_data* }'
Notice that you call the name of your database, followed by some kind of ID (which needs to be
unique not only in this CouchDB instance but preferably across all instances if you can), followed
by your JSON data.
Why the unique ID? You could use a UUID (or a GUID) as a unique ID, or you could create some
kind of natural key that combines various bits of data (for example, the name of a song with
underscores instead of spaces combined with a timestamp), or you can have CouchDB create a
unique ID for you (this is a slow process). Either one of these approaches is good, just don't use
some kind of auto-increment value like you would in the MySQL environment.
{"ok":true,"id":"whatever_you_like","rev":"1-1d915e4c209a2e47e5cf05594f9f951b"}
Notice that I took a very simple approach to the unique ID (using a simplified version of the
song name with underscores instead of spaces). This simple approach is probably OK for right
now. Luckily, the wrappers you'll use in PHP will help you create better IDs. Also notice that I
immediately received a response of "ok" with my document ID and a rev attribute to tell me what
the revision version is set to.
{"_id":"whatever_you_like","_rev":"1-1d915e4c209a2e47e5cf05594f9f951b",
"title":"Whatever You Like", "artist":"T.I.", "album":"Paper Trail"}
If you're following along in Futon, you should be able to click the songs database name and see
a listing for whatever_you_like in the documents list. Clicking that link displays the details of the
document in question, as illustrated in Figure 2.
You're getting the idea — make RESTful requests using JSON, and things happen.
Now, all of this looks pretty good, but if you're a PHP developer, you're wondering how to tie this all
in to something you feel comfortable with. The next section introduces you to some PHP wrappers
for CouchDB.
require_once "./lib/couch.php";
require_once "./lib/couchClient.php";
require_once "./lib/couchDocument.php";
This code serves as your connection code to CouchDB and includes all the relevant classes
that you'll need to work with the database. Go ahead and list all the information related to your
database, as shown in Listing 3.
Next, retrieve a document from your song database. Listing 5 shows the code to do so.
Great, but what if you need to make updates to a document? You can make two different kinds of
updates: by making changes to existing field values or by adding new fields with their own values.
You do this using arrow notation (for example, $doc->new_field), then committing your changes
with storeDoc(). Listing 7 shows the code for updating a document.
Running this code, you can then retrieve the document ID and get back the response in Listing 8.
Notice that the _rev attribute has been incremented to 2-whatever. Before, it was 1-whatever. It's
an easy way for you to tell what revision is there.
What if you want to store a new document in the database? You would instantiate a new object
and use arrow notation to fill in the fields in the document. The code in Listing 9 shows the code to
do so.
try {
$response = $client->storeDoc($song);
} catch (Exception $e) {
echo "Error: ".$e->getMessage()." (errcode=".$e->getCode().")\n";
exit(1);
}
print_r($response);
Conclusion
At this point, you have more than enough information to get started with CouchDB and PHP. It
should be easy for you to create your basic update forms that then allow you to create or update
existing documents in a database. The PHP-on-Couch package also gives you access to other
methods for creating and deleting databases, working with CouchDB views, and more. With any
luck, there's enough information in this article to get you off to a good start.
Related topics
• Visit the CouchDB project site.
• CouchDB: The Definitive Guide is a free online version of the definitive guide for CouchDB.
• Check out the CouchDB wiki for answers to your CouchDB questions.
• Read Installing CouchDB on Windows for instructions for installing the database on the
Windows platform.
• Visit Installing CouchDB on Linux/BSD to find instructions for installing the database on
computers running Linux or BSD.
• Check out The CouchDB API Reference to learn more about the API used in this article.
• Read "Exploring CouchDB" to learn more about what makes CouchDB tick.
• Download the PHP-on-Couch library from Github.
• PHP.net is the central resource for PHP developers.
• Check out the "Recommended PHP reading list."
• Browse all the PHP content on developerWorks.
• Follow developerWorks on Twitter.
• Expand your PHP skills by checking out IBM developerWorks' PHP project resources.
• Using a database with PHP? Check out the Zend Core for IBM, a seamless, out-of-the-box,
easy-to-install PHP development and production environment that supports IBM DB2 V9.
• Visit developerWorks Open and collaborate with some of IBM’s brightest minds in a
community setting.
• Start developing with product trials, free downloads, and IBM Bluemix services.