Understanding Omeka_Db_Table

Basics

Omeka_Db_Table is part of the Model part of Model-View-Controller in Omeka. It provides the methods for querying the database and returning results as Omeka_Record_AbstractRecord objects. The most frequently used methods in this class are Omeka_Db_Table::findBy and Omeka_Db_Table::find

Omeka_Db_Table::find simply returns a single record by the id passed in.

Omeka_Db_Table::findBy returns an array of records that match the criteria passed in with the $param argument. When creating your subclasses of Omeka_Db_Table, you will want to understand first how to build filters for queries using Omeka_Db_Table::findBy.

Omeka_Db_Table::findBy works by manipulating a Omeka_Db_Select object, which simplifies the process fo building simple SQL queries.

Filtering Queries

Omeka_Db_Table::findBy calls method Omeka_Db_Table::applySearchFilters. It takes a $select argument, and a $params argument. By default, this method simply checks the $params array passed in, looking for keys that match column names. For each match, a WHERE clause is generated.

Sometimes, though, it makes sense to add more complex logic. For example, you might want to filter a query by conditions on joining another table, or you might need to call a method in your subclass to process the data passed in the value of the parameter key. In such cases, Omeka has moved toward a pattern of using filterBy* methods.

In this pattern, you build more complex logic for adding a WHERE clause by passing in the $select object, and the value that you want to work with. Table_Collection offers a good example.

public function filterByPublic($select, $isPublic)
{
    $isPublic = (bool) $isPublic; // this makes sure that empty strings and unset parameters are false

    //Force a preview of the public collections
    if ($isPublic) {
        $select->where('collections.public = 1');
    } else {
        $select->where('collections.public = 0');
    }
}

This method does a little double-checking on the value passed in for whether the collection has been marked public, then applies the appropriate WHERE clause to the $select object.

In Table_Collection::applySearchFilters, we see the following to call it:

if(array_key_exists('public', $params)) {
    $this->filterByPublic($select, $params['public']);
}