Outlet provides database persistence for PHP objects in a transparent, unobtrusive way. It let's you define and instantiate entity classes that are completely independent of the code that saves them to the database. The data is persisted through the use of proxies. Whenever you 'save' an object, Outlet decorates the object with a sub-class that performs the database operations behind the scenes.

Let's say we start out with an entity object such as:

class Bug {
    public $Title;
    public $ProjectID;
 
    private $project;

    function getProject () {
        return $this->project;
    }

    function setProject (Project $p) {
        $this->project = $p;
    }
}

Whenever you instantiate, populate, and save it to the database with code like:

$con = Outlet::getInstance();
 
$bug = new Bug;
$bug->Title = "error on page";
$bug->ProjectID = 1;
 
$con->save( $bug ); //performs an insert

Outlet is replacing your $bug variable of type Bug with a proxy called Bug_OutletProxy:

print_r($bug); // after it's been saved

outputs:

Bug_OutletProxy Object
(
    [Title] => error on page
    [ProjectID] => 1
    [project:private] =>
)

Since the proxy is a subclass of the entity (Bug_OutletProxy extends Bug), you can use the proxy wherever you would have used the original entity. Even the following code evaluates to true:

// since the bug has been saved it is now an instance of Bug_OutletProxy
if ($bug instanceof Bug) echo "It seems to be a Bug too";

Now here's where the magic happens, when you call a method such a $bug->getProject(), the proxy automatically populates the $project property with data from the database behind the scenes:

// the proxy makes a SELECT query to retrieve the project from the database
$project = $bug->getProject();
 
print_r($bug);
		

You can see that the $bug->project property now contains an instance of Project:

Bug_OutletProxy Object
(
    [Title] => error on page
    [ProjectID] => 1
    [project:private] => Project_OutletProxy Object
        (
            [ID] => 1
            [Name] => My Project
        )

)