Queries and URL parameters

Collections (productions, people, schedule) read their filters from URL parameters and from shortcode attributes, and are built on a small set of query services. This page documents the URL contract, the collection routes and the PHP query services. For the visibility guarantees and stability classification of each service, see Stage presentation services.

Rendering a collection from PHP #

echo \Hype5\Theater\Frontend\Collections::render('productions', ['context' => 'upcoming', 'filters' => '0']);

Collections::render(string $type, array $attributes = []): string accepts productions, people or schedule and the attributes of the matching shortcode. It is the same code path as the shortcodes and blocks.

URL parameters #

Only scalar values are accepted. An attribute set on the shortcode always wins over the URL. A malformed hype5_production or hype5_venue makes the schedule empty instead of showing everything. Weeks start on WordPress's Week Starts On setting.

Which filter fields are shown is set in Appearance → Lists and pages (stored in hype5t_appearance as productions_filters, people_filters, schedule_filters).

Collection routes #

When a collection page is chosen in Appearance (option hype5t_collection_routes, keys productions, people, schedule ⇒ page ID), requests to the built-in address are redirected to that page with HTTP 302, keeping recognised hype5_* parameters. The page must be published and should contain the matching shortcode. A missing, unpublished or self-referencing page never causes a redirect. Single production and person pages are not affected.

Query services #

Data\CollectionRequest::normalize(array $attributes = [], array $request = []): array #

Combines attributes and request values (hype5_{key}) into a normalised argument array: context, search, genre, audience, language, city, profession, company_status, date_from, date_to, range, access, status (strings), production, venue (integers; -1 = malformed), page (≥ 1), per_page (1–100, default 12, alias limit), filters, pagination (booleans, default true) and active (whether any filter is set). Pass [] as $request to ignore the URL. Writes nothing.

Data\ProductionQuery::find(array $args): array #

$args is the output of normalize() plus context (current, upcoming, archive, archived, active, all) and order (next, title, manual, premiere_asc, premiere_desc; resolve auto yourself). Returns ['items' => WP_Post[], 'total', 'page', 'pages', 'args']. Only published productions are returned, including password-protected ones; turn the posts into output with ProductionCard::batch() or Collections::render(), not by printing post fields. The next order and the city filter use only performances of productions public to everyone (Theater 0.7.0): a protected production sorts with the undated ones and never matches a city.

ProductionQuery::states(string $context): array returns the repertory statuses of a context.

Data\ProductionQuery::next(array $ids): array #

The next scheduled or sold-out performance of each production, keyed by the production IDs you pass. Performances are stored against the original-language production; translated IDs are resolved to it (Phase 5K). Productions the visitor may not see are left out (unpublished, or password-protected without the password entered); the version you pass decides which password applies (Theater 0.7.0). This is a production-scoped reader: on other pages pass only IDs that Data\Visibility::listed() accepts. The rows are raw schedule rows; format them with Frontend\ProductionSchedule::row().

Data\PersonQuery::find(array $args): array #

$args from normalize(), optionally with order (sort_name or title). Returns the same shape with person posts that are published, have a public profile and are shown in the directory. PersonQuery::sort_name(int $id): string returns the sort name or the title.

Data\ScheduleQuery::find(array $args = []): array and count(array $args = []): int #

Arguments: limit (1–100, default 20), offset, production, venue, city, access, from, to, month, status, past, include_past, scope. Invalid values throw \InvalidArgumentException. Returns raw performance rows with offers and replacement attached, or the matching count. Only performances of productions public to everyone are included (published without a password; on a multilingual site also the reader's-language version, since 0.7.0, so count() equals the rows a public list shows), plus those of a password-protected production when the query is filtered to that production and the visitor has entered its password. scope (0.7.0) names the production version whose password decides; it defaults to production (production-scoped on any page), and 'scope' => 0 makes a filtered query cross-entity (no protected rows even after the password — pass it for output on other pages; row() withholds such rows there anyway). The venue is not checked here; ProductionSchedule::row() withholds what the visitor may not see, and lists shown on other pages should keep only rows whose production is public to everyone (as Collections::render() does). Raw rows contain internal fields (internal note, attendance, timestamps) and must never be printed; format each row with Frontend\ProductionSchedule::row(). Do not pass the second (internal) argument of find(): it disables the publication checks.

ScheduleQuery::access_choices(): array returns the accepted access keys with labels.

Cards and rows for output #

• Frontend\ProductionCard::batch(array $ids, array $display): array — prepared production cards keyed by ID, as used by collections.production-card.
• Frontend\ProductionSchedule::row(array $row, array $display, bool $registerAnchor = true): array — the prepared production.performance view of a raw row, withheld when the visitor may not see it.
• Frontend\DisplayOptions::for_entity(int $id = 0, array $explicit = []): array — the $display array these functions need.

Example: the next dates of one production #

A strip on a production's own page (scoped to that production, so the visitor's entered password applies):

use Hype5\Theater\Data\ScheduleQuery;
use Hype5\Theater\Frontend\{Appearance, DisplayOptions, ProductionSchedule, Render};

$productionId = get_the_ID();
$display = DisplayOptions::for_entity($productionId, ['schedule_layout' => 'agenda']);
try {
    $rows = ScheduleQuery::find(['production' => $productionId, 'limit' => 5, 'status' => 'scheduled']);
} catch (\InvalidArgumentException $e) {
    $rows = [];
}
echo '<div ' . Appearance::root($display, 'hype5-schedule') . '>';
foreach ($rows as $row) {
    $view = ProductionSchedule::row($row, $display, false);
    if (!empty($view['withheld'])) { continue; }
    echo Render::template('production.performance', $view, $display);
}
echo '</div>';

For lists shown on other pages, and for complete lists with filters and pagination, use Collections::render('schedule', [...]) or [hype5_schedule]: they also leave out productions that are not public to everyone, and they load the plugin's stylesheets, which Render::template() alone does not.