Last week we put together the main page of Treasure Bag and managed to get it to successfully list all the treasure in our database. You might also remember that we included some useless sorting buttons. Well this week we’re going to get those buttons working!

Sorting With MongoDB in PHP

Unsurprisingly, you sort using a function named sort. The only tricky part is knowing where to use it and what arguments to pass it. MongoDB’s sort function belongs to the cursor class. That’s the same cursor class that is returned by the find function. Remember this line of code?

$cursor = $connection->treasurebag->treasure->find();

That line gave us a cursor pointing at all our treasure. Now we just have to tell the cursor that we want the data sorted. Here’s a quick example of how to sort our data based off of treasure name.

$cursor->sort(array('Name'=>1));

Now let’s take this apart. $cursor->sort tells us that we’re calling the sort function built into the cursor class. We then tell the sort function how to sort by giving it an array holding a key value pair where the key is the attribute we want to sort by and the value is positive 1 for sorting forwards and -1 for sorting in reverse.

Did you catch all that? Here’s a quick question to check. How would you sort a cursor based off of price, starting with the most expensive item?

Do you have your answer ready? Let’s see if you got it right:

$cursor->sort(array('Price'=>-1));

Feel fry to try this out by adding a sort line into your Tresure Bag index.php file. Just make sure that you put it after the call to find (or else you won’t have a cursor to sort) but before the getNext while loop (or else you’ll print the data before sorting it).

Letting PHP Know Which Sort of Sort We Want

Hard coding a sort is OK if you always want the list to show up in the same order. But we want to be able to switch our sort order between name and price. That means we’re going to need some way to mark which sort we want to happen.

The easiest way is probably to just include the kind of sort we want as a variable in the URL and then grab it using the PHP $_GET array. So if we want to sort by name we would change the URL to this:

index.php?sortby=Name

And if we wanted to sort by price we would use:

index.php?sortby=Price

Now instead of hard coding our sort we can change our sort based on the URL. I’m sure you’ve all seen this PHP pattern before:

if(isset($_GET['sortby'])){

    if($_GET['sortby']=='Price'){
        $cursor->sort(array('Price'=>1));
    }
    elseif($_GET['sortby']=='Name'){
        $cursor->sort(array('Name'=>1));
    }
}

Nothing too amazing here. We check whether or not the user gave us a “sortby” variable and then based off of that we choose which kind of sort to run on our cursor. If the user didn’t ask for a sort or asked for a sort we don’t support (sortby=something_else) then we don’t call sort at all and just display the treasure in whatever order the database feels like giving them to us in.

You can test this out by hand typing in the following urls:

No sorting: index.php

Sort by name: index.php?sortby=Name

Sort by price: index.php?sortby=Price

Once you’ve made sure that you can successfully control your sorts by passing URL variables we’re ready for the last step.

Making The Buttons Useful

No MongoDB here. Just a tiny bit of Javascript. We’re going to add an “onclick” event to our buttons that will navigate the user to a URL with the desired sort parameters. Just find the button printing code in index.php and replace them with this:

echo '<button onclick="window.location.href=\'index.php?sortby=Name\'">
                           Sort By Name</button>';
echo '<button onclick="window.location.href=\'index.php?sortby=Price\'">
                           Sort By Price</button>';

If everything worked out you should be able to click on the two “Sort By” buttons to switch between Name order and Price order. If you want to see the treasure in their original non-sorted order just click on the “Inventory” link in the top menu.

All our treasure, sorted by name

All our treasure, cheapest to most expensive

Complete Updated Index.php

 <?php
include('header.php');

$connection = new Mongo();
$cursor = $connection->treasurebag->treasure->find();
if(isset($_GET['sortby'])){

    if($_GET['sortby']=='Price'){
        $cursor->sort(array('Price'=>1));
    }
    elseif($_GET['sortby']=='Name'){
        $cursor->sort(array('Name'=>1));
    }
}

echo '<h2>Inventory</h2>';
echo '<button onclick="window.location.href=\'index.php?sortby=Name\'">
                           Sort By Name</button>';
echo '<button onclick="window.location.href=\'index.php?sortby=Price\'">
                           Sort By Price</button>';
