pods()

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

PARAMETER	TYPE	DETAILS
$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->valid() ) {
	// The named pods configurations are registered.
}

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;