#PostQuery

Class.

use Saij\WpAppFramework\Query\PostQuery;

A query for posts of a post class, started with Event::query(), run through WP_Query and returning post objects.

A query never changes: every method returns a changed copy, so a query can be passed on and varied safely. Keep the result – $query->limit(3); alone does nothing, and PHP warns about it (#[\NoDiscard]).

$events = Event::query()
    ->where(EventDetailsFields::capacity()->greaterThan(10))
    ->where(Terms::in(Genre::class, [$jazz]))
    ->orderBy(EventDetailsFields::start())
    ->limit(10)
    ->get();

Defaults: published posts only, all matching posts (no limit), the sort order of WordPress (newest first). The statuses are taken as given, without checking the capabilities of the current user, like save().

#Methods

#author()

author(int $author, int ...$more): static

Posts of one of the authors (user IDs); replaces the authors of earlier calls.

Returns PostQuery

#cache()

cache(int $ttl, array $tags = [], array $vary = []): static

Caches the IDs of the result (and the number of posts) in the cache of the theme or plugin. The tags of the post type and of the taxonomies in the conditions are added: changed posts, meta values and terms invalidate the entry.

Returns PostQuery

#commentCount()

commentCount(int $count, Comparison $comparison = Comparison::Equal): static

Posts whose number of approved comments compares to $count.

Returns PostQuery

#commentStatus()

commentStatus(DiscussionStatus $status): static

Posts whose comments are open or closed.

Returns PostQuery

#count()

count(): int

The number of all matching posts; limit() and offset() do not count.

Returns int

#defaultTemplate()

defaultTemplate(): static

Posts with the default template of their type: no template stored.

Returns PostQuery

#exclude()

exclude(AbstractPost|int ...$posts): static

Not these posts; adds to the posts of earlier calls.

Returns PostQuery

#first()

first(): ?AbstractPost

The first matching post, null without one.

Returns T|null

#format()

format(PostFormat $format, PostFormat ...$more): static

Posts with one of the formats; PostFormat::Standard is a post without format. Replaces the formats of earlier calls.

Returns PostQuery

#get()

get(): array

The matching posts.

Returns list<T>

#hasPassword()

hasPassword(bool $password = true): static

Posts with a password, or with false without one.

Returns PostQuery

#ids()

ids(AbstractPost|int ...$posts): static

Only these posts; without arguments, no posts at all.

Returns PostQuery

#limit()

limit(int $limit): static

At most this many posts; without limit() a query returns all matching posts.

Returns PostQuery

#menuOrder()

menuOrder(int $order): static

Posts with this menu order (page attributes).

Returns PostQuery

#modifiedAfter()

modifiedAfter(DateTimeInterface $time): static

Posts last changed after the time (not at the time).

Returns PostQuery

#modifiedBefore()

modifiedBefore(DateTimeInterface $time): static

Posts last changed before the time (not at the time).

Returns PostQuery

#offset()

offset(int $offset): static

Skips this many posts (needs limit(); get() throws a LogicException without it).

Returns PostQuery

#orderBy()

orderBy(PostOrder|Field $by, Direction $direction = Direction::Asc): static

Sorts by post data or a meta field; further calls sort posts that are equal so far. A post without a stored meta value sorts like the default of the field.

Returns PostQuery

#paginate()

paginate(int $perPage, int $page): PostPage

One page of the matching posts with the number of all of them.

Returns PostPage<T>

Throws LogicException: With limit() or offset(): paginate() sets them itself.

#parent()

parent(AbstractPost|int|null $parent): static

Children of the post (an object or its ID), or top-level posts with null (hierarchical post types).

Returns PostQuery

Throws LogicException: If the post type is not hierarchical.

#parentIn()

parentIn(AbstractPost|int ...$parents): static

Children of one of the posts (hierarchical post types).

Returns PostQuery

Throws LogicException: If the post type is not hierarchical.

#parentNotIn()

parentNotIn(AbstractPost|int ...$parents): static

Posts that are no children of the posts (hierarchical post types).

Returns PostQuery

Throws LogicException: If the post type is not hierarchical.

#pingStatus()

pingStatus(DiscussionStatus $status): static

Posts whose pings (trackbacks, pingbacks) are open or closed.

Returns PostQuery

#publishedAfter()

publishedAfter(DateTimeInterface $time): static

Posts published after the time (not at the time).

Returns PostQuery

#publishedBefore()

publishedBefore(DateTimeInterface $time): static

Posts published before the time (not at the time).

Returns PostQuery

#search()

search(string $text, array $columns = [], bool $exact = false, bool $sentence = false): static

Posts that contain the words, searched like the search of WordPress: in the title, excerpt and content, or in the given columns; with $exact the text must be a whole column value, with $sentence the words are one phrase.

Returns PostQuery

#slug()

slug(string ...$slugs): static

Posts with one of the slugs (post_name).

Returns PostQuery

#status()

status(PostStatus $status, PostStatus ...$more): static

Posts with one of the statuses, instead of published posts only. The capabilities of the current user are not checked. Replaces the statuses of earlier calls.

Returns PostQuery

#sticky()

sticky(bool $sticky = true): static

Sticky posts only, or with false no sticky posts (Post::query() only). The sticky posts are read when the query runs.

Returns PostQuery

Throws LogicException: In a query of another post type than Post.

#template()

template(string ...$slugs): static

Posts with one of the templates, by slug (page-wide for templates/page-wide.html); replaces earlier calls of template() and defaultTemplate().

Returns PostQuery

#title()

title(string $title): static

Posts with exactly this title.

Returns PostQuery

#where()

where(Condition ...$conditions): static

Posts that meet all conditions (meta fields, terms, Any, All); adds to the conditions of earlier calls.

Returns PostQuery

Throws InvalidArgumentException: With a condition on the columns of a table.