What is a Proxy in Doctrine 2?

I just finished reading all the Doctrine 2 documentation, I started my own sandbox, I understood most of the principes, but there is still a question and I couldn't find any complete explanation in the doc.

1. What are Proxy classes?
2. When should I use them over entities?

As far as I understand, proxy classes add a layer to let you add some other features to your entities, but why use a proxy instead of implementing the methods themselves in the entity class?

>### UPDATE >This answer contains wrong information about differences between proxy objects and partial objects. See @Kontrollfreak's answer for more details: https://stackoverflow.com/a/17787070/252591

---

Proxy objects are used whenever your query doesn't return all data required to create an entity. Imagine following scenario:

@Entity
class User {
     @Column protected $id;
     @Column protected $username;
     @Column protected $firstname;
     @Column protected $lastname;

     // bunch of setters/getters here
}

DQL query:

SELECT u.id, u.username FROM Entity\User u WHERE u.id = :id

As you can see this query doesn't return firstname and lastname properties, therefore you cannot create User object. Creation of incomplete entity could lead to unexpected errors.

That's why Doctrine will create UserProxy object that supports lazy loading. When you'll try to access firstname property (which is not loaded) it will first load that value from database.

---

>I mean why should I use a proxy ?

You should always write your code as if you didn't use proxy objects at all. They can be treated as internal objects used by Doctrine.

>Why the lazy loading can't be implemented in the Entitiy itself?

Technically it could be but take a look at some random proxy object's class. It's full of dirty code, ugh. It's nice to have a clean code in your entities.

>Can you provide me an use case?

You're displaying a list of latest 25 articles and you want to display a details of the first one. Each of them contain a large amount of text, so fetching all that data would be a waste of memory. That's why you don't fetch unnecessary data.

SELECT a.title, a.createdAt
FROM Entity\Article a
ORDER BY a.createdAt DESC
LIMIT 25

$isFirst = true;
foreach ($articles as $article) {
    echo $article->getTitle();
    echo $article->getCreatedAt();

    if ($isFirst) {
        echo $article->getContent(); // Article::content is not loaded so it is transparently loaded 
                                     // for this single article.

        $isFirst = false;
    }
}

Proxies

A Doctrine proxy is just a wrapper that extends an entity class to provide Lazy Loading for it.

By default, when you ask the Entity Manager for an entity that is associated with another entity, the associated entity won't be loaded from the database, but wrapped into a proxy object. When your application then requests a property or calls a method of this proxied entity, Doctrine will load the entity from the database (except when you request the ID, which is always known to the proxy).

This happens fully transparent to your application due to the fact that the proxy extends your entity class.

Doctrine will by default hydrate associations as lazy load proxies if you don't JOIN them in your query or set the fetch mode to EAGER.

---

Now I must add this because I don't have enough reputation to comment everywhere:

Unfortunately, Crozin's answer contains misinformation.

If you execute a DQL query like

SELECT u.id, u.username FROM Entity\User u WHERE u.id = :id

you won't get a (proxied) entity object, but an associative array. So it's not possible to lazy load any additional properties.

With this in mind, one comes to the conclusion that the use case example won't work either. The DQL would have to be changed to something like this in order to access $article as object:

SELECT a FROM Entity\Article a ORDER BY a.createdAt DESC LIMIT 25

And the property returned by getContent() would have to be an association in order not to load the content properties of all 25 entities.

---

Partial Objects

If you want to partially load entity properties that are not associations, you have to tell this Doctrine explicitly:

SELECT partial u.{id, username} FROM Entity\User u WHERE u.id = :id

This gives you a partially loaded entity object.

But beware that partial objects are not proxies! Lazy Loading doesn't apply to them. Therefore, using partial objects is generally dangerous and should be avoided. Read more: Partial Objects — Doctrine 2 ORM 2 documentation