--no commit message

--no commit message

manual/new/docs/en/working-with-objects.txt

 ++ Dealing with relations
 ++ Component overview
 ++ Fetching objects
++++ Field lazy-loading
+
+Whenever you fetch an object that has not all of its fields loaded from database then the state of this object is called proxy. Proxy objects can load the unloaded fields lazily.
+
+Lets say we have a User class with the following definition:
+
+<code type='php'>
+class User extends Doctrine_Record
+{
+    public function setTableDefinition()
+    {
+        $this->hasColumn('name', 'string', 20);
+        $this->hasColumn('password', 'string', 16);
+        $this->hasColumn('description', 'string');
+    }
+}
+</code>
+
+In the following example we fetch all the Users with the fields name and password loaded directly. Then we lazy-load a huge field called description for one user.
+
+<code type='php'>
+$users = Doctrine_Query::create()->select('u.name, u.password')->from('User u');
+
+// the following lazy-loads the description fields and executes one additional database query
+$users[0]->description;
+</code>
+
+Doctrine does the proxy evaluation based on loaded field count. It does not evaluate which fields are loaded on field-by-field basis. The reason for this is simple: performance. Field lazy-loading is very rarely needed in PHP world, hence introducing some kind of variable to check which fields are loaded would introduce unnecessary overhead to basic fetching.