pods()

Set up the Pods class object for a specific pod.

Set up the Pods class object for a specific pod.

Function Definition

function pods ( $type = null, $id = null, $strict = false )

Source File: /pods/includes/classes.php

Since: 2.0

Parameters

PARAMETERTYPEDETAILS
$type(string)The pod name, leave null to auto-detect from The Loop.
$id(mixed)(optional) The ID or slug, to load a single record; Provide array of $params to run ‘find’; Or leave null to auto-detect from The Loop.
$strict(bool)(optional) If set to true, returns false instead of a Pods object, if the Pod itself doesn’t exist. Note: If you want to check if the Pods Item itself doesn’t exist, use exists().

Returns

(bool|Pods) The Pods object or false if $strict was set to true.

Examples

Get the Pods object

<?php
$mypod = pods( 'mypod' );

Get the Pods object for a specific ID or slug

<?php
$mypod = pods( 'mypod', $id_or_slug );

Get the Pods object and run a find()

<?php
$params = [
	'orderby' => 't.name DESC',
	'limit'   => 25,
	'where'   => 't.name != "Buster Keaton"',
];

$mypod = pods( 'mypod', $params );

// The above is the same as this.
$mypod = pods( 'mypod' )->find( $params );

// And the same as this.
$mypod = pods( 'mypod' );

$mypod->find( $params );

Output the field for all items returned using fetch() and display()

<?php
$mypod = pods( 'mypod' );

$mypod->find();

// Loop through the items returned.
while ( $mypod->fetch() ) {
	echo '<p>' . $mypod->display( 'my_field_name' ) . '</p>';
}

Check if a specific item exists with exists()

<?php
$mypod = pods( 'mypod', $id_or_slug );

if ( $pods->exists() ) {
	// The item exists.
} else {
	// The item was not found.
}

Output a form to allow adding new items using form()

<?php
$pods = pods( 'fruits' );

// Specify which fields to show.
$fields = [
	'post_title',
	'post_content',
	'available_stores',
];

// Output the form.
echo $pods->form( $fields );

Use strict mode and exists() to avoid errors if Pod or Pod item do not exist

This illustrates the difference between strict mode, which returns false if the pod itself does not exist, versus exists() (if the item exists).

<?php
$pods = pods( 'fruits', 'satsuma', true );

// Check if the pod is valid.
if ( false !== $pods ) {
	// Check if the pod item exists.
	if ( $pods->exists() ) {
		// The pod item exists.
	}
}

Use valid() to check if the Pod name is valid

When strict mode is not used, you can still check to see if the pod configuration is valid or not. If it’s not, expect everything else to not return items and other side effects. It’s not necessary to always check that a pod exists but if you are working with code that may change depending on whether the pod exists or not then it can be very useful.

<?php
$pods = pods( 'fruits', 'satsuma' );

// Check if the pod item exists.
if ( $pods->exists() ) {
	// The pod item exists.
}

Use exists() to check if a Pod item exists

Knowing whether an item was found or not when looking it up directly can be important for whether to output certain information.

<?php
$pods = pods( 'fruits', 'satsuma' );

// Check if the pod item exists.
if ( $pods->exists() ) {
	// The pod item exists.
}

Working with The Loop

The Loop is what you will find used in most themes that work with data stored in post types. The Loop covers every post type including Page, Post, and Custom Post Types extended/defined by Pods.

You may find yourself wanting to work within The Loop to output field values and interact with the Pods object itself. This example shows how to reference the current post while in any loop.

The Basics of pods() Auto-Detection

By default, pods() will automatically check to see if you are in a loop OR on a singular template. This handles a few different use-cases:

  • Post types (singular or archive)
    • Posts, Pages, and Custom Post Types
  • Taxonomy term archive (treated as a singular term)
    • Categories, Post Tags, and Custom Taxonomies
  • Author archive (treated as a singular user)

Example with Auto-Detection

<?php
// Detect what pod and which item to use.
$pods = pods();

// Output your field value.
echo $pods->display( 'my_custom_field' );

Example with Auto-Detection while in The Loop

This example covers most common uses which need to output custom fields for one or more post types in The Loop.

<?php
// Check if there are posts to display.
if ( have_posts() ) :
	// Loop through all of the posts.
	while ( have_posts() ) : the_post();
		// Display post content

		// Use pods() with multiple post types that may be in this loop.
		$pods = pods();

		// Output your field value.
		echo $pods->display( 'my_custom_field' );
	endwhile;
endif;

Example with an Optimized Pods object (reused) in The Loop

If you are working with the loop and you only have one post type being listed, the optimized Pods object approach is the recommended way because it uses less memory, less queries, and is generally much more efficient.

<?php
// Check if there are posts to display.
if ( have_posts() ) :
	// Use pods() outside of the loop to define which post type you are working with if it's only one post type.
	$pods = pods( 'your_post_type' );

	// Loop through all of the posts.
	while ( have_posts() ) : the_post();
		// Display post content

		// Tell Pods which post ID to fetch field values for.
		$pods->fetch( get_the_ID() );

		// Output your field value.
		echo $pods->display( 'my_custom_field' );
	endwhile;
endif;

Example with Shorthand Field Syntax in The Loop

This example shows an additional function pods_field_display() which can simplify usage but comes with the caveat of more memory used, additional queries, and less code efficiency.

<?php
// Check if there are posts to display.
if ( have_posts() ) :
	// Loop through all of the posts.
	while ( have_posts() ) : the_post();
		// Display post content

		// Output your field value.
		echo pods_field_display( 'my_custom_field' );
	endwhile;
endif;

More Documentation on pods()

add_to()

Add an item to the values of a relationship field.

add()

Add an item to a Pod.

data()

Return an array of all rows returned from a find() call.

delete()

Delete an item from the Pod.

display()

Return the output for a field.

do_magic_tags()

Replace magic tags with their values.

duplicate()

Duplicate an item.

exists()

Whether a Pod item exists or not when using fetch() or construct with an ID or slug.

export_data()

Export data from all items.

export()

Export an item’s data.

fetch()

Fetch an item from a Pod.

field()

Return the value for a field.

fields()

Return field array from a Pod, a field’s data, or a field option.

filters()

Output search filters to be used with find().

find()

Find items of a pod.

first_id()

Return the first item ID.

form()

Embed a form to add / edit a pod item from within your theme.

helper()

Run a helper within a Pod Page or WP Template.

id()

Return the item ID.

import()

Import data.

index()

Return the item name.

last_id()

Return the last item ID.

next_id()

Return the next item ID.

nth()

Fetch the nth state.

pagination()

Display the pagination controls.

position()

Fetch the current position in the loop.

prev_id()

Return the previous item ID.

raw()

Return the raw output for a field.

remove_from()

Remove values from fields.

reset_pod()

Delete all items from the Pod.

reset()

Reset the item position back to the start of the find() list.

row()

Return row array for an item.

save()

Save an item.

template()

Display the page template.

total_found()

Fetch to total number of rows found.

total()

Fetch the total row count.

valid()

Pod object validity.

zebra()

Fetch the zebra switch.