PHPackages                             pollen/query - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. pollen/query

ActiveLibrary[Database & ORM](/categories/database)

pollen/query
============

Create WP Query in a fluent way.

1.0(1y ago)18112[1 issues](https://github.com/Pollora/Query/issues)GPL-2.0-or-laterPHPPHP ^8.1.0

Since Oct 21Pushed 1y ago3 watchersCompare

[ Source](https://github.com/Pollora/Query)[ Packagist](https://packagist.org/packages/pollen/query)[ RSS](/packages/pollen-query/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (5)Versions (2)Used By (0)

PostQuery Class
===============

[](#postquery-class)

The `PostQuery` class is a fluent interface for constructing WP\_Query objects in WordPress. This class simplifies the process of building complex queries and provides a more readable and concise way to define query parameters.

- [Advantages](#advantages-of-using-postquery-wrapper)
- [Installation](#installation)
- [Basic Usage](#basic-usage)
- [Author](#author)
- [Category](#category)
- [Tag](#tag)
- [Tax\_Query](#tax_query)
- [Search](#search)
- [Post](#post)
- [Password](#password)
- [Status](#status)
- [Comment Parameter](#comment-parameter)
- [Pagination](#pagination)
- [Order](#order)
- [Date](#date)
- [Meta Query](#meta-query)
- [Permission](#permission)
- [Mimetype](#mimetype)
- [Cache](#cache)

Advantages of Using `PostQuery` Wrapper
---------------------------------------

[](#advantages-of-using-postquery-wrapper)

When using the `PostQuery` wrapper, you gain several advantages over using the original `WP_Query` class for querying posts in WordPress:

1. **Method Chaining**: The `PostQuery` wrapper allows for method chaining, making it easier to construct and read complex queries in a more fluent and readable manner.
2. **Type Safety**: `PostQuery` provides type-hinted methods, reducing the risk of runtime errors by ensuring that the correct data types are used for query parameters.
3. **Readable and Expressive**: The methods in `PostQuery` have descriptive names, making it easier to understand the purpose of each query parameter.
4. **Consistency**: `PostQuery` enforces consistent naming conventions and provides a standardized way to query posts, enhancing code maintainability.
5. **Improved Code Structure**: Using `PostQuery` promotes cleaner and more organized code, separating query logic from the rest of your application.
6. **Reduced Boilerplate**: The wrapper simplifies common tasks, reducing the amount of boilerplate code needed to create queries.
7. **IDE Autocompletion:** Unlike array-based arguments, the `PostQuery` wrapper provides autocompletion support in IDEs, which can significantly improve developer productivity and reduce coding errors.

### Comprehensive Example

[](#comprehensive-example)

Let's consider an example where we want to query posts with specific criteria using the `PostQuery` wrapper and compare it to the equivalent `WP_Query` code. We'll combine various methods to construct a complex query.

#### Using `PostQuery` Wrapper

[](#using-postquery-wrapper)

```
use Pollora\Query\PostQuery;

$results = PostQuery::select()
    ->postType('product')
    ->taxQuery(function (TaxQuery $query) {
        $query->where(
            $query
                ->taxonomy('category')
                ->contains(['tee-shirt', 'sportswear'])
                ->searchByTermSlug()
        );
    })
    ->dateQuery(function (DateQuery $query) {
        $query->where(
            $query
                ->date('posted_at')
                ->between('2021-01-01', '2022-02-01')
        )->orWhere(
            $query->date()->created()->after('2021-01-01')
        );
    })
    ->metaQuery(function (MetaQuery $query) {
        $query
            ->where(
                $query->meta('status')->equalTo('active')
            )->orWhere(
                $query->meta('highlighted')->equalTo(0)
            );
    })
    ->userPermission('readable')
    ->cacheResults()
    ->get();
```

#### Equivalent `WP_Query` Code

[](#equivalent-wp_query-code)

```
new WP_Query([
    'cache_results' => true,
    'date_query' => [
        'relation' => 'OR',
        [
            'column' => 'posted_at',
            'before' =>
                [
                    'year' => '2022',
                    'month' => '02',
                    'day' => '01',
                ],
            'after' =>
                [
                    'year' => '2021',
                    'month' => '01',
                    'day' => '01',
                ],
        ],
        [
            'column' => 'post_date',
            'after' =>
                [
                    'year' => '2021',
                    'month' => '01',
                    'day' => '01',
                ],
        ],
    ],
    'fields' => 'all',
    'meta_query' => [
        'relation' => 'OR',
        [
            'key' => 'status',
            'compare' => '=',
            'value' => 'active',
        ],
        [
            'key' => 'highlighted',
            'compare' => '=',
            'type' => 'BINARY',
            'value' => 0,
        ],
    ],
    'perm' => 'readable',
    'post_type' => 'product',
    'tax_query' => [
        'relation' => 'AND',
        [
            'taxonomy' => 'category',
            'field' => 'slug',
            'terms' =>
                [
                    'tee-shirt',
                    'sportswear',
                ],
            'operator' => 'IN',
            'include_children' => true,
        ],
    ],
]);
```

The table of our good old Wp\_Query is a little complex, isn't it? :)

Installation
------------

[](#installation)

To use the `PostQuery` wrapper in your WordPress project, you need to install the `pollora/query` package using Composer.

If you're not using a WordPress environment that integrate composer, you can follow the steps described [in this article](https://deliciousbrains.com/storing-wordpress-in-git/).

To install Pollora Query, run the following command :

```
composer require pollora/query
```

Composer will download and install the `pollora/query` package and its dependencies.

### Using the `PostQuery` Wrapper

[](#using-the-postquery-wrapper)

Once you've installed the `pollora/query` package and set up Composer in your WordPress environment, you can use the `PostQuery` wrapper to construct and execute WordPress post queries as described in the previous sections.

Now, you're ready to harness the power and simplicity of the `PostQuery` wrapper in your WordPress project to streamline your post queries and improve code readability and maintainability.

Basic Usage
-----------

[](#basic-usage)

To get started with the `PostQuery` class, you can use the `select()` method to specify the fields you want to retrieve and the `get()` method to generate a WP\_Query object with the corresponding arguments.

By default, the `PostQuery` class adopts a more intuitive approach when it comes to querying posts by post type. Unlike the default behavior of WordPress's `WP_Query`, which sets the `post_type` parameter to `'post'` if not specified, the `PostQuery` class assumes a broader scope. It sets the `post_type` parameter to `'all'` by default, indicating that it will search across all post types. This default behavior aligns with a more logical and inclusive approach, ensuring that you can effortlessly query posts of any type without needing to explicitly specify the post type every time you create a query. This simplifies the process and enhances flexibility when constructing your queries.

### Retrieve All Fields

[](#retrieve-all-fields)

```
PostQuery::select()->get(); // Equivalent to PostQuery::select('*')->get();
```

This will generate the following WP\_Query arguments:

```
new WP_Query([
    'fields' => 'all',
    'post_type' => 'any',
]);
```

In this case, the `fields` argument is set to `'all'`, indicating that all fields should be retrieved.

### Specify Specific Fields

[](#specify-specific-fields)

You can use the `select()` method with specific field names to tailor your query to your needs.

```
PostQuery::select('id=>parent')->get();
```

This will generate the following WP\_Query arguments:

```
new WP_Query([
    'fields' => 'id=>parent',
    'post_type' => 'all',
]);
```

Here, the `fields` argument is set to `'id=>parent'`, which means only the 'id' and 'parent' fields will be retrieved.

### Retrieve Only IDs

[](#retrieve-only-ids)

To retrieve only the IDs of the posts, you can use the following code:

```
PostQuery::select('ids')->get();
```

This will generate the following WP\_Query arguments:

```
new WP_Query([
    'fields' => 'ids',
    'post_type' => 'all',
]);
```

In this case, the `fields` argument is set to `'ids'`, indicating that only the post IDs will be returned.

### Find specific post id

[](#find-specific-post-id)

The `find($postID)` method is used to create a WP\_Query instance that retrieves a specific post by its ID. This method simplifies the process of querying a single post and allows you to specify the fields you want to retrieve.

To use the `find()` method, follow these steps:

1. Call the `find($postID)` method on an instance of the `PostQuery` class, passing the desired post ID as a parameter.
2. Chain other methods to further customize the query, such as `fields()`, if needed.
3. Finally, call the `get()` method to generate a WP\_Query object with the specified arguments.

```
PostQuery::find(1) // you can also pass an array of post ids.
    ->fields('ids')
    ->get();
```

This will generate the following WP\_Query arguments:

```
new WP_Query([
    'p' => 1,           // Retrieve the post with ID 1
    'fields' => 'ids',  // Retrieve only the post ID
    'post_type' => 'all',
]);
```

In this example, the `find(1)` method specifies that you want to retrieve the post with ID 1, the `fields('ids')` method indicates that you only want to retrieve the post ID, and the `post_type` argument is set to `'all'`, including all post types in the query.

Author
------

[](#author)

The `PostQuery` class provides several methods for specifying the author(s) of the posts you want to retrieve. These methods allow you to filter posts based on author IDs, author usernames, and author IDs to include or exclude.

### author($authorID)

[](#authorauthorid)

The `author($authorID)` method allows you to query posts authored by a specific user using their user ID. Here's an example:

```
PostQuery::select()
    ->author(1)
    ->get();
```

This will generate the following WP\_Query arguments:

```
new WP_Query([
    'author' => 1,       // Retrieve posts authored by the user with ID 1
    'post_type' => 'all' // Include all post types in the query
]);
```

### authorName($authorUsername)

[](#authornameauthorusername)

The `authorName($authorUsername)` method allows you to query posts authored by a specific user using their username. Here's an example:

```
PostQuery::select()
    ->authorName('taylor')
    ->get();
```

This will generate the following WP\_Query arguments:

```
new WP_Query([
    'author_name' => 'taylor', // Retrieve posts authored by the user with the username 'taylor'
    'post_type' => 'all'      // Include all post types in the query
]);
```

### authorIn($authorIDs)

[](#authorinauthorids)

The `authorIn($authorIDs)` method allows you to query posts authored by one or more users specified by their user IDs. You can pass an array of user IDs to this method. Here's an example:

```
PostQuery::select()
    ->authorIn([1, 2, 3])
    ->get();
```

This will generate the following WP\_Query arguments:

```
new WP_Query([
    'author__in' => [1, 2, 3], // Retrieve posts authored by users with IDs 1, 2, or 3
    'post_type' => 'all'       // Include all post types in the query
]);
```

### authorNotIn($authorIDs)

[](#authornotinauthorids)

The `authorNotIn($authorIDs)` method allows you to exclude posts authored by one or more users specified by their user IDs. You can pass an array of user IDs to this method. Here's an example:

```
PostQuery::select()
    ->authorNotIn([1, 2, 3])
    ->get();
```

This will generate the following WP\_Query arguments:

```
new WP_Query([
    'author__not_in' => [1, 2, 3], // Exclude posts authored by users with IDs 1, 2, or 3
    'post_type' => 'all'           // Include all post types in the query
]);
```

Category
--------

[](#category)

The `PostQuery` class allows you to query posts based on categories using various methods. These methods enable you to filter posts by category ID, category name, and include or exclude categories.

### cat($categoryID)

[](#catcategoryid)

The `cat($categoryID)` method allows you to query posts belonging to a specific category by specifying its category ID. Here's an example:

```
PostQuery::select()
    ->cat(1)
    ->get();
```

This generates the following WP\_Query arguments:

```
new WP_Query([
    'cat' => 1,       // Retrieve posts from category with ID 1
    'post_type' => 'all', // Include all post types in the query
]);
```

### categoryName($categoryName)

[](#categorynamecategoryname)

The `categoryName($categoryName)` method allows you to query posts belonging to a specific category by specifying its name. Here's an example:

```
PostQuery::select()
    ->categoryName('sales')
    ->get();
```

This generates the following WP\_Query arguments:

```
new WP_Query([
    'category_name' => 'sales', // Retrieve posts from the 'sales' category
    'post_type' => 'all',       // Include all post types in the query
]);
```

### categoryIn($categoryIDs)

[](#categoryincategoryids)

The `categoryIn($categoryIDs)` method allows you to include posts from one or more categories specified by their category IDs. You can pass an array of category IDs to this method. Here's an example:

```
PostQuery::select()
    ->categoryIn([1, 2, 3])
    ->get();
```

This generates the following WP\_Query arguments:

```
new WP_Query([
    'category__in' => [1, 2, 3], // Include posts from categories with IDs 1, 2, or 3
    'post_type' => 'all',        // Include all post types in the query
]);
```

### categoryNotIn($categoryIDs)

[](#categorynotincategoryids)

The `categoryNotIn($categoryIDs)` method allows you to exclude posts from one or more categories specified by their category IDs. You can pass an array of category IDs to this method. Here's an example:

```
PostQuery::select()
    ->categoryNotIn([1, 2, 3])
    ->get();
```

This generates the following WP\_Query arguments:

```
new WP_Query([
    'category__not_in' => [1, 2, 3], // Exclude posts from categories with IDs 1, 2, or 3
    'post_type' => 'all',           // Include all post types in the query
]);
```

Tag
---

[](#tag)

The `PostQuery` class allows you to query posts based on tags using various methods. These methods enable you to filter posts by tag name, tag ID, tag slugs, and include or exclude tags.

### tag($tagName)

[](#tagtagname)

The `tag($tagName)` method allows you to query posts associated with a specific tag by specifying its name. Here's an example:

```
PostQuery::select()
    ->tag('programming')
    ->get();
```

This generates the following WP\_Query arguments:

```
new WP_Query([
    'tag' => 'programming', // Retrieve posts associated with the 'programming' tag
    'post_type' => 'all',   // Include all post types in the query
]);
```

### tagId($tagID)

[](#tagidtagid)

The `tagId($tagID)` method allows you to query posts associated with a specific tag by specifying its ID. Here's an example:

```
PostQuery::select()
    ->tagId(1)
    ->get();
```

This generates the following WP\_Query arguments:

```
new WP_Query([
    'tag_id' => 1,       // Retrieve posts associated with the tag with ID 1
    'post_type' => 'all', // Include all post types in the query
]);
```

### tagAnd($tagIDs)

[](#tagandtagids)

The `tagAnd($tagIDs)` method allows you to query posts that are associated with all of the specified tags by specifying their IDs. You can pass an array of tag IDs to this method. Here's an example:

```
PostQuery::select()
    ->tagAnd([1, 2])
    ->get();
```

This generates the following WP\_Query arguments:

```
new WP_Query([
    'tag__and' => [1, 2], // Retrieve posts associated with both tags with IDs 1 and 2
    'post_type' => 'all', // Include all post types in the query
]);
```

### tagIn($tagIDs)

[](#tagintagids)

The `tagIn($tagIDs)` method allows you to query posts associated with one or more tags by specifying their IDs. You can pass an array of tag IDs to this method. Here's an example:

```
PostQuery::select()
    ->tagIn([3, 4])
    ->get();
```

This generates the following WP\_Query arguments:

```
new WP_Query([
    'tag__in' => [3, 4], // Retrieve posts associated with tags with IDs 3 or 4
    'post_type' => 'all', // Include all post types in the query
]);
```

### tagNotIn($tagIDs)

[](#tagnotintagids)

The `tagNotIn($tagIDs)` method allows you to exclude posts associated with one or more tags by specifying their IDs. You can pass an array of tag IDs to this method. Here's an example:

```
PostQuery::select()
    ->tagNotIn([5, 6])
    ->get();
```

This generates the following WP\_Query arguments:

```
new WP_Query([
    'tag__not_in' => [5, 6], // Exclude posts associated with tags with IDs 5 or 6
    'post_type' => 'all',    // Include all post types in the query
]);
```

### tagSlugAnd($tagSlugs)

[](#tagslugandtagslugs)

The `tagSlugAnd($tagSlugs)` method allows you to query posts that are associated with all of the specified tags by specifying their slugs. You can pass an array of tag slugs to this method. Here's an example:

```
PostQuery::select()
    ->tagSlugAnd(['dev', 'qa'])
    ->get();
```

This generates the following WP\_Query arguments:

```
new WP_Query([
    'tag_slug__and' => ['dev', 'qa'], // Retrieve posts associated with both 'dev' and 'qa' tags
    'post_type' => 'all',            // Include all post types in the query
]);
```

### tagSlugIn($tagSlugs)

[](#tagslugintagslugs)

The `tagSlugIn($tagSlugs)` method allows you to query posts associated with one or more tags by specifying their slugs. You can pass an array of tag slugs to this method. Here's an example:

```
PostQuery::select()
    ->tagSlugIn(['frontend', 'backend'])
    ->get();
```

This generates the following WP\_Query arguments:

```
new WP_Query([
    'tag_slug__in' => ['frontend', 'backend'], // Retrieve posts associated with 'frontend' or 'backend' tags
    'post_type' => 'all',                     // Include all post types in the query
]);
```

Tax\_Query
----------

[](#tax_query)

The `PostQuery` class allows you to filter posts based on taxonomy terms using the `taxQuery()` method. This method provides a powerful way to construct complex queries involving taxonomy terms and their relationships.

### Simple tax query

[](#simple-tax-query)

In its simplest form, you can use the `taxQuery()` method to filter posts by a single taxonomy and a list of terms. For example:

```
PostQuery::select()
    ->taxQuery(function (TaxQuery $query) {
        $query->where(
            $query
                ->taxonomy('category')
                ->contains(['tee-shirt', 'sportswear'])
                ->searchByTermSlug()
        );
    })
    ->get();
```

This generates the following WP\_Query arguments:

```
new WP_Query([
    'post_type' => 'all',
    'tax_query' => [
        'relation' => 'AND',
        [
            'taxonomy' => 'category',
            'field' => 'slug',
            'terms' => ['tee-shirt', 'sportswear'],
            'operator' => 'IN',
            'include_children' => true,
        ],
    ],
]);
```

### 'OR' Relation

[](#or-relation)

You can also use the 'OR' relation to query posts that match any of the specified taxonomy conditions. For example:

```
PostQuery::select()
    ->taxQuery(function (TaxQuery $query) {
        $query->where(
            $query
                ->taxonomy('category')
                ->contains([10, 20])
                ->searchById()
        )->orWhere(
            $query
                ->taxonomy('event')
                ->contains(['black-friday', 'christmas-sales'])
                ->searchByTermSlug()
        );
    })
    ->get();
```

This generates the following WP\_Query arguments:

```
new WP_Query([
    'post_type' => 'all',
    'tax_query' => [
        'relation' => 'OR',
        [
            'taxonomy' => 'category',
            'field' => 'term_id',
            'terms' => [10, 20],
            'operator' => 'IN',
            'include_children' => true,
        ],
        [
            'taxonomy' => 'event',
            'field' => 'slug',
            'terms' => ['black-friday', 'christmas-sales'],
            'operator' => 'IN',
            'include_children' => true,
        ],
    ],
]);
```

### Nested Conditions

[](#nested-conditions)

You can also create nested conditions within the Tax\_Query. In the following example, we use nested conditions with 'OR' and 'AND' relations:

```
PostQuery::select()
    ->taxQuery(function (TaxQuery $query) {
        $query
            ->where(
                $query->taxonomy('status')->notContains(['private'])
            )
            ->orWhere(function (TaxQuery $query) {
                $query
                    ->where(
                        $query->taxonomy('attributes')->exists()
                    )
                    ->orWhere(
                        $query->taxonomy('product_cat')->contains(['tee-shirt', 'sportswear'])
                    );
            })
            ->orWhere(function (TaxQuery $query) {
                $query
                    ->where(
                        $query->taxonomy('promo_cat')->contains(['summer', 'blackfriday'])
                    )
                    ->andWhere(
                        $query->taxonomy('new_products')->notExists()
                    );
            });
    })
    ->get();
```

This generates the following WP\_Query arguments:

```
new WP_Query([
    'post_type' => 'all',
    'tax_query' => [
        'relation' => 'OR',
        [
            'taxonomy' => 'status',
            'field' => 'term_id',
            'terms' => [
                'private',
            ],
            'operator' => 'NOT IN',
            'include_children' => true,
        ],
        [
            'relation' => 'OR',
            [
                'taxonomy' => 'attributes',
                'field' => 'term_id',
                'terms' => null,
                'operator' => 'EXISTS',
                'include_children' => true,
            ],
            [
                'taxonomy' => 'product_cat',
                'field' => 'term_id',
                'terms' => [
                    'tee-shirt',
                    'sportswear',
                ],
                'operator' => 'IN',
                'include_children' => true,
            ],
        ],
        [
            'relation' => 'AND',
            [
                'taxonomy' => 'promo_cat',
                'field' => 'term_id',
                'terms' => [
                    'summer',
                    'blackfriday',
                ],
                'operator' => 'IN',
                'include_children' => true,
            ],
            [
                'taxonomy' => 'new_products',
                'field' => 'term_id',
                'terms' => null,
                'operator' => 'NOT EXISTS',
                'include_children' => true,
            ],
        ],
    ],
])
```

Search
------

[](#search)

The `PostQuery` class allows you to perform keyword-based searches on posts using the `search()` method. This method helps you filter posts that match a specific keyword or phrase.

### search($keyword)

[](#searchkeyword)

The `search($keyword)` method allows you to perform a keyword-based search for posts. You can specify the desired keyword or phrase as a parameter. Here's an example:

```
PostQuery::select()
    ->search('my keyword')
    ->get();
```

This generates the following WP\_Query argument:

```
new WP_Query([
    's' => 'my keyword', // Perform a keyword-based search for posts containing 'my keyword'
    'post_type' => 'all',
]);
```

Post
----

[](#post)

The `PostQuery` class provides methods for filtering posts based on various post-related parameters. These methods allow you to specify the post type, post ID, post slug, post parent, and more.

### postType($type)

[](#posttypetype)

The `postType($type)` method allows you to specify the post type you want to query. You can provide the post type as a parameter. Here's an example:

```
PostQuery::select()
    ->postType('article')
    ->get();
```

This generates the following WP\_Query argument:

```
new WP_Query([
    'post_type' => 'article', // Retrieve posts of the 'article' post type
]);
```

### postId($id)

[](#postidid)

The `postId($id)` method allows you to query a specific post by its ID. You can provide the post ID as a parameter. For example:

```
PostQuery::select()
    ->postId(42)
    ->get();
```

This generates the following WP\_Query argument:

```
new WP_Query([
    'p' => 42, // Retrieve the post with ID 42
    'post_type' => 'all'
]);
```

### postSlug($slug)

[](#postslugslug)

The `postSlug($slug)` method allows you to query a specific post by its slug. You can provide the post slug as a parameter. For example:

```
PostQuery::select()
    ->postSlug('mon-article')
    ->get();
```

This generates the following WP\_Query argument:

```
new WP_Query([
    'name' => 'mon-article', // Retrieve the post with the slug 'mon-article'
    'post_type' => 'all'
]);
```

### postParent($parentID)

[](#postparentparentid)

The `postParent($parentID)` method allows you to query posts that have a specific parent post. You can provide the parent post ID as a parameter. For example:

```
PostQuery::select()
    ->postParent(5)
    ->get();
```

This generates the following WP\_Query argument:

```
new WP_Query([
    'post_parent' => 5, // Retrieve posts with a parent post of ID 5
    'post_type' => 'all',
]);
```

### whereParentIn($parentIDs)

[](#whereparentinparentids)

The `whereParentIn($parentIDs)` method allows you to query posts that have parent posts specified by their IDs. You can pass an array of parent post IDs to this method. For example:

```
PostQuery::select()
    ->whereParentIn([1, 2, 3])
    ->get();
```

This generates the following WP\_Query argument:

```
new WP_Query([
    'post_parent__in' => [1, 2, 3], // Retrieve posts with parent post IDs in the array
    'post_type' => 'all'
]);
```

### whereParentNotIn($parentIDs)

[](#whereparentnotinparentids)

The `whereParentNotIn($parentIDs)` method allows you to exclude posts that have parent posts specified by their IDs. You can pass an array of parent post IDs to this method. For example:

```
PostQuery::select()
    ->whereParentNotIn([4, 5, 6])
    ->get();
```

This generates the following WP\_Query argument:

```
new WP_Query([
    'post_parent__not_in' => [4, 5, 6], // Exclude posts with parent post IDs in the array
    'post_type' => 'all'
]);
```

### whereIn($postIDs)

[](#whereinpostids)

The `whereIn($postIDs)` method allows you to query posts with specific IDs. You can pass an array of post IDs to this method. For example:

```
PostQuery::select()
    ->whereIn([7, 8, 9])
    ->get();
```

This generates the following WP\_Query argument:

```
new WP_Query([
    'post__in' => [7, 8, 9], // Retrieve posts with IDs in the array
    'post_type' => 'all'
]);
```

### whereNotIn($postIDs)

[](#wherenotinpostids)

The `whereNotIn($postIDs)` method allows you to exclude posts with specific IDs. You can pass an array of post IDs to this method. For example:

```
PostQuery::select()
    ->whereNotIn([10, 11, 12])
    ->get();
```

This generates the following WP\_Query argument:

```
new WP_Query([
    'post__not_in' => [10, 11, 12], // Exclude posts with IDs in the array
    'post_type' => 'all'
]);
```

### slugIn($slugs)

[](#sluginslugs)

The `slugIn($slugs)` method allows you to query posts with specific slugs. You can pass an array of post slugs to this method. For example:

```
PostQuery::select()
    ->slugIn(['slug-1', 'slug-2'])
    ->get();
```

This generates the following WP\_Query argument:

```
new WP_Query([
    'post_name__in' => ['slug-1', 'slug-2'], // Retrieve posts with slugs in the array
    'post_type' => 'all'
]);
```

### Note: 'pagename' and 'page\_id'

[](#note-pagename-and-page_id)

Unlike WP\_Query, the `PostQuery` class does not provide separate methods for 'pagename' and 'page\_id' parameters. Instead, you can use 'name' and 'p' parameters while specifying the 'post\_type' as 'page' to achieve the equivalent results:

```
PostQuery::select()
    ->postType('page')
    ->postSlug('my-page')
    ->get();
```

This generates the following WP\_Query argument:

```
new WP_Query([
    'post_type' => 'page',   // Query for pages
    'name' => 'my-page',     // Specify the page slug
    'post_type' => 'all'
]);
```

Password
--------

[](#password)

The `PostQuery` class provides methods to filter posts based on their password protection status and the specific post password.

### withPassword()

[](#withpassword)

The `withPassword()` method allows you to query posts that have a password protection set. You can use this method to retrieve posts that require a password to access. For example:

```
PostQuery::select()
    ->withPassword()
    ->get();
```

This generates the following WP\_Query argument:

```
new WP_Query([
    'has_password' => true, // Retrieve posts with password protection
    'post_type' => 'all'
]);
```

### withoutPassword()

[](#withoutpassword)

The `withoutPassword()` method allows you to query posts that do not have a password protection set. You can use this method to exclude posts that require a password to access. For example:

```
PostQuery::select()
    ->withoutPassword()
    ->get();
```

This generates the following WP\_Query argument:

```
new WP_Query([
    'has_password' => false, // Exclude posts with password protection
    'post_type' => 'all'
]);
```

### withPassword($password)

[](#withpasswordpassword)

The `withPassword($password)` method allows you to query posts that have a specific post password set. You can provide the desired post password as a parameter. For example:

```
PostQuery::select()
    ->withPassword('zxcvbn')
    ->get();
```

This generates the following WP\_Query argument:

```
new WP_Query([
    'post_password' => 'zxcvbn', // Retrieve posts with the specified post password
    'post_type' => 'all'
]);
```

Status
------

[](#status)

The `PostQuery` class allows you to filter posts based on their status using the `postStatus()` method. This method helps you query posts with a specific status.

### postStatus($status)

[](#poststatusstatus)

The `postStatus($status)` method allows you to specify the status of posts you want to retrieve. You can provide the desired status as a parameter. For example:

```
PostQuery::select()
    ->postStatus('publish')
    ->get();
```

This generates the following WP\_Query argument:

```
new WP_Query([
    'post_status' => 'publish', // Retrieve posts with the 'publish' status
    'post_type' => 'all'
]);
```

You can use this method to query posts with different statuses such as 'publish,' 'draft,' 'pending,' or custom statuses defined in your WordPress installation. It provides precise control over the status of the posts you retrieve in your queries.

Comment Parameter
-----------------

[](#comment-parameter)

The `PostQuery` class provides a method to filter posts based on the number of comments they have using the `commentCount()` method. This method allows you to retrieve posts with a specific number of comments.

### commentCount($count)

[](#commentcountcount)

The `commentCount($count)` method allows you to specify the number of comments a post should have in order to be retrieved in the query. You can provide the desired comment count as a parameter. For example:

```
PostQuery::select()
    ->commentCount(1)
    ->get();
```

This generates the following WP\_Query argument:

```
new WP_Query([
    'comment_count' => 1, // Retrieve posts with exactly 1 comment
]);
```

Pagination
----------

[](#pagination)

The `PostQuery` class provides methods to control the pagination of query results. These methods allow you to specify the number of posts to retrieve per page, skip a certain number of posts, and more.

### take($count), limit($count) or postsPerPage($count)

[](#takecount-limitcount-or-postsperpagecount)

The `take($count)`, `limit($count)`, and `postsPerPage($count)` methods allow you to specify the number of posts to retrieve per page. You can provide the desired post count as a parameter. For example:

```
PostQuery::select()
    ->take(5)
    ->get();
```

These methods generate the following WP\_Query argument:

```
new WP_Query([
    'posts_per_page' => 5, // Retrieve 5 posts per page
]);
```

You can use these methods to control the number of posts displayed on each page of your query results.

### skip($count) or offset($count)

[](#skipcount-or-offsetcount)

The `skip($count)` and `offset($count)` methods allow you to skip a certain number of posts in the query results. You can provide the desired skip count as a parameter. For example:

```
PostQuery::select()
    ->skip(5)
    ->get();
```

These methods generate the following WP\_Query argument:

```
new WP_Query([
    'offset' => 5, // Skip the first 5 posts in the query results
]);
```

You can use these methods to skip a specific number of posts, useful for creating paginated queries.

### noPaging()

[](#nopaging)

The `noPaging()` method allows you to disable pagination entirely, retrieving all posts matching the query without any pagination. For example:

```
PostQuery::select()
    ->noPaging()
    ->get();
```

This generates the following WP\_Query argument:

```
new WP_Query([
    'nopaging' => true, // Retrieve all posts without pagination
]);
```

Use this method when you want to retrieve all matching posts in a single query, regardless of the number.

### postsPerArchivePage($count)

[](#postsperarchivepagecount)

The `postsPerArchivePage($count)` method allows you to specify the number of posts to display per archive page. This is particularly useful for archive pages like category or tag archives. For example:

```
PostQuery::select()
    ->postsPerArchivePage(5)
    ->get();
```

This generates the following WP\_Query argument:

```
new WP_Query([
    'posts_per_archive_page' => 5, // Display 5 posts per archive page
]);
```

You can use this method to control the number of posts displayed on archive pages.

### page($pageNumber)

[](#pagepagenumber)

The `page($pageNumber)` method allows you to specify the page number when paginating query results. You can provide the desired page number as a parameter. For example:

```
PostQuery::select()
    ->page(666)
    ->get();
```

This generates the following WP\_Query argument:

```
new WP_Query([
    'page' => 666, // Retrieve results for page number 666
]);
```

Use this method when you want to retrieve a specific page of results in a paginated query.

### ignoreStickyPosts()

[](#ignorestickyposts)

The `ignoreStickyPosts()` method allows you to exclude sticky posts from the query results. Sticky posts are posts that are pinned to the top of the list. For example:

```
PostQuery::select()
    ->ignoreStickyPosts()
    ->get();
```

This generates the following WP\_Query argument:

```
new WP_Query([
    'ignore_sticky_posts' => true, // Exclude sticky posts from the query
]);
```

Order
-----

[](#order)

The `PostQuery` class provides methods to control the order in which posts are retrieved. You can specify one or more orderby parameters to sort the query results based on various criteria.

### orderBy($field, $order = 'DESC')

[](#orderbyfield-order--desc)

The `orderBy($field, $order = 'DESC')` method allows you to specify the field by which the posts should be ordered and the order in which they should be sorted. You can provide the desired field and order as parameters. For example:

```
PostQuery::select()
    ->orderBy('most_comments')
    ->orderBy('post_date', 'ASC')
    ->get();
```

This method generates the following WP\_Query argument:

```
new WP_Query([
    'orderby' => [
        'most_comments' => 'DESC', // Order by 'most_comments' in descending order
        'post_date' => 'ASC',      // Then order by 'post_date' in ascending order
    ],
]);
```

Date
----

[](#date)

The `PostQuery` class allows you to query posts based on date-related criteria using the `DateQuery` class. This class provides methods to create complex date queries, allowing you to filter posts by their publication, modification, or custom dates.

### `dateQuery($callback)`

[](#datequerycallback)

The `dateQuery($callback)` method allows you to define a complex date query using the `DateQuery` class. You can pass a callback function to create the date query conditions. For example:

```
PostQuery::select()->dateQuery(function (DateQuery $query) {
    $query
        ->where(
            $query->date('edited_at')->before('2022-01-01')->after([
                'year' => '2021',
                'month' => '01',
                'day' => '01',
            ])
        )
        ->inclusive();
})->get();
```

This method generates the following WP\_Query argument:

```
new WP_Query([
    'date_query' => [
        'relation' => 'AND',
        [
            'column' => 'edited_at',
            'before' => [
                'year' => 2022,
                'month' => 1,
                'day' => 1,
                'hour' => 12,
                'minute' => 0,
                'second' => 0,
            ],
            'after' => [
                'year' => 2021,
                'month' => 1,
                'day' => 1,
            ],
        ],
        'inclusive' => true,
    ],
]);
```

You can use this method to create complex date queries that include conditions like before, after, and inclusive/exclusive settings.

### `date($column = 'post_date')`

[](#datecolumn--post_date)

The `date($column = 'post_date')` method within the `DateQuery` class allows you to specify the column or type of date to query. You can choose from 'post\_date,' 'post\_modified,' or other custom date columns. For example:

```
$query->date('edited_at');
```

### `before($date)`

[](#beforedate)

The `before($date)` method within the `DateQuery` class allows you to specify that the date should be before a certain point in time. You can provide the date in various formats, such as 'YYYY-MM-DD' or an array specifying 'year,' 'month,' 'day,' 'hour,' 'minute,' and 'second.'

### `after($date)`

[](#afterdate)

The `after($date)` method within the `DateQuery` class allows you to specify that the date should be after a certain point in time. Like the `before()` method, you can provide the date in various formats.

### `between($start, $end)`

[](#betweenstart-end)

The `between($start, $end)` method within the `DateQuery` class allows you to specify that the date should be between two points in time. You can provide the start and end dates in various formats.

### `created()`

[](#created)

The `modified()` method within the `DateQuery` class allows you to specify that the date query should apply to the last modified date of the post, as opposed to the default 'post\_date' column. This is useful for distinguishing between post creation and modification dates.

### `inclusive()`

[](#inclusive)

The `inclusive()` method within the `DateQuery` class allows you to specify that the date query should include posts that match the exact date and time specified. This is particularly useful when using the `before()` and `after()` methods.

Meta Query
----------

[](#meta-query)

The `PostQuery` class allows you to perform custom queries based on post metadata using the `MetaQuery` class. This class provides methods to create complex meta queries, allowing you to filter posts based on custom field values.

### `metaQuery($callback)`

[](#metaquerycallback)

The `metaQuery($callback)` method allows you to define a complex meta query using the `MetaQuery` class. You can pass a callback function to create the meta query conditions. For example:

```
PostQuery::select()->metaQuery(function (MetaQuery $query) {
    $query->where(
        $query->meta('status')->equalTo('active')
    );
})->get();
```

This method generates the following WP\_Query argument:

```
new WP_Query([
    'meta_query' => [
        'relation' => 'AND',
        [
            'key' => 'status',
            'compare' => '=',
            'type' => 'CHAR',
            'value' => 'active',
        ],
    ],
]);
```

### meta($key)

[](#metakey)

The `meta($key)` method within the `MetaQuery` class allows you to specify the custom field key you want to query. For example:

### Comparison Methods

[](#comparison-methods)

The `MetaQuery` class offers several methods to specify the comparison operations to perform on custom fields. You can chain these methods to build complex conditions.

#### ofType($type)

[](#oftypetype)

This method allows you to specify the type of comparison to use. Possible types are class constants such as `MetaQueryBuilder::NUMERIC`, `MetaQueryBuilder::CHAR`, `MetaQueryBuilder::DATE`, etc. By default, the type is automatically determined based on the value provided during comparison.

Example of usage:

```
$query->meta('my_post_meta')->ofType('numeric'); // You can also use a number
```

##### Note :

[](#note-)

The `detectValueType` method is used internally to automatically determine the data type of the value provided during comparison. It is called automatically when you use other comparison methods.

This method performs the following checks to determine the data type:

- If the value is an array, it takes the data type of the first element.
- If a data type is explicitly set using the `ofType` method, it uses that data type.
- If the value is `null`, it defaults to the `CHAR` data type.
- If the value is `0` or `1`, it uses the `BINARY` data type.
- If the value is a negative integer, it uses the `SIGNED` data type.
- If the value is a non-negative integer, it uses the `UNSIGNED` data type.
- If the value is a floating-point number, it uses the `DECIMAL` data type.
- If the value is a string containing only a numeric date (e.g., '2022-01-01'), it uses the `DATE` data type.
- If the value is a string containing only a numeric time (e.g., '12:00:00'), it uses the `TIME` data type.
- If the value is a string containing both date and time (e.g., '2022-01-01 12:00:00'), it uses the `DATETIME` data type.
- If none of the above conditions apply, it defaults to the `CHAR` data type.

#### equalTo($value)

[](#equaltovalue)

This method specifies that the custom field must be equal to a certain value.

Example of usage:

```
$query->meta('my_post_meta')->equalTo('active'); // You can also use a number
```

#### notEqualTo(mixed $value)

[](#notequaltomixed-value)

This method specifies that the custom field must not be equal to a certain value.

Example of usage:

```
$query->meta('my_post_meta')->notEqualTo('inactive');
```

#### greaterThan($value)

[](#greaterthanvalue)

This method specifies that the custom field must be greater than a certain value.

Example of usage:

```
$query->meta('my_post_meta')->greaterThan(100);
```

#### greaterOrEqualTo($value)

[](#greaterorequaltovalue)

This method specifies that the custom field must be greater than or equal to a certain value.

Example of usage:

```
$query->meta('my_post_meta')->greaterOrEqualTo(100);
```

#### lessThan($value)

[](#lessthanvalue)

This method specifies that the custom field must be less than a certain value.

Example of usage:

```
$query->meta('my_post_meta')->lessThan(5);
```

#### lessOrEqualTo($value)

[](#lessorequaltovalue)

This method specifies that the custom field must be less than or equal to a certain value.

Example of usage:

```
$query->meta('my_post_meta')->lessOrEqualTo(5);
```

#### `between(mixed $lowerBoundary, mixed $upperBoundary): self`

[](#betweenmixed-lowerboundary-mixed-upperboundary-self)

This method specifies that the custom field must be between two given values.

Example of usage:

```
$query->meta('my_post_meta')->between('2022-01-01', '2022-12-31');
```

#### notBetween($lowerBoundary, $upperBoundary)

[](#notbetweenlowerboundary-upperboundary)

This method specifies that the custom field must not be between two given values.

Example of usage:

```
$query->meta('my_post_meta')->notBetween('2022-01-01', '2022-12-31');
```

#### `like(string $value): self`

[](#likestring-value-self)

This method specifies a partial match of the custom field with a string.

Example of usage:

```
$query->meta('my_post_meta')->like('keyword');
```

#### notLike($value)

[](#notlikevalue)

This method specifies that the custom field must not partially match a string.

Example of usage:

```
$query->meta('my_post_meta')->notLike('excluded');
```

#### in($values)

[](#invalues)

This method specifies that the custom field must match one of the values in a given array.

Example of usage:

```
$query->meta('my_post_meta')->in(['value1', 'value2', 'value3']);
```

#### notIn($values)

[](#notinvalues)

This method specifies that the custom field must not match any of the values in a given array.

Example of usage:

```
$query->meta('my_post_meta')->notIn(['excluded1', 'excluded2']);
```

#### state($value)

[](#statevalue)

The `state($value)` method within the `MetaQuery` class allows you to use the named meta queries and use this state for ordering. See [this section of the documentation](https://developer.wordpress.org/reference/classes/wp_query/#order-orderby-parameters) for more information.

Example of usage:

```
PostQuery::select()
    ->metaQuery(function (MetaQuery $query) {
        $query
            ->where(
                $query
                ->meta('menu_order')
                    ->state('menu_order_state')
                    ->greaterThan(10)
            );

    })
    ->orderBy('menu_order_state', 'ASC')
    ->get();
```

#### exists()

[](#exists)

This method specifies that the custom field must exist (be defined).

Example of usage:

```
$query->meta('my_post_meta')->exists();
```

#### notExists()

[](#notexists)

This method specifies that the custom field must not exist (not be defined).

Example of usage:

```
$query->meta('my_post_meta')->notExists();
```

### `metaQuery` Method Chaining

[](#metaquery-method-chaining)

You can chain multiple `meta()` methods to create complex meta queries. For example:

```
PostQuery::select()->metaQuery(function (MetaQuery $query) {
    $query
        ->where(
            $query->meta('status')->equalTo('active')
        )
        ->orWhere(
            $query->meta('highlighted')->equalTo(1)
        );

})->get();
```

This generates a meta query with an 'OR' relation between the two conditions.

### Nested Meta Queries

[](#nested-meta-queries)

You can create nested meta queries by using the `MetaQuery` class within the `metaQuery()` callback. This allows you to create complex meta queries with multiple levels of conditions. For example:

```
PostQuery::select()
    ->metaQuery(function (MetaQuery $query) {
        $query
            ->where(
                $query->meta('status')->equalTo('active')
            )
            ->orWhere(function (MetaQuery $query) {
                $query
                    ->where(
                        $query->meta('_sku')->equalTo('H123456789')
                    )
                    ->orWhere(
                        $query->meta('_sku')->equalTo('D123456784')
                    );
            })
            ->orWhere(function (MetaQuery $query) {
                $query
                    ->where(
                        $query->meta('promo_cat')->notIn(['summer', 'blackfriday'])->state('promo_cat')
                    )
                    ->andWhere(
                        $query->meta('promo_cat')->notEqualTo('sales')
                    );
            })
            ->orWhere(
                $query->meta('sale_date')
                    ->between('2024-01-01', '2024-12-31')
            );

    })
    ->orderBy('promo_cat')
    ->get();
```

Permission
----------

[](#permission)

The `PostQuery` class allows you to query posts based on specific user permissions. You can use the following permission parameters to filter posts based on their accessibility to users.

### `userPermission(string $permission)`

[](#userpermissionstring-permission)

The `userPermission` method is used to filter posts based on user permissions. It accepts one parameter:

- `$permission` (string): Specifies the type of permission to filter posts by. Valid values include:

    - `'readable'`: This permission filters posts that the user can read.
    - `'editable'`: This permission filters posts that the user can edit.

#### Filter posts that the user can read.

[](#filter-posts-that-the-user-can-read)

```
PostQuery::select()
    ->userPermission('readable')
    ->get();
```

This method generates the following WP\_Query argument:

```
new WP_Query([
    'perm' => 'readable',
    'post_type' => 'all',
]);
```

#### Filter posts that the user can edit.

[](#filter-posts-that-the-user-can-edit)

```
PostQuery::select()
    ->userPermission('editable')
    ->get();
```

This method generates the following WP\_Query argument:

```
new WP_Query([
    'perm' => 'editable',
    'post_type' => 'all',
]);
```

#### Invalid permissions

[](#invalid-permissions)

```
PostQuery::select()
    ->userPermission('invalid')
    ->get();
```

When an invalid permission is provided, all posts are returned in the generated WP\_Query:

```
new WP_Query([
    'post_type' => 'all',
]);
```

Mimetype
--------

[](#mimetype)

The `PostQuery` class allows you to filter posts based on their MIME types. You can use the `postMimeType` method to specify the MIME type(s) you want to filter by.

### `postMimeType(string|array $mimeTypes)`

[](#postmimetypestringarray-mimetypes)

The `postMimeType` method filters posts based on MIME type(s). It accepts one parameter:

- `$mimeTypes` (string|array): Specifies the MIME type(s) to filter posts by. You can provide a single MIME type as a string or an array of multiple MIME types.

#### Filter posts by a single MIME type (e.g., 'image/gif').

[](#filter-posts-by-a-single-mime-type-eg-imagegif)

```
PostQuery::select()
    ->postMimeType('image/gif')
    ->get();
```

This method generates the following WP\_Query argument:

```
new WP_Query([
    'post_mime_type' => 'image/gif',
    'post_type' => 'all',
]);
```

#### Filter posts by an array of MIME types.

[](#filter-posts-by-an-array-of-mime-types)

```
PostQuery::select()
    ->postMimeType(['image/jpeg', 'image/gif', 'image/png', 'image/bmp', 'image/tiff', 'image/x-icon'])
    ->get();
```

This method generates the following WP\_Query argument:

```
new WP_Query([
    'post_mime_type' => ['image/jpeg', 'image/gif', 'image/png', 'image/bmp', 'image/tiff', 'image/x-icon'],
    'post_type' => 'all',
]);
```

Cache
-----

[](#cache)

The `PostQuery` class provides methods for controlling caching behavior when querying posts.

### cacheResults()

[](#cacheresults)

The `cacheResults` method enables caching of query results. When you use this method, the query results will be cached for faster retrieval. It doesn't accept any parameters.

```
PostQuery::select()
    ->cacheResults()
    ->get();
```

This method generates the following WP\_Query argument:

```
new WP_Query([
    'cache_results' => true,
    'post_type' => 'all',
]);
```

### updateMetaCache($update)

[](#updatemetacacheupdate)

The `updateMetaCache` method allows you to control whether post meta data is cached. You can specify whether to update the post meta cache or not using this method.

- `$update` (bool): Pass `true` to update the post meta cache or `false` to disable it.

```
PostQuery::select()
    ->updateMetaCache(false)
    ->get();
```

This method generates the following WP\_Query argument:

```
new WP_Query([
    'update_post_meta_cache' => false,
    'post_type' => 'all',
]);
```

### updateTermCache($update)

[](#updatetermcacheupdate)

The `updateTermCache` method allows you to control whether post term data is cached. You can specify whether to update the post term cache or not using this method.

- `$update` (bool): Pass `true` to update the post term cache or `false` to disable it.

```
PostQuery::select()
    ->updateTermCache(true)
    ->get();
```

This method generates the following WP\_Query argument:

```
new WP_Query([
    'update_post_term_cache' => true,
    'post_type' => 'all',
]);
```

###  Health Score

29

—

LowBetter than 60% of packages

Maintenance36

Infrequent updates — may be unmaintained

Popularity17

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity47

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

567d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/8435080f3e74b629258f291a62cb72aa9d63ee44d74e588f594dc6378c328fa2?d=identicon)[amphibee](/maintainers/amphibee)

---

Top Contributors

[![ogorzalka](https://avatars.githubusercontent.com/u/149651?v=4)](https://github.com/ogorzalka "ogorzalka (13 commits)")

###  Code Quality

TestsPest

Static AnalysisRector

### Embed Badge

![Health badge](/badges/pollen-query/health.svg)

```
[![Health](https://phpackages.com/badges/pollen-query/health.svg)](https://phpackages.com/packages/pollen-query)
```

###  Alternatives

[doctrine/orm

Object-Relational-Mapper for PHP

10.2k285.3M6.2k](/packages/doctrine-orm)[jdorn/sql-formatter

a PHP SQL highlighting library

3.9k115.1M102](/packages/jdorn-sql-formatter)[illuminate/database

The Illuminate Database package.

2.8k52.4M9.4k](/packages/illuminate-database)[mongodb/mongodb

MongoDB driver library

1.6k64.0M546](/packages/mongodb-mongodb)[ramsey/uuid-doctrine

Use ramsey/uuid as a Doctrine field type.

90340.3M211](/packages/ramsey-uuid-doctrine)[reliese/laravel

Reliese Components for Laravel Framework code generation.

1.7k3.4M16](/packages/reliese-laravel)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)