{"id":21882686,"url":"https://github.com/jjgrainger/query","last_synced_at":"2025-04-15T06:06:22.239Z","repository":{"id":40242088,"uuid":"239143623","full_name":"jjgrainger/Query","owner":"jjgrainger","description":"A fluent interface for creating WordPress Queries","archived":false,"fork":false,"pushed_at":"2022-07-07T10:38:47.000Z","size":65,"stargazers_count":19,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-15T06:06:16.937Z","etag":null,"topics":["query-builder","wordpress","wordpress-php-library"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jjgrainger.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-02-08T14:15:57.000Z","updated_at":"2025-01-28T18:45:02.000Z","dependencies_parsed_at":"2022-06-27T21:28:43.312Z","dependency_job_id":null,"html_url":"https://github.com/jjgrainger/Query","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jjgrainger%2FQuery","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jjgrainger%2FQuery/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jjgrainger%2FQuery/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jjgrainger%2FQuery/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jjgrainger","download_url":"https://codeload.github.com/jjgrainger/Query/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249016624,"owners_count":21198833,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["query-builder","wordpress","wordpress-php-library"],"created_at":"2024-11-28T09:34:12.012Z","updated_at":"2025-04-15T06:06:22.221Z","avatar_url":"https://github.com/jjgrainger.png","language":"PHP","readme":"# WordPress Query Builder v0.2.0\n\n\u003e A fluent interface for creating WordPress Queries\n\n[![tests](https://github.com/jjgrainger/Query/actions/workflows/tests.yml/badge.svg)](https://github.com/jjgrainger/Query/actions/workflows/tests.yml) [![codecov](https://codecov.io/gh/jjgrainger/Query/branch/master/graph/badge.svg)](https://codecov.io/gh/jjgrainger/Query) [![Total Downloads](https://poser.pugx.org/jjgrainger/query/downloads)](https://packagist.org/packages/jjgrainger/query) [![Latest Stable Version](https://poser.pugx.org/jjgrainger/query/v/stable)](https://packagist.org/packages/jjgrainger/query) [![License](https://poser.pugx.org/jjgrainger/query/license)](https://packagist.org/packages/jjgrainger/query)\n\n## Requirements\n\n* PHP \u003e= 7.2\n* [Composer](https://getcomposer.org/)\n* [WordPress](https://wordpress.org) 5.3.2\n\n## Installation\n\n```\n$ composer require jjgrainger/query\n```\n\n## Usage\n\nThe `Query` class provides a fluent interface for create `WP_Query` in WordPress.\n\n```php\nuse Query\\Query;\n\n// Create a new WP_Query for the latest 3 products.\n$results = Query::post_type( 'product' )-\u003eposts_per_page( 3 )-\u003eget();\n\n// The above is the same as...\n$args = [\n    'post_type'      =\u003e 'product',\n    'posts_per_page' =\u003e 3,\n];\n\n$results = new \\WP_Query( $args );\n```\n\n### Creating Custom Query Classes\n\nCustom query classes can be created by extending the `Query` class. Custom query classes can encapsulate default parameters which can then be expanded upon with query methods.\n\nFor example, a `FeaturedPostsQuery` can be created to return posts with the 'featured' taxonomy term. The default query parameters are defined within the `setup()` method that receives a `Builder` instance.\n\n```php\nuse Query\\Query;\nuse Query\\Builder;\n\nclass FeaturedPostsQuery extends Query\n{\n    /**\n     * Setup the initial query.\n     *\n     * @param  Builder $builder\n     *\n     * @return Builder\n     */\n    public function setup( Builder $builder ): Builder\n    {\n        // Setup a tax_query for posts with the 'featured' term.\n        $tax_query = [\n            [\n                'taxonomy' =\u003e 'featured',\n                'fields'   =\u003e 'slugs',\n                'terms'    =\u003e [ 'featured' ],\n            ],\n        ];\n\n        return $builder-\u003ewhere( 'tax_query', $tax_query );\n    }\n}\n```\nOnce the query class is created it can be used through out the project in a vairety of ways.\n\n```php\nuse FeaturedPostsQuery as Featured;\n\n// Returns a WP_Query object for posts with the featured term.\n$results = Featured::get();\n\n// Returns a WP_Query object for the latest 3 products with the featured term.\n$results = Featured::type( 'products' )-\u003elimit( 3 )-\u003eget();\n\n// Queries can be instantiated with an array of additional query arguments.\n$args = [\n    'post_type' =\u003e 'products',\n];\n\n// Create a query object.\n$query = new Featured( $args );\n\n// Modify the query and get the WP_Query object.\n$results = $query-\u003elimit( 3 )-\u003eget();\n```\n\n### Custom Scopes\n\nCustom scopes can be added to the global `Query` using the static `addScope` method. One of the simplest ways to add a scope is with a closure.\n\n```php\n// Create a new scope with a closure.\nQuery::addScope( 'events', function( Builder $builder ) {\n    return $builder-\u003ewhere( 'post_type', 'event' );\n} );\n\n// Call the scope when needed.\n$results = Query::events()-\u003elimit( 3 );\n```\n\n#### Custom Scope Classes\n\nCustom scope classes can be added to the global `Query`. The custom scope class will need to implement the `Scope` interface and contain the required `apply` method.\nThe `apply` method should accept the query `Builder` as the first argument and any optional arguments passed via the scope.\nOnce added to the `Query` class the scope will be available by the class name with the first letter lowecase.\n\n```php\n// Create a custom scope class.\nuse Query\\Scope;\nuse Query\\Builder;\n\nclass PostID implements Scope {\n    public function apply( Builder $builder, $id = null ) {\n        return $builder-\u003ewhere( 'p', $id );\n    }\n}\n\n// Add the scope to the Query.\nQuery::addScope( new PostID );\n\n// Use the scope in the Query.\n$results = Query::postID( 123 )-\u003eget();\n```\n\n## Notes\n\n* The library is still in active development and not intended for production use.\n* Licensed under the [MIT License](https://github.com/jjgrainger/Query/blob/master/LICENSE)\n* Maintained under the [Semantic Versioning Guide](https://semver.org)\n\n## Author\n\n**Joe Grainger**\n\n* [https://jjgrainger.co.uk](https://jjgrainger.co.uk)\n* [https://twitter.com/jjgrainger](https://twitter.com/jjgrainger)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjjgrainger%2Fquery","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjjgrainger%2Fquery","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjjgrainger%2Fquery/lists"}