The new programming model of 2.0

Note: Any code snippets here are completey out of context and have the sole purpose of showing the common API and it's usage.
Note: This document is subject to frequent changes.

Key Concepts

Entity
Base class for all classes that want to be managed by Doctrine.
Defined by their identity. All Entities need an ID (can be a composite ID).

class Article extends Entity
{
    public static function initMetadata($mapping)
    {
        // specify the mapping of regular columns to fields
        $mapping->mapColumn('article_id as id', 'integer', 4, array(
                'primary' => true, 'generationType' => 'auto'));
        $mapping->mapColumn('topic', 'string', 100);
        $mapping->mapColumn('text', 'string');

        // use a custom repository for articles
        $mapping->setCustomRepository('MyArticleRepository');

        // specify the mapping of associations to fields
        $mapping->oneToMany('Comment as comments', array(
                'local' => 'id',
                'foreign' => 'user_id',
                'owningSide' => 'Comment',
                'fetchType' => 'lazy', // eager/lazy/none(default)
                'cascade' => 'all', // all/none(default)/save/delete/refresh
                'indexBy' => 'commentId',
                'orderBy' => 'date desc',
                'optional' => false  // defaults to true
                ));

        // some frequently used, named queries
        $mapping->addNamedQuery("articles.of.author", "select a.* from Article a where a.author.id = ?");
    }
}

EntityManager?
Manages the overall lifecycle of Entities on one database connection.
Main entry point for ORM-related functionality (createQuery(), createNativeQuery(), getRepository(), ...)

$conn = new Connection($dsn);
$em = new EntityManager($conn);
$query = $em->createQuery("select u.* from User u");

EntityRepository?
Serves as a repository for Entities.
Provides lots of predefined finder methods.
Can be extended to create custom repositories for certain Entities.

$repos = $em->getRepository("User");
$someUser = $repos->find(1);

Query
Represents a DQL query.
Provides a fluent interface to build/enhance the query.

$users = $em->createQuery("select u.* from Users u")->execute();
...
$query = $em->createQuery();
$users = $query->select("u.*")->from("Users u")->execute();
...
$articles = $em->createNamedQuery("articles.of.author")->execute(array(1));

Bootstrapping

The new bootstrapping procedure of the Doctrine ORM looks as follows:

...
use Doctrine::ORM::EntityManagerFactory;
use Doctrine::Common::Configuration;
use Doctrine::Common::EventManager;
use Doctrine::Common::Event;

// get a factory
$emf = new EntityManagerFactory();
// configure the factory
// in general this is optional, however, most of the time
// you will have some custom configuration and event listeners.
$config = new Configuration();
$config->set('queryCache', new ApcCache());
$config->set('metadataCache', new ApcCache());
$eventManager = new EventManager();
$eventManager->registerEventListener(new MyListener(), array(Event::preDelete, Event::postDelete));
$emf->setConfiguration($config);
$emf->setEventManager($eventManager);
// options for the EntityManager
$options = array(
    'driver' => 'mysql',
    'user' => 'john',
    'password' => 'wayne',
    'database' => 'mydb'     
);
// create manager
$em = $emf->createEntityManager($options, 'myEM');

//...
// Store $em in a registry or register it with a DI container or inject
// it manually into your controller chain or whatever you use.
// Alternatively, when using multiple EntityManagers (and thus, several database connections)
// store the EntityManagerFactory and use  $emf->getEntityManager('myEM')

The EntityManagerFactory? is the central bootstrapping component. It creates the EntityManager?, shared resources and uses a ConnectionFactory? to retrieve a Connection object and then wires all this together. It also makes sure that the DBAL (Connection) & ORM (EntityManager?) use the same Configuration and EventManager? and other shared instances.