echo '<table><tr><td>Name</td><td>Price</td><td>Type</td></tr>';
while($document = $cursor->getNext()){

    $treasureID = $document['_id'];
    $name = $document['Name'];
    $price = $document['Price'];
    $type = $document['Type'];

    echo "<tr><td>$name</td>
                <td>$price</td>
                <td>$type</td></tr>";

}
echo '</table>';

include('footer.php');
?>

That’s it for sorting. A quick short lesson. Join me next week as we add a whole new page that shows detailed information on a single treasure.

Finally Some Code!

Last week we ran through a couple exercises to help get you familiar with the data structure of MongoDB. This week we’re going to start learning how to access MongoDB using PHP.

Simple Page Template

There are a few chores we need to get out of the way before we can start doing actual database work. Like creating a space on our server for out project. I just dropped a “treasurebag” directory right into my web server’s www folder.

Next, if you remember back to the document design you’ll see that every single page is supposed to have the same same title and navigation menu, so it makes sense to create a single file to hold all this common data.

We’re also going to need some simple style rules to make the application look a little better. We could place this in a separate CSS file, but since we only have a few dozen lines of style rules we might as well just include it in the same page as the header. And since this isn’t a design tutorial I’m not really going to say much about the styling. We give the page a parchment color background to fit the fantasy theme, add some black outlines to tables and center some text. Nothing complex or beautiful but it does make everything a little more readable.

Header

This should all go into a file named “header.php”.

<!DOCTYPE html>
<html>
<head>
    <title>Treasure Bag</title>
    <style>
        body{
            background:#F1F1D4
        }
        #header-wrapper{
            width:800px;
            text-align:center;
            border: solid black 3px;
        }
        #header-wrapper table{
            width:100%;
        }
        #header-wrapper td{
            width:33%;
            text-align:center;
            padding: 20px;
        }

        #content-wrapper{
            width: 800px;
            padding: 20px;
        }

        #content-wrapper table{
            border-collapse:collapse;
            width:500px;
            margin-top:10px;
        } 

        #content-wrapper td{
            border: solid black 1px;
            padding: 5px;
            margin: collapse;
        }
    </style>
</head>
<body>
<div id="header-wrapper">
<h1>Treasure Bag</h1>
<table>
    <tr>
        <td><a href="index.php">Inventory</a></td>
        <td><a href="add.php">Add Treasure</a></td>
        <td><a href="search.php">Search</a></td>
    </tr>
</table>
</div>
<div id="content-wrapper">

Footer

There really isn’t anything we need to display at the bottom of every page, but the header has a lot of HTML elements that never get closed. So we’ll create a very simple footer file that clears all that up so that we don’t have to worry about it.

Please put these three lines into a file named “footer.php”.

        </div>
</body>
</html>

Using Our Template

Using our page template is very simple. You just insert the header, add your content and then use the footer to finish everything up.

<?php
include('header.php');
//YOUR CONTENT HERE
include('footer.php');
?>

Preparing PHP For MongoDB

Now that that’s out of the way we can get back to thinking about databases. But before we can start using MongoDB in our PHP applications we have to install a few extra PHP features. Just like with installing MongoDB itself this process will be a little different for every system and it’s up to you to figure it out. You probably want to start with the official page on MongoDB PHP support.

Connecting to MongoDB With PHP

I’m going to assume at this point that you’ve successfully installed the MongoDB PHP drivers and are ready to finally start coding. You might want to create a “sample.php” file to help you test the next few lines of code. Or you can wait until the end of tutorial when we create the first real page of our Treasure Bag application.

The first step in pulling data out of the database is to connect to it. So any PHP script that plans on talking to MongoDB needs this somewhere near the top:

$connection = new Mongo();

The reason this is so simple is because PHP assumes that you’re running MongoDB on “localhost” and with the default port. So you only have to tell PHP where to find your database if you’re doing something more complex, like trying to connect to a remote database. In that case you’ll have to give PHP a little more information about where to look.

