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();

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 respository’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( 'start_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( [ 'start_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();

Fetching results

`all()`

Gets the results as posts.

Example:

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

`count()`

Count the found posts.

Example:

$num = tribe_events()
    ->per_page( 20 )
    ->count();

`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' );

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.
start_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',
        'start_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: This functionality is not currently working as expected because it needs to be updated for the new custom tables following the 6.x update. There is an internal ticket [BTRIA-2310] for our developers to investigate this further.

We can update existing data for an event.

Example:

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