PhpRiot
Become Zend Certified

Prepare for the ZCE exam using our quizzes (web or iPad/iPhone). More info...


When you're ready get 7.5% off your exam voucher using voucher CJQNOV23 at the Zend Store

Managing Your Data With DatabaseObject

Callbacks

One of the most powerful features of DatabaseObject is its callbacks functionality. A callback is a function that is called after a certain operation takes place. In DatabaseObject (not taking into account getters, setters or checkers), there are seven different callbacks that can be defined:

  1. Post-load callback
  2. Pre-insert callback
  3. Post-insert callback
  4. Pre-update callback
  5. Post-update callback
  6. Pre-delete callback
  7. Post-delete callback

Post-load callback: loadCallback()

This function is called after a record has been successfully loaded. You may want to use this to load other properties associated with the loaded record. For example, you may want to load the list of links associated with a user (based on the example we are creating).

Listing 5 listing-5.php
<?php
    class User extends DatabaseObject
    {
        var $links = array();
 
        /* ... other code ... */
 
        function loadCallback()
        {
            $query = sprintf('select * from users_links where user_id = %d', $this->id);
            $result = $this->query($query);
 
            while ($row = $result->nextRow())
                $this->links[] = $row;
        }
    }
 
    $user = new User($db);
    $user->loadRecord(123); // load the record with user ID of 123
 
    // the above loadCallback() function is called if
    // $user->loadRecord() successfully loads the record
?>

Pre-insert callback: insertCallback()

This method is called prior to a new record being inserted. When the saveRecord() method is called, DatabaseObject determines whether a record is being inserted or updated. For example, you may to update a property right before saving the record.

Additionally, you can abort the saving of the record if you need. You must return true from this method to continue with saving the record. If you don’t return anything, or if you return false, then the record will not be saved.

Listing 6 listing-6.php
<?php
    class User extends DatabaseObject
    {
        /* ... other code ... */
 
        function insertCallback()
        {
            $this->setProperty('ts_created', time());
            return true;
        }
    }
?>

Post-insert callback: insertPostCallback()

This method is called right after a new record is inserted. There may be some extra actions you want to perform right after a new record is inserted, such as sending the new user an email. Once again, you must return true or false after this method. If you return false from this method, the insert will be rolled back from the database. Mind you, this requires that your database server supports transactions, so if it doesn’t, there’s no point returning false here.

Additionally, if you’re using PostgreSQL, the serial column (that is, the primary key column) will return an OID. DatabaseObject will automatically look up the correct primary key value based on the OID of the new record, prior to calling this method.

Listing 7 listing-7.php
<?php
    class User extends DatabaseObject
    {
        /* ... other code ... */
 
        function insertPostCallback()
        {
            $this->sendUserEmail();
            return true;
        }
 
        function sendUserEmail()
        {
            // functionality here to send the user an email
        }
    }
?>

Pre-update callback: updateCallback()

This method is called prior to saving an existing record. It works identically to the insertCallback() method, but is for existing records rather than new records. true must be returned the record to be saved to the database.

Listing 8 listing-8.php
<?php
    class User extends DatabaseObject
    {
        /* ... other code ... */
 
        function updateCallback()
        {
            $this->setProperty('ts_updated', time());
            return true;
        }
    }
?>

Post-update callback: updatePostCallback()

This method is called after an existing record is updated. It works identically to the insertPostCallback() method, but is for existing records rather than new records. For example, you might want to send the user an email confirming that their details have been updated. Just like insertPostCallback(), true must be returned, otherwise the update will be rolled back.

Listing 9 listing-9.php
<?php
    class User extends DatabaseObject
    {
        /* ... other code ... */
 
        function updatePostCallback()
        {
            $this->sendDetailsUpdatedUserEmail();
            return true;
        }
 
        function sendDetailsUpdatedUserEmail()
        {
            // functionality here to send the user an email
        }
    }
?>

Pre-delete callback: deleteCallback()

This method is called prior to a record being deleted. You may want to use this to deal with tables that reference this table. If you have foreign key constraints attached to your table, you won’t be able to remove this record. In our users/links example, you would want to delete a user’s links before you could delete the user.

Just like the other methods, you must return true or false from this method. Returning true proceeds with the deleting the record. If you return false the record will not be deleted.

Listing 10 listing-10.php
<?php
    class User extends DatabaseObject
    {
        /* ... other code ... */
 
        function deleteCallback()
        {
            $query = sprintf('delete from users_links where user_id = %d', $this->oid);
            $this->query($query);
 
            return true;
        }
    }
 
    $user = new User($db);
    $user->loadRecord(123); // load the record with user ID of 123
    $user->deleteRecord(); // now delete that record
 
?>

Post-delete callback: deletePostCallback()

This method is called after you delete a record. There may be some final cleanup code you want to execute after a record has been deleted. Once again, you must return true to finalize the delete, otherwise the delete operation will be rolled back.

Listing 11 listing-11.php
<?php
    class User extends DatabaseObject
    {
        /* ... other code ... */
 
        function deletePostCallback()
        {
            // do some final cleanup here if required
        }
    }
?>

In This Article


Additional Files