--------------
Omeka_Db_Table
--------------

.. php:class:: Omeka_Db_Table

    Package: :doc:`Db\\Table </Reference/packages/Db/Table/index>`

    Database table classes.
    
    Subclasses attached to models must follow the naming convention:Table_TableName, e.g. Table_ElementSet in models/Table/ElementSet.php.

    .. php:attr:: _target
    
        The name of the model for which this table will retrieve objects.

    .. php:attr:: _name
    
        The name of the table (sans prefix).
        
        If this is not given, it will be inflected.

    .. php:attr:: _tablePrefix
    
        The table prefix.
        
        Generally used to differentiate Omeka installations sharing a database.

    .. php:attr:: _db
    
        The Omeka database object.

    .. php:method:: __construct(string $targetModel, Omeka_Db $db)
    
        Construct the database table object.
        
        Do not instantiate this by itself. Access instances only viaOmeka_Db::getTable().
        
        :param string $targetModel: Class name of the table's model.
        :param Omeka_Db $db: Database object to use for queries.

    .. php:method:: __call(string $m, array $a)
    
        Delegate to the database adapter.
        
        Used primarily as a convenience method. For example, you can callfetchOne() and fetchAll() directly from this object.
        
        :param string $m: Method name.
        :param array $a: Method arguments.
        :returns: mixed

    .. php:method:: getTableAlias()
    
        Retrieve the alias for this table (the name without the prefix).
        
        :returns: string

    .. php:method:: getDb()
    
        Retrieve the Omeka_Db instance.
        
        :returns: Omeka_Db

    .. php:method:: hasColumn(string $field)
    
        Determine whether a model has a given column.
        
        :param string $field: Field name.
        :returns: bool

    .. php:method:: getColumns()
    
        Retrieve a list of all the columns for a given model.
        
        This should be here and not in the model class because get_class_vars()returns private/protected properties when called from within the class.Will only return public properties when called in this fashion.
        
        :returns: array

    .. php:method:: getTableName()
    
        Retrieve the name of the table for the current table (used in SQL 
        statements).
        
        If the table name has not been set, it will inflect the table name.
        
        :returns: string

    .. php:method:: setTableName(string $name)
    
        Set the name of the database table accessed by this class.
        
        If no name is provided, it will inflect the table name from the name ofthe model defined in the constructor. For example, Item -> items.
        
        :param string $name: (optional) Table name.
        :returns: void

    .. php:method:: getTablePrefix()
    
        Retrieve the table prefix for this table instance.
        
        :returns: string

    .. php:method:: setTablePrefix(string|null $tablePrefix)
    
        Set the table prefix.
        
        Defaults to the table prefix defined by the Omeka_Db instance. Thisshould remain the default in most cases. However, edge cases may requirecustomization, e.g. creating wrappers for tables generated by otherapplications.
        
        :param string|null $tablePrefix:

    .. php:method:: find(integer $id)
    
        Retrieve a single record given an ID.
        
        :param integer $id: 
        :returns: Omeka_Record_AbstractRecord|false

    .. php:method:: findAll()
    
        Get a set of objects corresponding to all the rows in the table
        
        WARNING: This will be memory intensive and is thus not recommended forlarge data sets.
        
        :returns: array Array of {@link Omeka_Record_AbstractRecord}s.

    .. php:method:: findPairsForSelectForm(array $options = Array)
    
        Retrieve an array of key=>value pairs that can be used as options in a 
        <select> form input.
        
        :param array $options: (optional) Set of parameters for searching/ filtering results.
        :returns: array

    .. php:method:: _getColumnPairs()
    
        Retrieve the array of columns that are used by findPairsForSelectForm().
        
        This is a template method because these columns are different for everytable, but the underlying logic that retrieves the pairs from thedatabase is the same in every instance.
        
        :returns: array

    .. php:method:: findBy(array $params = Array, integer $limit, integer $page)
    
        Retrieve a set of model objects based on a given number of parameters
        
        :param array $params: A set of parameters by which to filter the objects that get returned from the database.
        :param integer $limit: Number of objects to return per "page".
        :param integer $page: Page to retrieve.
        :returns: array|null The set of objects that is returned

    .. php:method:: getSelect()
    
        Retrieve a select object for this table.
        
        :returns: Omeka_Db_Select

    .. php:method:: getSelectForFindBy(array $params = Array)
    
        Retrieve a select object that has had search filters applied to it.
        
        :param array $params: optional Set of named search parameters.
        :returns: Omeka_Db_Select

    .. php:method:: getSelectForFind(integer $recordId)
    
        Retrieve a select object that is used for retrieving a single record from 
        the database.
        
        :param integer $recordId: 
        :returns: Omeka_Db_Select

    .. php:method:: applySearchFilters(Omeka_Db_Select $select, array $params)
    
        Apply a set of filters to a Select object based on the parameters given.
        
        By default, this simply checks the params for keys corresponding to databasecolumn names. For more complex filtering (e.g., when other tables are involved),or to use keys other than column names, override this method and optionallycall this parent method.
        
        :param Omeka_Db_Select $select: 
        :param array $params:

    .. php:method:: applySorting(Omeka_Db_Select $select, string $sortField, string $sortDir)
    
        Apply default column-based sorting for a table.
        
        :param Omeka_Db_Select $select: 
        :param string $sortField: Field to sort on.
        :param string $sortDir: Direction to sort.

    .. php:method:: applyPagination(Zend_Db_Select $select, integer $limit, integer|null $page)
    
        Apply pagination to a select object via the LIMIT and OFFSET clauses.
        
        :param Zend_Db_Select $select: 
        :param integer $limit: Number of results per "page".
        :param integer|null $page: Page to retrieve, first if omitted.
        :returns: Zend_Db_Select

    .. php:method:: findBySql(string $sqlWhereClause, array $params = Array, boolean $findOne = )
    
        Retrieve an object or set of objects based on an SQL WHERE predicate.
        
        :param string $sqlWhereClause: 
        :param array $params: optional Set of parameters to bind to the WHERE clause. Used to prevent security flaws.
        :param boolean $findOne: optional Whether or not to retrieve a single record or the whole set (retrieve all by default).
        :returns: array|Omeka_Record_AbstractRecord|false

    .. php:method:: count(array $params = Array)
    
        Retrieve a count of all the rows in the table.
        
        :param array $params: optional Set of search filters upon which to base the count.
        :returns: integer

    .. php:method:: getSelectForCount(array $params = Array)
    
        Retrieve a select object used to retrieve a count of all the table rows.
        
        :param array $params: optional Set of search filters.
        :returns: Omeka_Db_Select

    .. php:method:: checkExists(int $id)
    
        Check whether a given row exists in the database.
        
        Currently used to verify that a row exists even though the current usermay not have permissions to access it.
        
        :param int $id: The ID of the row.
        :returns: boolean

    .. php:method:: fetchObjects(string $sql, array $params = Array)
    
        Retrieve a set of record objects based on an SQL SELECT statement.
        
        :param string $sql: This could be either a string or any object that can be cast to a string (commonly Omeka_Db_Select).
        :param array $params: Set of parameters to bind to the SQL statement.
        :returns: array|null Set of Omeka_Record_AbstractRecord instances, or null if none can be found.

    .. php:method:: fetchObject(string $sql, string $params = Array)
    
        Retrieve a single record object from the database.
        
        :param string $sql: 
        :param string $params: Parameters to substitute into SQL query.
        :returns: Omeka_Record_AbstractRecord or null if no record

    .. php:method:: recordFromData(array $data)
    
        Populate a record object with data retrieved from the database.
        
        :param array $data: A keyed array representing a row from the database.
        :returns: Omeka_Record_AbstractRecord

    .. php:method:: _getSortParams(array $params)
    
        Get and parse sorting parameters to pass to applySorting.
        
        A sorting direction of 'ASC' will be used if no direction parameter ispassed.
        
        :param array $params: 
        :returns: array|null Array of sort field, sort dir if params exist, null otherwise.

    .. php:method:: _getHookName(string $suffix)
    
        Get the name for a model-specific hook or filter..
        
        :param string $suffix: The hook-specific part of the hook name.
        :returns: string