find()

Find items of a pod.

Find items of a pod, much like WP_Query, but with advanced table handling.

We covered this method extensively in the PodsCast episode #1

Function Definition

public function find ( $params = null, $limit = 15, $where = null, $sql = null )

Source File: /pods/classes/Pods.php

Since: 2.0

Parameters

PARAMETERTYPEDETAILS
$params(array|string|int)An associative array of parameters, or the ID of the item, or for advanced content types the item’s slug.
$limit(int)(optional) (deprecated) Limit the number of items to find, use -1 to return all items with no limit
$where(string)(optional) (deprecated) SQL WHERE declaration to use
$sql(string)(optional) (deprecated) For advanced use, a custom SQL query to run

Additional Parameter Options

OPTIONTYPEDEFAULTDETAILS
where(string)$whereSQL WHERE to use, ie “t.my_field = ‘test'” – This field also supports tableless traversal like “my_relationship_field.id = 3” with unlimited depth. For the exact syntax to use for your field based on your Pod / storage type, see the find() Notation Options
orderby(string)nullSQL ORDER BY to use, like “t.name DESC” – This field also supports tableless traversal like “my_relationship_field.name DESC” with unlimited depth
groupby(string)nullSQL GROUP BY, like ‘t.city’.
limit(int)$limitLimit the number of items to find, use -1 to return all items with no limit
offset(int)nullOverride what’s calculated automatically based on ‘limit’ and ‘page’
search(bool)trueWhether to handle search. Defaults to $this->search, which can be globally overridden by defining the constant PODS_GLOBAL_POD_SEARCH to true/false
pagination(bool)trueWhether to handle pagination. Defaults to $this->pagination, which can be globally overridden by defining the constant PODS_GLOBAL_POD_PAGINATION to true/false
page(int)1Specify a page of the results to get. Defaults to $this->page,
table(string)Default of current pod typeTable to base find() off of
select(string)`t`.* or `t`.*, `d`.*Fields to select from the database. The “t” prefix will reference the primary table, “d” prefixes are used for the Pod table for any WP Object and the “t” prefix references that WP Object (wp_posts, wp_terms, wp_users, wp_comments)
join(string or array)nullAdditional table(s) to JOIN, using SQL syntax like “LEFT JOIN `my_table` ON `my_table`.`id` = `t`.`id`”
expires(int)nullWhether to cache the results or not, 0 will cache it until caches are cleared, 1+ will cache it for X amount of seconds; Default is no caching (null)
cache_mode(string)cacheCache mode to use, available options are cache, transient, or site-transient

Returns

(Pods) The pod object

Examples

Example 1

<?php
// Find can be called in one of three ways

// Example #1
$mypod = pods( 'mypod', $params );

// Example #2
$mypod = pods( 'mypod' )->find( $params );

// Example #3
$mypod = pods( 'mypod' );
$mypod->find( $params );


// Here's how to use find()
$params = array(
    'limit' => 3, 
    'page' => 2, 
    // Be sure to sanitize ANY strings going here
    'where'=>"category.name = 'My Category'"
);

// Run the find
$mypod = pods( 'mypod', $params );

// Loop through the records returned
while ( $mypod->fetch() ) {
    echo $mypod->display( 'name' ) . "\n";
}

The above example will output:

Pod Title 1 
Pod Title 2 
Pod Title 3

Using a variable in a where clause

When the where clause must be created dynamically, a variable can be passed to it like in this example:

<?php
// get value from input to a form
$keyword = like_escape( pods_v_sanitized( 'keyword', 'post' ) );

// set up find parameters, where meta field title matches $keyword
$params = array(
    'where' => 't.post_title LIKE "%' . $keyword . '%" OR my_field.meta_value LIKE "%' . $keyword . '%"'
 );

//search in articles pod
$pods = pods( 'articles', $params );

//loop through results
if ( 0 < $pods->total() ) {
    while ( $pods->fetch() ) {
        echo $pods->display( 'issue' );
    }
}
?>

Additional find() Notation Options

There are a number of special notation options you can use which can save you time and effort in referencing field in your find() requests. Be sure to check them out because this is one of the most powerful features in Pods.

More Documentation on find()

find() Notation Options

Available find() notation options.