PHPackages websteam/wp-query-builder - 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. websteam/wp-query-builder ActiveLibrary[Database & ORM](/categories/database) websteam/wp-query-builder ========================= A fork of an expressive query builder for WordPress based on Laravel's Query Builder 03PHP Since Feb 22Pushed 3y agoCompare [ Source](https://github.com/websteam/WP-Query-Builder)[ Packagist](https://packagist.org/packages/websteam/wp-query-builder)[ RSS](/packages/websteam-wp-query-builder/feed)WikiDiscussions master Synced 1mo ago READMEChangelogDependenciesVersions (1)Used By (0) WP Query builder ================ [](#wp-query-builder) An expressive query builder for WordPress based on Laravel's Query Builder. Wraps the `$wpdb` global. [![Build Status](https://camo.githubusercontent.com/31f800cfc449731d5e311bd5a208e73d308b58b15ae14ebd6540ac263d207e4a/68747470733a2f2f7472617669732d63692e6f72672f7374657068656e6861727269732f57502d51756572792d4275696c6465722e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/stephenharris/WP-Query-Builder) How to use in managed environments ---------------------------------- [](#how-to-use-in-managed-environments) If you wish to use this extension in a managed environment, simply install using `composer`: ``` composer require stephenharris/wp-query-builder ``` To use the Query builder ``` include('vendor/autoload.php'); global $wpdb; $qb = new WPQueryBuilder\Query($wpdb); ``` How to use in distributed plug-ins ---------------------------------- [](#how-to-use-in-distributed-plug-ins) Since there is no way to manage dependencies between plug-ins, bundling this library inside a plug-in will likely cause errors (possibly fatal errors) if used with another plug-in that also includes it. The safe way to bundle this library inside your plug-in is to use [Mozart](https://github.com/coenjacobs/mozart). This copies it the codebase, but wraps it inside a custom namespace. You'll need to handle autoloading of the library classes. They can be autoloaded according to PSR-4 from your Mozart destination directory. ``` global $wpdb; $qb = new YourPluginNameSpace\WPQueryBuilder\Query($wpdb); ``` Data Sanitisation ----------------- [](#data-sanitisation) The purpose of this library is to provide an **expressive** and **safe**\* way to run queries against your WordPress database (typically involving custom tables). To this end all **values** provided are escaped, but note that **column and table**names are not yet escaped. In any case, even if they were you should be whitelisting any allowed columns/tables: otherwise using user-input, or other untrusted data to determine the column/table could allow an attacker to retrieve data they shouldn't or generate a map of your database. Querying Results ---------------- [](#querying-results) ### Retrieving all rows from a table [](#retrieving-all-rows-from-a-table) ``` $qb->select()->from("wp_users")->get(); //SELECT * FROM wp_users; ``` ### Retrieve a single row [](#retrieve-a-single-row) ``` $qb->select()->from("wp_users")->where("user_email", "=", "admin@example.com")->first(); //SELECT * FROM wp_users WHERE user_email = 'admin@example.com' LIMIT 1; ``` ### Retrieve a single column [](#retrieve-a-single-column) To retrieve the first column in the returned results: ``` $usernames = $qb->select(["user_login", "user_email"])->from("wp_users")->getColumn(); ``` To retrieve a particular column ``` $emails = $qb->select(["user_login", "user_email"])->from("wp_users")->getColumn("user_email"); ``` ### To retrieve a value [](#to-retrieve-a-value) ``` $email = $qb->select("user_email")->from("wp_users")->where("ID", "=", 123)->getScalar(); ``` ### Basic Where clauses [](#basic-where-clauses) Adds a `WHERE` clause, matching records where the column value equals/not equals/ greater than/ less than / greater than or equals / less than equals (`=`/`, !=`, `>`, `=`, `select() ->from("wp_posts") ->where("post_status", "=", "publish") ->andWhere("post_date", ">=", "2018-05-31 10:00:00") ->get(); //SELECT * FROM wp_posts WHERE post_status='publish' AND post_date >= "2018-05-31 10:00:00"; ``` To add an `OR` condition, use `orWhere($column, $operator, $value)`. ### Where column value IN [](#where-column-value-in) Adds a `WHERE` clause, matching records which have a column value in the array provided: ``` $qb->select()->from("wp_users")->whereIn("ID", [1, 2, 3])->get(); //SELECT * FROM wp_users WHERE ID IN (1, 2, 3); ``` ### Where column value IN [](#where-column-value-in-1) Adds a `WHERE` clause, matching records which have a column value in the array provided: ``` $qb->select()->from("wp_users")->whereIn("ID", [1, 2, 3])->get(); //SELECT * FROM wp_users WHERE ID IN (1, 2, 3); ``` ### Where column value BETWEEN [](#where-column-value-between) Adds a `WHERE` clause, matching records which have a column value between two specified values: ``` $qb->select()->from("wp_posts")->whereBetween("post_date", '2018-05-01 00:00:00', '2018-05-31 23:59:59')->get(); //SELECT * FROM wp_posts BETWEEN '2018-05-01 00:00:00' AND '2018-05-31 23:59:59'; ``` ### Search for a field [](#search-for-a-field) Performs a `LIKE` comparison on one ore more fields fields. ``` $qb->select()->from("wp_posts")->search("post_title", "foo")->get(); //SELECT * FROM wp_posts WHERE post_title='%foo%'; ``` To search in multiple columns you can pass an array of columns: ``` $qb->select()->from("wp_posts")->search(["post_title", "post_content", "post_excerpt"], "foo")->get(); //SELECT * FROM wp_posts WHERE post_title='%foo%' OR post_content='%foo%' OR post_excerpt='%foo%'; ``` ### Complex Where clauses [](#complex-where-clauses) The `andWhere` (and its alias `where`), and `orWhere` all also accept a `WhereCause` instances. This allows you to build more complex queries, such as nested `WHERE` conditions. ``` $privateAndAuthor = new WPQueryBuilder\CompositeWhereClause(); $privateAndAuthor->andWhere(new WPQueryBuilder\BasicWhereClause('post_status', '==', 'private')) $privateAndAuthor->andWhere(new WPQueryBuilder\BasicWhereClause('post_author', '==', 1)); $qb->select() ->from("wp_posts") ->where($privateAndAuthor) ->orWhere("post_status", '=', "publish") ->get(); //SELECT * FROM wp_posts WHERE (post_status = 'private' AND post_author = 1) OR post_status = 'publish'; ``` Joining ------- [](#joining) There are four methods for joining: ``` $query->select(['wp_posts.*', 'u.user_nicename']) ->('wp_posts') ->leftJoin('wp_users as u', 'wp_posts.post_author', '=', 'u.ID'); // SELECT wp_posts.*, u.user_nicename FROM wp_posts LEFT JOIN wp_users as u ON wp_posts.post_author = u.ID; ``` Methods - `leftJoin($table, $firstColumn, $operator, $secondColumn)` - `rightJoin($table, $firstColumn, $operator, $secondColumn)` - `innerJoin($table, $firstColumn, $operator, $secondColumn)` - `fullJoin($table, $firstColumn, $operator, $secondColumn)` Insert records -------------- [](#insert-records) The `Query::insert` method will insert a record with the given column / values (given an array, where the column is the key). You must call `Query::table` with the name of the table specified. ``` $qb->table("wp_posts") ->insert( "post_title" => "My Post Title", "post_content" => "My post content...", "post_status" => "publish", ); // INSERT INTO wp_posts (post_title, post_content, post_status) VALUES ('My Post Title', 'My post content...', 'publish'); ``` Delete records -------------- [](#delete-records) The `Query::delete` method will execute a delete command for the table specified, via the `Query::table` or `Query::from` command. The `delete` method must be called **after** any where conditions, as otherwise you will delete the entire table. ``` $qb->table("wp_posts") ->where("ID", "=", 123) ->delete(); // DELETE FROM wp_posts WHERE ID='123'; ``` Error handling -------------- [](#error-handling) Calling a method incorrectly (e.g. calling `Query::get` without first calling `Query::table`, or passing a field to `getColumn` that was not included in the query Results) will results in a `LogicException` (either `BadMethodCallException`or `InvalidArgumentException`). If the SQL query fails then a `WPQueryBuilder\QueryException` is thrown. ``` try { $qb->set([ 'ID' => 5, 'post_title' => 'Updating a post' ]) ->where('ID', '=', 3) ->update(); } catch (\LogicException $e) { // There is an error in your code } catch (\WPQueryBuilder\QueryException $e) { // This could be data conflict } ``` ### Health Score 14 — LowBetter than 2% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity3 Limited adoption so far Community8 Small or concentrated contributor base Maturity23 Early-stage or recently created project Bus Factor1 Top contributor holds 85.7% 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. ### Community Maintainers ![](https://www.gravatar.com/avatar/e76d105a1b4326dcdf57f77745c6cc3506906d4937b683eff4e3022913ccaa15?d=identicon)[websteam](/maintainers/websteam) --- Top Contributors [![stephenharris](https://avatars.githubusercontent.com/u/3255034?v=4)](https://github.com/stephenharris "stephenharris (12 commits)")[![websteam](https://avatars.githubusercontent.com/u/19708840?v=4)](https://github.com/websteam "websteam (2 commits)") ### Embed Badge ![Health badge](/badges/websteam-wp-query-builder/health.svg) ``` [![Health](https://phpackages.com/badges/websteam-wp-query-builder/health.svg)](https://phpackages.com/packages/websteam-wp-query-builder) ``` ### 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)