$connection = new Mongo(“mongodb://yourremoteurlhere.com”);

Reading An Entire Database

Now that we have a connection, what do we do with it? How about we dump the contents of the entire “treasure” collection onto our page? After last week’s tutorial there should be at least a few documents in there we can look at.

You might remember that we were able to dump data on the command line by first choosing which database we wanted to use, then choosing a collection and finally calling find:

use treasurebag
db.treasure.find()

The PHP solution is very similar:

$db = $connection->treasurebag;
$db->treasure->find();

Alternatively, you can choose the database and the collection both in the same line like this:

$connection->treasurebag->treasure->find();

That’s not so bad. We’re using arrows instead of dots but otherwise everything looks the same. But wait! There’s one big difference. Using find in MongoDB just immediately dumped all of our treasure documents onto our screen. But in PHP find will give us a cursor, a special object that will give us documents one at a time. To dump everything on the screen we will have to take that cursor and keep asking for more documents by using getNext():

$cursor = $connection->treasurebag->treasure->find()

while($document = $cursor->getNext()){
   print_r($document);
}

If you’ve been following along then visiting your “sample.php” page should show you a big lump of text with whatever data is still in your “treasure” collection from the last tutorial. If you get an error or just aren’t seeing anything try these troubleshooting tips:

• Make sure there is data in the “treasure” collection of the “treasurebag” database by firing up the Mongo console tool like we talked about last week.
• Make sure that you remembered to connect to MongoDB before trying to create the cursor. $connection = new Mongo() needs be the first thing in your script!
• Double check your spelling for database and collection names. One tiny typo is all it takes to start looking through a blank database instead of the real “treasurebag” database.

Accessing Individual Pieces Of Data

Just dumping our documents onto the page isn’t very practical. What if we only want to see part of a document? Like the name of a treasure or its price? The answer is pretty easy and I bet most of you figured it out just by looking at the print_r output from the example above.

For those of you who didn’t, remember that a MongoDB document is made up of key value pairs. To get a specific piece of data you just ask for the key you want and get back the value stored with it:

$document['key'];

So if you want to print out the name of an item all you have to do is:

echo $document['Name'];

Or if you need to store a price for later:

$price = $document['Price'];

Creating the Treasure Bag View Page

That’s everything you need to know to create the main “index.php” page of our Treasure Bag application. We have the page template, the MongoDB connection and we know how to use the cursor. All that’s left is to put it together. I’ve included my complete solution right below but you might want to try creating your own “index.php” page first. If you look at the design document you’ll see that we want to put all the treasures into a table that shows their name, price and type. And don’t forget to use our header and footer files!

Anyways, here’s my “index.php” file, which I saved to the same directory as “header.php” and “footer.php”:

<?php
include('header.php');

$connection = new Mongo();
$cursor = $connection->treasurebag->treasure->find();

echo '<h2>Inventory</h2>';
echo '<button>Sort By Name</button>';
echo '<button>Sort By Price</button>';
echo '<table><tr><td>Name</td><td>Price</td><td>Type</td></tr>';
while($document = $cursor->getNext()){

	$name = $document['Name'];
	$price = $document['Price'];
	$type = $document['Type'];

	echo "<tr><td>$name</td>
                  <td>$price</td>
                  <td>$type</td>
              </tr>";

}
echo '</table>';

include('footer.php');
?>

Screenshot of Success!

It’s Alive!

Let’s walk through this screenshot really quick. Up at the top you can see the title and the navigation links from “header.php”. Underneath that we have the actual inventory table created using data from our MongoDB cursor. You’ll also notice that we added two buttons for sorting right above the table. Right now they don’t actually do anything, but our design document tells us that we need them for later so we might as well add them now.

And that’s it for this week! Try using the MongoDB console to add new items to the “treasure” collection and then refresh “index.php” to see them show up in all their glory. Then tune in next week as we make the sort buttons actually sort and add a page for viewing item details.

BONUS!

If you’ve been following along with the bonus activities you should have designed a character view page and have a character collection with some sample data. Create a “characterlist.php” file that connects to this collection and puts all your characters into a table or list. You will also probably want to edit “header.php” to include links to this page. You might have to alter some of the style rules to make the menu work well with four links instead of three, but I’m sure a bonus obsessed programmer like you can handle it.

Installing MongoDB: You Can Do It!

Before we can start working with MongoDB we need to install it. The installation process is a little different for every system. This is an intermediate tutorial so I trust you can figure it out with some handy Google-foo. This might be a good place to start.

On my particular Linux system it was as easy as:

sudo apt-get install mongod-server

MongoDB comes with two tools. The first is the database server itself. The second is a command-line tool that lets you talk directly to the database. This command-line tool is going to be the focus of this week’s tutorial.

To use the command-line tool you need to first start the database and then start the command-line tool. On some systems the database server might start itself automatically. Once again: intermediate level tutorial. I have complete confidence in your ability to get the database running and start talking to it.

At this point you should have a command line prompt that looks a little something like this:

MongoDB shell version: 2.0.4
connecting to: test
>

Good job! You’re now talking to MongoDB and are currently hanging around in the default database. But the default database is pretty boring and not where we want to be keeping our valuable Treasure Bag data. We’re going to want to create a new database.

Creating Databases In MongoDB

Creating new databases in MongoDB is easy. Almost too easy. Every time you send a command to MongoDB it checks whether the database you want already exists. If it doesn’t then it creates it for you.

For example, you switch between databases with the use command, like so:

use treasurebag

If the treasurebag database already exists this will drop us into it. If it doesn’t exist, this function will create it and then drop us into it. Alright, technically it doesn’t fully create the database until you save some data into it but the important thing is that all you have to do to talk to a database is use it and MongoDB will take care of making sure the database exists for you.

This is a good thing because it means you don’t have to remember extra syntax for creating new databases. You just ask for what you want and one way or another you’ll get it. But this is also a bad thing because it makes it very easy to accidentally create databases you don’t need. All it takes is a typo:

use tresurbag

Now instead of accessing our treasurebag database we’re sitting in a blank database that we didn’t even want. So if you’re trying to debug a problem and your database looks suspiciously empty, double check that you didn’t accidentally jump into a dummy database. Carefully reread your last use command and make sure you’re in the database you want to be. If not, then switch!

The Shape of MongoDB

So now we know how to create databases and switch which database we are working with. But what exactly does a MongoDB database look like? Well, MongoDB databases are split into “collections” with unique names. Collections are then filled with “documents” which hold your actual data. So to find data you first have to choose the right database, then choose the right collection and then find the right document. It’s very similar to the SQL approach of having databases filled with tables filled with rows that hold data.

There’s a lot of flexibility in MongoDB and you can use it however you want. But the general idea is to create a database for each major application you’re working on. In our case, Treasure Bag is going to get its own database. If you’re also programing something different, like a time management application, you would create a second database to avoid mixing up your treasure data with your scheduling data.

Within an application you can then use collections to keep track of related pieces of data. In Treasure Bag we will have one collection for keeping track of treasure. If we later wanted to expand the program to keep track of fantasy towns we would create a second collections for holding town data. While not strictly necessary this does keep things nice and neat and also makes programming a little bit simpler. Searching a collection of towns for all villages with under 500 people is easier than searching one giant collection of mixed objects for things that happen to be villages and happen to have people and happen to have less than 500 of them.

Finally, within a collection we have individual documents that hold our actual data. Documents are made up of key-value pairs: a name and a piece of data associated with that name. Population: 500. Color: Blue. Favorite Things: Roses, Kittens, Gumdrops. You get the idea.

Putting Data Into The Database

Theory is all well and good, but we’re here to practice. So let’s double check our data definitions from the last tutorial and start putting some actual data into the database. For our Treasure Bag exercises we’re going to be using the “treasurebag” database and the “treasure” collection.

Inserting data via the command-line follows a predictable pattern. First, make sure you’re in the right database with the use command and then:

db.collectionname.insert({ key1 : value1, key2 : value2, key3 : value3 })

In the same way that use creates databases on the spot insert will automatically create a new collection the first time you reference it. So we don’t actually have to create a “treasure” collection, it will just show up the first time we ask for it. Let’s give it a try with a very simple treasure: The Precious. It’s attributes look like this:

Name: The Precious

Price: 10000

Type: Ring

Special Attribute: Invisibility

Plugging this in to the pattern above we get:

db.treasure.insert( { “Name” : “The Precious”, “Price” : 10000, 
“Type” : “Ring”, “Special Attribute” : “Invisibility” } )

MongoDB is very quiet about inserts. Hit enter and it won’t look like anything happened at all. So… how do we know if it worked? Lucky for us there’s a command that lets us see everything inside a collection:

db.collectionname.find()

Or in our case:

db.treasure.find()

If everything has gone well you should see something a lot like this:

{ "_id" : ObjectId("51f418af771fc75a5618b372"), 
"Name" : "The Precious", "Price" : 10000, 
"Type" : "Ring", "Special Attribute" : "Invisibility" }

So it looks like our treasure did make it into the database. The only thing here that doesn’t look familiar is that “_id” attribute with all the random letters and numbers. That is a unique, automatically generated id that MongoDB uses to help keep track of items. Don’t worry about it too much, but don’t forget about it entirely either. We’ll be using it in future tutorials.

Since adding a ring went so well, why don’t we try something else? Like the Staff of Defenestration?

Name: Staff of Defenestration

Price: 10,000

Type: Staff

Charges: 23

Spells:

• Telekinesis
• Feather Fall

This introduces an interesting new feature. The “Spells” attribute doesn’t have just one value, it has two. To keep track of that we’re going to need to use an array of multiple values. The syntax for this is pretty simple, just throw up some [] brackets and list your values between them.

db.treasure.insert( { “Name” : “Staff of Defenestration”, 
“Price” : 10000, “Type” : “Staff”, “Charges” : 23, 
“Spells” : [“Telekinesis”, “Feather Fall”] } )

Try using db.treasure.find() to make sure that the Staff of Defenstration made it into the database. And then try inserting some new treasures of your own. Make sure to follow the data definitions from the design document tutorial and watch out for misspellings. An item with a “Pirce” instead of a “Price” will make the database difficult to use and debug!

Searching The Collection

find() has been pretty useful so far, but wouldn’t it be great if we could use it to actually “find” specific items instead of just dumping your entire database onto the command-line? Yes it would! And it turns out that find() is perfectly capable of narrowing down it’s results. All you have to do is give it some key-value pairs to work with.

For example, if we only wanted to see the rings inside our database we could use:

db.treasure.find( { “Type” : “Ring” })

We can get even more specific by using more than one key-value pair. Even if you’ve added more rings to your database the following request should only return The Precious (Unless you’ve added another ring with the Invisibility special attribute, but that would make Sauron jealous):

db.treasure.find( { “Type” : “Ring”, “Special Attribute” : “Invisibility” } )

Removing Items

Putting items into a database and looking at them later isn’t enough. Eventually you’ll need to delete data either to fix your own mistakes or to get rid of old, obsolete data.

But if you can handle find you can also handle remove. Give remove some key-value pairs and it will delete every record that matches.

For example, you can delete every wand in the datbase:

db.treasure.remove( { “Type” : “Wand” } )

Or you can narrow it down by using more unique data

db.treasure.remove( { “Name” : “Orc Poker” } )

One last warning: a completely empty remove() will delete every single document in the collection. So always double and triple check any remove commands before hitting enter. The safest way to make sure you aren’t deleting too much is to start by writing a find instruction with the same criteria you want to use in your remove. That will give you a quick peek at what data you’re about to delete.

Congratulations! You Completed This Week’s Lesson

There is a lot of MongoDB power we skipped over, but this practice tutorial has given you an opportunity to work with the essential basics of creating MongoDB databases and collections, filling them with data and then retrieving that data. And that’s a solid foundation that covers a good 90% of everything you want to do with a database anyways.

Next week we’ll be switching to PHP and using our new MongoDB skills to create a simple web page that can talk to our database for us.

Bonus!

Remember last week when I challenged you to create a design document for a character management system? Well now you know enough MongoDB to take the next step. Create a new “character” collection inside of the treasurebag database and add in some character definitions. Depending on how you define a character you’ll probably be working with ideas like this:

db.characters.insert( {“Name” : “Rayeth”, 
“Class” : “Dragon Slayer”, “Level” : 19 } )

Brief Introduction to MongoDB

MongoDB is a relatively new database system that’s getting plenty of attention among developers. It’s big claim to fame is that it is schema-less and very flexible.

With a classic SQL database you have to define a scheme, a set of rules describing exactly what kind of data goes into the database. Ex: A student database might require that every student record have a first name, last name and birthday. If you change your mind and decide you also want to include GPA you have no choice but to go back and redefine the database. And if some students have middle names but some don’t you have to decide between ignoring everyone’s middle name or creating a middle name value that sometimes gets left blank.

MongoDB, on the other hand, gives you the freedom to put whatever data you want into the database whenever you want. Toss a bunch of students into a database and then glue on GPAs later without breaking a sweat. You can give some students a middle name without touching the others. You can even mix and match completely unrelated records. Want to stick a spaghetti recipe in the middle of your student database? With MongoDB you can! (Note: mixing student records and cookbooks together in one database is bad software design and actually sort of creepy. Just because you can do it doesn’t mean you should.)

Of course, MongoDB isn’t a miracle solution and classic SQL databases are still an efficient choice for a lot of applications. But it’s always nice to have more tools and more options so if you’ve got the time it’s worth giving MongoDB a look.

The Practice Project: Treasure Bag

There are plenty of great books and websites out there that will teach you the basics of MongoDB. But in my opinion you don’t really understand a technology until you’ve built at least one program with it. So over the next few weeks of free time I plan to write a very simple sample MongoDB web application and invite you all to join in with me.

The trick here is that we want a project that really shows off the flexibility of MongoDB and lets us practice with all the major features of the database. We want to avoid boring things like employee registries or phone books where all the data is similar. If you’re going to write something like that you might as well use MySQL.

Which is why I decided on writing a fantasy game themed application that I call “Treasure Bag”. This simple program will let a user keep track of the treasure he finds in a generic Dungeons and Dragons style game.

This is a great project for MongoDB because treasure items are similar enough you probably want to keep their data all in one place while being different enough that designing a SQL database for them would be difficult. For example, both Weapons and Wands have a price and a name but the weapon is going to have information about combat statistics while the wand is going to have extra information about magic spells. With SQL we would probably have to create a separate table for each type of item, but with MongoDB we can keep them both in one collection.

Tune in next time to follow along as we design the application.

I use a Linux emulator at work, but I’ve never actually installed the OS on a physical machine. But now that my new computer has rendered my old computer redundant I figured I would remedy that deficiency and turn my spare laptop into a dedicated Linux wonderland.

For the most part the install went smoothly but there were two big issues that I thought I would document for anyone else trying to install Ubuntu 12.04 on a Dell Inspiron 1521.

Enabling Wireless Networking

Ubuntu 12.04 didn’t recognize my built-in wireless at first. There were no options to turn on wireless or scan for networks or anything.

The easiest way to fix this is to run the “Additional Drivers” program that comes with Ubuntu. In fact, Ubuntu will probably prompt you to run this program the first time you start your system.

The only trick here is that “Additional Drivers” won’t work without an Internet connection, and at this point the wireless still doesn’t work. Fortunately, wired networking does work so all you have to do is grab an Ethernet cable and physically plug your computer into your network.

Once you are physically connected to the Internet you can run “Additional Drivers” which should automatically find the software Ubuntu needs to enable and run your wireless. At that point you can ditch the cabling and reconnect to your network via wireless.

Ubuntu Endlessly Loops While Trying To Wake Up From Suspend

Normal laptop behavior says that the computer should conserve power by going into suspend mode when the user folds the screen down and then waking up when the user opens it back up. But when I tried this I found Ubuntu 12.04 getting stuck in a loop where it would try to wake up, flash some text across the screen, briefly cut power to the screen and then start all over. This doesn’t happen every time, but still often enough to be a nuisance.

Update: I originally thought this problem was somehow tied to having wireless networking active, but after further testing the computer seems to have the same chance of hanging versus properly suspending regardless of whether wireless is active or not. The problem is rare enough that I can currently live with it but I hope to find the real cause of and solution to this problem in the near future.