lipsworld / claws

A library for building standardized SQL clauses used in custom WordPress database queries.

Claws

Claws is a library for building standardized SQL clauses used in custom WordPress database queries.

• Version: 1.0.0-beta – this is not (yet) stable software, please don't use in production environments
• Stable: n/a

Sandhills Development, LLC © 2017

Background

In Sandhills products like AffiliateWP, Easy Digital Downloads, or Restrict Content Pro, we leverage a variety of database schema, sometimes extending core post, term, or taxonomy objects, though more often than not, custom objects.

Because of this, we've experienced an ever growing need to build (sometimes very complex) WHERE clauses in order to make information about those custom objects easily queryable.

Claws was born out that need – to create a consistent, secure system under which to generate SQL with maintenance overhead shared among the products. And also because we wanted to eventually DRY up our query code :-)

How to use Claws

Claws is specifically intended for use within applications extending WordPress in some way, whether those are plugins, themes, or something else.

And to be clear, Claws will not build your queries for you, just certain clauses. The onus is still on the developer to pass SQL generated with Claws through their database abstraction layer, it's simply meant to be used as a helper for building queries that you will ultimately run in your code independently.

At this time, Claws is minutely reliant on some core WordPress functionality, so using it as a standalone PHP library isn't possible.

Methods

Claws v1.0.0-beta currently only provides support for building WHERE clauses for MySQL queries.

At the top-level, there a few methods of note:

• where( $field ) – Sets both the "current clause" and "current field" values
• get_sql( $clause ) – Used to retrieve SQL generated by one more calls against a given clause. Default will be the "current clause"

In addition, the following comparison methods are available at the top-level:

• equals()
• doesnt_equal()
• lt() (less than)
• gt() (greater than)
• lte() (less than or equal)
• gte() (greater than or equal)
• like()
• not_like()
• in()
• not_in()
• between()
• not_between()
• exists()
• not_exists()

These methods largely cover most comparison needs in WHERE clause building. In order to allow more complex clause building global or() and and() methods are also available. See Other Ways to use Claws for more on complex clauses.

Basic Usage

Claws instances can be created either directly via the \Sandhills namespace:

$claws = new \Sandhills\Claws();

or with a helper in the global namespace:

$claws = claws();

Claws instances persist only in the current session and are not singletons. Meaning that you can instantiate a Claws object, add to it throughout the linear course of code execution, and then effectively "collect" the results of that work at the other end.

Setting of the "current clause" via something like where() can persist between calls, but we recommend reasserting the current clause on every subsequent call just in case.

Here's a basic example of that:

$claws = claws()->where( 'post_title' );

$claws->like( 'foo' )

$where = $claws->get_sql();

// WHERE `post_title` LIKE '%%foo%%'

We've found the persistence of each Claws instance is ideal for get_* type queries that may accept a variety of arguments we need to build into a fairly complex query, retrievable at the other end to be fed to via wpdb.

Method Chaining

Methods are also chainable, which allows a more logical flow of clause building.

For instance, taking the first example, the entire thing could be chained for one complete expression:

$where = claws()->where( 'post_title' )
		->like( 'foo' )
		->get_sql();

// WHERE `post_title` LIKE '%%foo%%'

Most comparison methods can also accept an array as well as an $operator value of OR or AND, though it should be made clear that all supplied values will be compared against the $field value set in where():

$title_searches = array(
	'foo', 'bar'
);

$where = claws()->where( 'post_title' )
		->like( $title_searches )
		->get_sql();

// WHERE `post_title` LIKE '%%foo%%' OR `post_title` LIKE '%%bar%%' 

Other Ways to Use Claws

Outside of each of the top-level comparison methods, there's also a shorthand method of doing '=', '!=', '<', '>', '>=', '<=' comparisons using the where() method:

$where = claws()->where( 'post_id', '=', 1, 'int' )
		->get_sql();

// WHERE `post_id` = 1

To compare multiple fields with multiple values, the "current field" value must be reset using where( $field ):

$where = claws()->where( 'post_id' )->equals( 1, 'int' )
		->where( 'post_title' )->like( 'foo' )
		->get_sql();

// WHERE `post_id` = 1 AND `post_title` LIKE '%%foo%%'

To compare multiple fields where either condition could match, a special or() method should be used between the comparisons:

$where = claws()->where( 'post_id' )->equals( 1, 'int' )
		->or()
		->where( 'post_title' )->like( 'foo' )
		->get_sql();

// WHERE `post_id` = 1 OR `post_title` LIKE '%%foo%%'