ORM Basics

Topics

As mentioned, the TEC ORM API can perform CRUD operations to manage TEC posts programmatically. The most common application of the ORM is to filter and then order the output when querying the posts. There are also options to further control the output by specifying the pagination or what to fetch.

The ORM can also modify the database by creating, updating, or deleting posts.

When using the ORM, these operations can be chained to filter down events, organizers, venues, attendees, or tickets and then your imagination is the only limit to what you can do with the output.

Filtering

`by( $key, $value = null )`

This method is an alias of the where() method.

`in( $post_ids )`

This method filters posts down to the those whose IDs are within the $post_ids array.

Example:

$events = tribe_events()
    ->in( [ 1, 2, 3 ] )
    ->all();

`not_in( $post_ids )`

This method filters posts down to the those whose IDs are NOT within the $post_ids array.

Example:

$events = tribe_events()
    ->not_in( [ 1, 2, 3 ] )
    ->all();

`parent( $post_id )`

Grab posts whose parent post is the given $post_id.

Example:

$events = tribe_events()
    ->parent( 5 )
    ->all();

`parent_in( $post_ids )`

Grab posts whose parent posts are within the given $post_ids array.

Example:

$events = tribe_events()
    ->parent_in( [ 1, 2, 3 ] )
    ->all();

`parent_not_in( $post_ids )`

Grab posts whose parent posts are NOT within the given $post_ids array.

Example:

$events = tribe_events()
    ->parent_not_in( [ 1, 2, 3 ] )
    ->all();

`search( $value )`

Filter results based on a search term.

Example:

$events = tribe_events()
    ->search( 'bork' )
    ->all();

`nth( $n )`

Returns the nth post of the page that matches the current query, using 1-based indexing (e.g., nth(2) returns the second post).

Example:

$events = tribe_events()
    ->nth( 2 )
    ->all();

`where( $key, $value = null )`

This method filters the results by the given key and value. Supported keys are those that are supported by the WP_Query class plus any of the repository’s declared schemas.

Example:

// Filter down to posts with a key and value.
$events = tribe_events()
    ->where( 'post_id', 5 )
    ->all();

// Filter down to posts with a key and default value.
$events = tribe_events()
    ->where( 'has_tickets' )
    ->all();

Ordering Results

`order( $order = 'ASC' )`

This is a simple modifier that orders results from the repository in ascending (ASC) or descending (DESC) order.

Example:

$events = tribe_events()
    ->order( 'ASC' )
    ->all();

`order_by( $order_by, $order = 'DESC' )`

You can order by a specific field and in a specific direction using this method.

Example:

$events = tribe_events()
    ->order_by( 'event_date', 'DESC' )
    ->all();

`sort( $orderby = [], $order = 'ASC', $preserve_keys = false )`

With the sort() method, you can sort by multiple fields in a specific direction.

Example:

$events = tribe_events()
    ->sort( [ 'event_date', 'post_title' ], 'ASC' )
    ->all();

Pagination

`next()`

Get the next page of results.

Example:

$events = tribe_events()
    ->per_page( 5 )
    ->next()
    ->all();

`page()`

Set the page number of the results to fetch.

Example:

// Fetches events the second 5 results.
$events = tribe_events()
    ->per_page( 5 )
    ->page( 2 )
    ->all();

`per_page()`

Set the number of posts per page for the fetched results.

Example:

// Fetches 5 events.
$events = tribe_events()
    ->per_page( 5 )
    ->all();

`prev()`

Get the previous page of results.

Example:

$events = tribe_events()
    ->per_page( 5 )
    ->prev()
    ->all();

`offset()`

Sets the offset for the query, specifying how many posts to skip before beginning to fetch results. This only takes effect when posts_per_page is not set to -1 and will ignore standard pagination.

Example:

$events = tribe_events()
    ->per_page( 10 )
    ->offset( 5 )
    ->all(); // Returns results, skipping the first 5 posts.

Fetching results

`all()`

Gets the results as posts.

Example:

$events = tribe_events()
    ->per_page( 20 )
    ->all();

`found()`

Returns the number of posts matching the query, ignoring the offset and returning the number of results as if limits were not applied. This is similar to, but more efficient than, count() because it does not apply any filters.

Example:

$events = tribe_events()
    ->per_page( 20 )
    ->found();
// If you had 100 events, the results would be 100

`count()`

Count the found posts on the current page.

Example:

$num = tribe_events()
    ->per_page( 20 )
    ->count();
// If you had 100 events, the results would be 20

`first()`

Get the first post in the result set.

Example:

$event = tribe_events()
    ->per_page( 20 )
    ->first();

`get_ids()`

Gets the IDs of the posts in the result set.

Example:

$event_ids = tribe_events()
    ->per_page( 20 )
    ->get_ids();

`last()`

Get the last post in the result set.

Example:

$event = tribe_events()
    ->per_page( 20 )
    ->last();

`pluck( $field )`

Gets the field from all posts in the result set.

Example:

$event_ids = tribe_events()
    ->per_page( 20 )
    ->pluck( 'post_title' );

`fields( $fields )`

Specifies which fields should be included in the query results. This can be used to limit the query to specific fields (e.g., only IDs or specific meta fields), improving performance by reducing the amount of data returned.

Example:

$event_ids = tribe_events()
    ->per_page( 20 )
    ->fields( 'ids' );

Modifying the database

`create()`

With this method (and ->set_args()), we can create new events. Some arguments you can use for event creation:

all_day – (boolean) Whether it is an all day event or not.
category – (array<int>) Array of category IDs.
cost – (float) Cost of the event.
currency_symbol – (string) Currency symbol.
currency_position – (string) Position for the currency symbol. prefix or postfix.
end_date – (string) End date/time of the event.
duration – (int) Time in seconds of the length of the event (not needed if end_date is present).
featured – (boolean) Whether or not the event should be featured.
hide_from_upcoming – (boolean) Whether to hide from upcoming events.
organizer – (array<int>) Array of organizer IDs.
show_map – (boolean) Whether to show the map or not.
show_map_link – (boolean) Whether to show the map link or not.
event_date – (string) Start date/time of the event
status – (string) WP post status.
sticky – (boolean) Whether the event should be sticky or not.
tag – (array<int>) Array of tag IDs.
timezone – (string) Timezone string. Example: America/New_York.
title – (string) Event title.
url – (string) URL of the event (if different than the WP event URL).
venue – (int) Venue ID.

Example:

$event = tribe_events()
    ->set_args( [
        'title'      => 'My Event',
        'event_date' => '+2 days 15:00:00',
        'duration'   => HOUR_IN_SECONDS,
        'status'     => 'publish',
    ] )
    ->create();

`delete()`

With this method you can delete events.

Example:

// Delete a specific event.
tribe_events()
    ->where( 'id', 5 )
    ->delete();

// Delete a collection of events.
tribe_events()
    ->where( 'ends_before', 'today' )
    ->delete();

`save()`

Note: Our developers are currently investigating an issue where the event repository is returning NULL when trying to update. The internal ticket reference is BTRIA-2310.

We can update existing data for a post. More information here.

Example:

$updated = tribe_events()
    ->where( 'id', 5 )
    ->set( 'title', 'My New Title' )
    ->set( 'category', [ 17, 18 ] )
    ->save();