Now, let's get familar with the key concepts, tools and classes that form the backbone of the Doctrine ORM. +++ Doctrine Query Language The Doctrine Query Language (DQL) is an object query language. It let's you express queries for single objects or full object graphs, using the terminology of your domain model: class names, field names, relations between classes, etc. This is a powerful tool for retrieving or even manipulating objects without breaking the separation of the domain model (field names, class names, ..) from the relational model (table names, column names, ...). DQL looks very much like SQL and this is intended because it makes it relatively easy to grasp for people knowing SQL. There are, however, a few very important differences you should always keep in mind: Take this example: from Employee emp join emp.tasks t where emp.salary < 40000 The things to notice about this query: * We select from **classes** (Employee) * We join along **associations** (emp.tasks) * We can reference **fields** (emp.salary) * There is no join condition (ON x.y = y.x). The associations between your classes and how these are expressed in the database are known to Doctrine (You need to make this mapping known to Doctrine, of course. How to do that is explained later.). **DQL expresses a query in the terms of your domain model (your classes, the attributes they have, the relations they have to other classes, etc.)** It's very important that we speak about classes, fields and associations between classes here. 'Employee' is **not** a table / table name . It may be that the name of the database table the Employee class is mapped to is indeed named Employee but you should nevertheless adhere to this differentiation of the terminology. This may sound nitpicky since, due to the ActiveRecord approach, your relational model is often very similar to your domain model but it's really important. The column names are rarely the same as the field names and as soon as inheritance is involved the relational model starts to diverge from the domain model. You can have a class Employee that is in fact mapped to several tables in the database. At this point it should be clear that talking about "selecting from the Employee table" is simply wrong then. And as Doctrine development continues there will be more features available that allow the 2 models to diverge even more. +++ Metadata Mapping [todo: explain what this is and how it's done in doctrine. mention the alternative approach (code generation)] +++ Classes The following is a list of the most important classes of the Doctrine ORM and their responsibilities. ++++ Doctrine::ORM::Entity The Entity class is the "ActiveRecord" base class. A class needs to extend this base class in order to enable Doctrine to manage it's persistence. The Entity class provides extending classes with the usual ActiveRecord interface (save()/delete()) and a lot of other methods that are useful in the basic maintenance of the persistent state. ++++ Doctrine::ORM::Mapper The Mapper class is the gateway to the main mapping facilities and functionality. If you're going a straight ActiveRecord route you will never have to deal with that class. However, if you don't want to bloat your Entity classes with static finder methods, you can use custom mapper classes that act as your Entity repositories that provide an OO interface for retrieving Entities in the terms of the language of your domain. As you will see, such custom mapper classes come with a lot of functionality out of the box without any custom coding. This is because all custom mapper classes need to inherit from Doctrien::ORM::Mapper [Link to custom mapper docs here?]. ++++ Doctrine::ORM::EntityManager The EntityManager class does exactly what the name implies. It manages the lifecycles of all Entities used during the processing of one HTTP request. The EntityManager is the entrypoint for a lot of ORM related functionality. One exception is the usage of the ActiveRecord interface on your Entities, the EntityManager is then involved behind the scenes. One of the key features you'll most likely use the most is the creation of object queries using DQL (Doctrine's OQL implementation). An EntityManager needs a database connection to operate on (An instance of Doctrine::DBAL::Connection). ++++ Doctrine::ORM::Query [coming soon] ++++ Doctrine::ORM::ClassMetadata [coming soon]