{{Doctrine_Record}} is a wrapper for database row but along with that it speficies what relations it has
{{Doctrine_Record}} is a wrapper for database row but along with that it speficies what relations it has
on other components and what columns it has. It may access the related components, hence its refered as an ActiveRecord.
on other components and what columns it has. It may access the related components, hence its refered as an ActiveRecord.
The classes that inherit {{Doctrine_Record}} are called components. There should be atleast one component for each database table.
The classes that inherit {{Doctrine_Record}} are called components. There should be atleast one component for each database table.
++++ Creating new records
++++ Creating new records
There are couple of ways for creating new records. Propably the easiest is using native php new -operator. The other ways are calling {{Doctrine_Table::create()}} or {{Doctrine_Connection::create()}}. The last two exists only for backward compatibility. The recommended way of creating new objects is the new operator.
There are couple of ways for creating new records. Propably the easiest is using native php new -operator. The other ways are calling {{Doctrine_Table::create()}} or {{Doctrine_Connection::create()}}. The last two exists only for backward compatibility. The recommended way of creating new objects is the new operator.
<code type="php">
<code type="php">
$user = $conn->create("User");
$user = $conn->create("User");
// alternative way:
// alternative way:
$table = $conn->getTable("User");
$table = $conn->getTable("User");
$user = $table->create();
$user = $table->create();
// the simpliest way:
// the simpliest way:
$user = new User();
$user = new User();
// records support array access
// records support array access
$user["name"] = "John Locke";
$user["name"] = "John Locke";
// save user into database
// save user into database
$user->save();
$user->save();
</code>
</code>
++++ Retrieving existing records
++++ Retrieving existing records
Doctrine provides many ways for record retrieval. The fastest ways for retrieving existing records are the finder methods provided by {{Doctrine_Table}}. If you need to use more complex queries take a look at DQL API and {{Doctrine_Connection::query}} method.
Doctrine provides many ways for record retrieval. The fastest ways for retrieving existing records are the finder methods provided by {{Doctrine_Table}}. If you need to use more complex queries take a look at DQL API and {{Doctrine_Connection::query}} method.
<code type="php">
<code type="php">
$table = $conn->getTable("User");
$table = $conn->getTable("User");
// find by primary key
// find by primary key
$user = $table->find(2);
$user = $table->find(2);
if($user !== false)
if($user !== false)
print $user->name;
print $user->name;
// get all users
// get all users
foreach($table->findAll() as $user) {
foreach($table->findAll() as $user) {
print $user->name;
print $user->name;
}
}
// finding by dql
// finding by dql
foreach($table->findByDql("name LIKE '%John%'") as $user) {
foreach($table->findByDql("name LIKE '%John%'") as $user) {
print $user->created;
print $user->created;
}
}
// finding objects with DQL
// finding objects with DQL
$users = $conn->query("FROM User WHERE User.name LIKE '%John%'");
$users = $conn->query("FROM User WHERE User.name LIKE '%John%'");
</code>
</code>
++++ Accessing properties
++++ Accessing properties
You can retrieve existing objects (database rows) with {{Doctrine_Table}} or {{Doctrine_Connection}}. {{Doctrine_Table}} provides simple methods like {{findBySql}}, {{findAll}} and find for finding objects whereas {{Doctrine_Connection}} provides complete OQL API for retrieving objects (see chapter 9).
You can retrieve existing objects (database rows) with {{Doctrine_Table}} or {{Doctrine_Connection}}. {{Doctrine_Table}} provides simple methods like {{findBySql}}, {{findAll}} and find for finding objects whereas {{Doctrine_Connection}} provides complete OQL API for retrieving objects (see chapter 9).
<code type="php">
<code type="php">
$user = $table->find(3);
$user = $table->find(3);
// access property through overloading
// access property through overloading
$name = $user->name;
$name = $user->name;
// access property with get()
// access property with get()
$name = $user->get("name");
$name = $user->get("name");
// access property with ArrayAccess interface
// access property with ArrayAccess interface
$name = $user['name'];
$name = $user['name'];
// iterating through properties
// iterating through properties
foreach($user as $key => $value) {
foreach($user as $key => $value) {
}
}
</code>
</code>
++++ Updating records
++++ Updating records
Updating objects is very easy, you just call the {{Doctrine_Record::save()}} method. The other way (perhaps even easier) is to call {{Doctrine_Connection::flush()}} which saves all objects. It should be noted though that flushing is a much heavier operation than just calling save method.
Updating objects is very easy, you just call the {{Doctrine_Record::save()}} method. The other way (perhaps even easier) is to call {{Doctrine_Connection::flush()}} which saves all objects. It should be noted though that flushing is a much heavier operation than just calling save method.
<code type="php">
<code type='php'>
$table = $conn->getTable("User");
$table = $conn->getTable('User');
$user = $table->find(2);
$user = $table->find(2);
if($user !== false) {
if($user !== false) {
$user->name = "Jack Daniels";
$user->name = 'Jack Daniels';
$user->save();
$user->save();
}
}
</code>
</code>
++++ Deleting records
++++ Deleting records
Deleting records in Doctrine is handled by {{Doctrine_Record::delete()}}, {{Doctrine_Collection::delete()}} and {{Doctrine_Connection::delete()}} methods.
Deleting records in Doctrine is handled by {{Doctrine_Record::delete()}}, {{Doctrine_Collection::delete()}} and {{Doctrine_Connection::delete()}} methods.
<code type="php">
<code type="php">
$table = $conn->getTable("User");
$table = $conn->getTable("User");
$user = $table->find(2);
$user = $table->find(2);
// deletes user and all related composite objects
// deletes user and all related composite objects
if($user !== false)
if($user !== false)
$user->delete();
$user->delete();
$users = $table->findAll();
$users = $table->findAll();
// delete all users and their related composite objects
// delete all users and their related composite objects
$users->delete();
$users->delete();
</code>
</code>
++++ Using expression values
++++ Getting record state
There might be situations where you need to use SQL expressions as values of columns. This can be achieved by using Doctrine_Expression which converts portable DQL expressions to your native SQL expressions.
{{Every Doctrine_Record}} has a state. First of all record can be transient or persistent. Every record that is retrieved from database is persistent and every newly created record is transient. If a {{Doctrine_Record}} is retrieved from database but the only loaded property is its primary key, then this record has a state called proxy.
Lets say we have a class called event with columns timepoint(datetime) and name(string). Saving the record with the current timepoint can be achieved as follows:
Every transient and persistent {{Doctrine_Record}} is either clean or dirty. {{Doctrine_Record}} is clean when none of its properties are changed and dirty when atleast one of its properties has changed.
<code type="php">
$event = new Event();
<code type="php">
$event->name = 'Rock festival';
$state = $record->state();
$event->timepoint = new Doctrine_Expression('NOW()');
switch($state):
$event->save();
case Doctrine_Record::STATE_PROXY:
</code>
// record is in proxy state,
// meaning its persistent but not all of its properties are
The last line would execute sql (in sqlite):
// loaded from the database
<code>
break;
INSERT INTO event (name, timepoint) VALUES (?, 'NOW()')
case Doctrine_Record::STATE_TCLEAN:
</code>
// record is transient clean,
// meaning its transient and
++++ Getting record state
// none of its properties are changed
break;
{{Every Doctrine_Record}} has a state. First of all record can be transient or persistent. Every record that is retrieved from database is persistent and every newly created record is transient. If a {{Doctrine_Record}} is retrieved from database but the only loaded property is its primary key, then this record has a state called proxy.
case Doctrine_Record::STATE_TDIRTY:
// record is transient dirty,
Every transient and persistent {{Doctrine_Record}} is either clean or dirty. {{Doctrine_Record}} is clean when none of its properties are changed and dirty when atleast one of its properties has changed.
// meaning its transient and
// some of its properties are changed
<code type="php">
break;
$state = $record->state();
case Doctrine_Record::STATE_DIRTY:
// record is dirty,
switch($state):
// meaning its persistent and
case Doctrine_Record::STATE_PROXY:
// some of its properties are changed
// record is in proxy state,
break;
// meaning its persistent but not all of its properties are
case Doctrine_Record::STATE_CLEAN:
// loaded from the database
// record is clean,
break;
// meaning its persistent and
case Doctrine_Record::STATE_TCLEAN:
// none of its properties are changed
// record is transient clean,
break;
// meaning its transient and
endswitch;
// none of its properties are changed
</code>
break;
case Doctrine_Record::STATE_TDIRTY:
// record is transient dirty,
++++ Getting object copy
// meaning its transient and
// some of its properties are changed
Sometimes you may want to get a copy of your object (a new object with all properties copied). Doctrine provides a simple method for this: {{Doctrine_Record::copy()}}.
break;
case Doctrine_Record::STATE_DIRTY:
<code type="php">
// record is dirty,
$copy = $user->copy();
// meaning its persistent and
</code>
// some of its properties are changed
break;
case Doctrine_Record::STATE_CLEAN:
++++ Serializing
// record is clean,
// meaning its persistent and
Sometimes you may want to serialize your record objects (possibly for caching purposes). Records can be serialized, but remember: Doctrine cleans all relations, before doing this. So remember to persist your objects into database before serializing them.
// none of its properties are changed
break;
<code type="php">
endswitch;
$string = serialize($user);
</code>
$user = unserialize($string);
</code>
++++ Getting object copy
Sometimes you may want to get a copy of your object (a new object with all properties copied). Doctrine provides a simple method for this: {{Doctrine_Record::copy()}}.
++++ Checking Existence
<code type="php">
<code type="php">
$copy = $user->copy();
$record = new User();
</code>
$record->exists(); // false
++++ Serializing
$record->name = 'someone';
$record->save();
Sometimes you may want to serialize your record objects (possibly for caching purposes). Records can be serialized, but remember: Doctrine cleans all relations, before doing this. So remember to persist your objects into database before serializing them.
