Revamped object model using object handles
===========================================

Background
----------

In the Zend Engine 1.0 (and its predecessor the PHP 3 scripting
engine) the object model's design is that instantiated objects are
language values. This means that when programmers are performing
operations, such variable assignment and passing parameters to
functions, objects are handled very similarly to the way other
primitive types are handled such as integers and strings.
Semantically this means that the whole object is being copied. The
approach Java takes is different where one refers to objects by handle
and not by value (one can think of a handle as an objects' ID).

Need
----

Unfortunately, the approach taken up to now has severely limited the
Zend Engine's object oriented model, both feature and simplicity
wise. One of the main problems with the former approach is that object
instantiation and duplication is very hard to control, a problem which
can not only lead to inefficient development but also often to strange
run-time behavior. Changing the object model to a handle oriented
model will allow the addressing of many needs such as destructors,
de-referencing method return values, tight control of object
duplication and more.

Overview
--------

The proposed object model is very much influenced by the Java
model. In general, when you create a new object you will be getting a
handle to the object instead of the object itself. When this handle is
sent to functions, assigned and copied it is only the handle which is
copied/sent/assigned. The object itself is never copied nor
duplicated. This results in all handles of this object to always point
at the same object making it a very consistent solution and saving
unnecessary duplication and confusing behavior.

Functionality
-------------

After this change the basic use of objects will be almost identical to
previous versions of the scripting engine.  However, you won't bump
into awkward and confusing copying & destructing of objects.  In order
to create and use a new object instance you will do the following:
$object = new MyClass(); $object->method();

The previous code will assign $object the handle of a new instance of
the class MyClass and call one of its methods.


Consider the following code:

1	class MyClass
2	{
3		function setMember($value)
4		{
5			$this->member = $value;
6		}
7
8		function getMember()
9		{
10			return $this->member;
11		}
12	}
13
14	function foo($obj)
15	{
16		$obj->setMember("foo");
17	}
18
19	$object = new MyClass();
20	$object->setMember("bar");
21	foo($object);
22	print $object->getMember();

Without the new Java-like handles, at line 20 the objects' data member
member is set to the string value of "bar".  Because of the internal
representation of objects in the Zend Engine 1.0, the object is marked
as a reference, and when it is sent by value to the function foo, it
is duplicated (!).  Therefore, the call to foo() on line 21 will
result in the $obj->setMember("foo") call being called on a duplicate
of $object. Line 22 will then result in "bar" being printed.

This is how the scripting engine has worked until today. Most
developers are probably unaware of the fact that they aren't always
talking to the same object but often duplicates; others may have
realized this can usually be solved by always passing objects by
reference (unless a replica is actually desired, which is uncommon).

The new object model will allow for a much more intuitive
implementation of the code.  On line 21, the object's handle (ID) is
passed to foo() by value. Inside foo(), the object is fetched
according to this handle and, therefore, the setMember() method is
called on the originally instantiated object and not a copy.  Line 22
will therefore result in "foo" being printed.  This approach gives
developers tighter control of when objects are created and duplicated.
An additional not-as-important benefit is that the object handle will
be passed to foo() by value, which most probably will also save
unnecessary duplication of the value containing the ID itself and thus
additionally improving run-time performance.

This was just a simple description of why the new object model solves
awkward behavior and makes object handling much easier, intuitive and
efficient.  The importance of this change goes far beyond what is
mentioned in this section as you will see in further sections which
describe new features with a majority of them being based on this
change.

Compatibility Notes
--------------------

Many PHP programmers aren't even aware of the copying quirks of the
current object model and, therefore, there is a relatively good chance
that the amount of PHP applications that will work out of the box or
after a very small amount of modifications would be high.

To simplify migration, version 2.0 will support an optional
'auto-clone' feature, which will perform a cloning of the object
whenever it would have been copied in version 1.0.  Optionally, it
will also be possible to request that the engine will emit an E_NOTICE
message whenever such an automatic clone occurs, in order to allow
developers to gradually migrate to the version 2.0-style behavior
(without automatic clones).

Dependencies
------------

The new object model is not dependent on other features.  Many of the
other Zend Engine 2.0 features, such as the $foo->bar()->barbara()
syntax, destructors and others completely rely on this new object
model.
