Setting up CodeIgniter 2 with Doctrine 2 the right way
So you've discovered the awesomeness of CodeIgniter and you need an ORM. You've read about people around StackOverflow and the CodeIgniter forums recommending Doctrine as an object mapper. You've tried and tried but Doctrine and CodeIgniter are just not playing nicely together. Well http://www.phpandstuff.com/ has a stupendous tutorial... for CodeIgniter < 2.0 and Doctrine < 2.0. We need something more recent, eh?
Well, I walked the same rocky road and decided to make my own tutorial. Yah, yah, there's already a bunch out there. But they either suck or don't apply to CodeIgniter 2 or Doctrine 2. Mine doesn't suck. I hope.
So for future reference, here are the versions I am working with during this tutorial, but similarly versions should work just fine:
- CodeIgniter 2.1.0
- Doctrine 2.2.1
- Also, I am running Apache 2.2.20, PHP 5.3.6 (with APC), MySQL 5.1.58, all on Ubuntu Server 11.10.
- I am assuming you already have a MySQL database (with valid a user) set up.
The following versions have been tested to make sure they fully work with this tutorial:
- CodeIgniter 2.1.0 and Doctrine 2.2.1
- CodeIgniter 2.0.2 and Doctrine 2.0.5
If you want to work with a different version of CodeIgniter or Doctrine, this tutorial should still be totally fine as long as the version of CodeIgniterand Doctrine are version 2.x.x! You may have to change the paths of downloads a bit (i.e. changing a
CodeIgniter_2.1.0.zip in a URL to
CodeIgniter_2.0.2.zip, but everything else will be exactly the same. If you can't handle that, I'd recommend firing up a WordPress instance and going from there...
Also, here are some names I will be using throughout the tutorial. Replace them with whatever paths or names that are relevant to your project.
- Project Name: Emma Watson Shrine
- Project Directory:
I am going to try to make this as easy on you as possible, so I will give all of the steps necessary to get this stack up and running. In other words, you shouldn't even have to read the Doctrine and CodeIgniter documentation, although it is HIGHLY recommended.
"And away we go..."
Download and Configure CodeIgniter
- Download the CodeIgniter archive, extract it, and move it to the location that you'd like your project to reside.
- Make sure your project's directory has proper permissions. This kind of depends on your server's setup, but I set my project's directory permissions to 755. If you're not sure about this, skip to the next step. It's most likely that the permissions are okay if you used an FTP program to upload the CodeIgniter files.
- CodeIgniter still needs some configuration, but it's running! When you view your project directory in your browser, it should look something like this: screenshot.
- Now let's take some time to configure CodeIgniter. Don't worry, it's really quick!
- Open CodeIgniter's config file in the text editor of your choice.
- Set the base URL.
- Open CodeIgniter's database config file.
- Set up the database information. This is the database that Doctrine will use.
- Download the Doctrine archive, extract it, and move it to your CodeIgniter application's library directory. Keep in mind that the archive you download has two sub-directories:
Doctrinedirectory is what you actually need.
Add Doctrine as a CodeIgniter library
This is when things start getting a bit more confusing. So read carefully!
- Go to your CodeIgniter applications's library directory. We need to make a PHP class that will help our CodeIgniter controllers talk use Doctrine's all-powerful Entity Manager. Create a new file at the following path and open it up in a text editor:
- Paste this code in. Read the in-code comments for explanation, if you want to learn a thing or two. Here's a link to Doctrine.php if you just want to download it to the right location.
- Open CodeIgniter's autoload config file.
doctrineto the autoloaded libraries.
- You should be able to view your project directory in your browser at this point without any errors coming up. If you have, double back and make sure you've followed all the steps. Furthermore, the page should look exactly as it did before you added Doctrine as a library.
Add Models to DoctrineFrom here on, what you need to do really depends on what you would like your website to do. Since I am making a shrine dedicated to Emma Watson, I think I'll need two models (represented by two tables): a
Userobject and an
Userobject will hold information about an individual user. The
Articleobject will have an author (linking to a
Userobject) and other information for displaying an article. Something we need to get straight first is that the models generated by Doctrine are going to be different than CodeIgniter models (i.e. they will not extend the CI_Model class).
- Create a Mappings directory in your application’s models directory.
- Create some YAML mapping files and put them in the Mappings directory. How to do this is outside the scope of this tutorial, but I will provide mine as examples. Here is a link to the Doctrine documentation on how to format these file. Make sure the mapping files have the ".dcm.yml" file extension and the "Entities." prefix. The extension tells Doctrine that this file is a YAML mapping file, and the prefix tells Doctrine to put the models in the
- When declaring the name of your object, make sure to prefix the name with
Entities\to put it in the Entities namespace.
- Here is the YAML file for my
Userobject. The file name should be
- And here is the YAML file for my
Articleobject. The file name should be
- When declaring the name of your object, make sure to prefix the name with
- Go back to the models directory and create two more directories: "Entities" and "Proxies". Proxies is the directory that will hold the proxy classes that Doctrine uses. If you're really smart, you should be able to figure out what the Entities directory is for. Since this is the Internet, I think it's safe to assume that I should explain it to you. It's the directory that holds the Entities!
Configure Doctrine Command Line ToolTo use Doctrine, you need set up the command line tool, which helps you with a lot of tasks, like automatically creating the schema in your database, generating proxy classes, etc.
- Go to your application's
applicationdirectory and create a file called
doctrine-cli.php. This is a PHP file that you will need to run through the command line PHP program. Alternatively, download this file to your application directory and skip the next step. Make sure you change the
APPPATHdefinition in the code to fit your needs!
- Put the following contents in your
doctrine-cli.phpfile. As I said above, make sure you change the
APPPATHin the code definition to fit your needs!
- Now run this script through the PHP command-line and should see a list of commands available to you. The output should look something like this:
Setup Entities, Proxies, and Database SchemaWe're getting close here. Really the last thing you need to do before you can jump into developing your Facebook killer.
- For all of the steps in this section, you'll need to simply call the Doctrine command line tool that you got working in the previous section. The order of these steps does matter!
- Let's go ahead and generate the entity classes. Note that we are creating them in the models directory. Doctrine detects that they are in the
Entitiesnamespace and automatically puts them in the Entities subdirectory. Keep in mind that these entity classes come with getters/setters for all of the fields you defined in your YAML file but can be modified to add custom methods and such.
- Now the proxy classes.
- If you've tried this before and your database is not empty, you'll need to do this step. Otherwise, skip it.
- And finally, let's create the database tables for Doctrine to store our objects in.
Using Doctrine in a CodeIgniter ControllerBelieve it or not, you've just made it through all the hard stuff. With all that stupid configuration stuff out of the way, you can get to coding. Yay! Since we added Doctrine as an autoloaded library, we don't even need to fool with loading Doctrine every time you create a new controller. Also, the library file (
libraries/Doctrine.php) has a auto-load call that makes it so all of the entities you put in the
models/Entitiesdirectory are automatically available to your controllers! If you know what you're doing, go ahead and leave this page. Get coding! Otherwise, I'm going to give you a few code samples so you can start using Doctrine.
How do I create a new entity and save it into the database?Easy.
How do I get an entity from the database?Child's play.
Can I add custom methods to my entities?Yes!