DAO DSL

Sometimes using array params is not enough. In those cases, UES has a dsl to build the statement in pure PHP.

Why?

The motivation for building a PHP dsl for select statements can be summed up into a single reason: meta information.

Because UES provides dynamic meta table linking (convention over configuration), filtering records based on meta information would be a nightmarish SQL statement at its best.

Recognized Words

All of the recognized words are conveniently placed at the top of classes/dao/filter.php.

Examples

Sometimes it's best just to see the DSL in action. In this example I'm going to filter records based on this information: firstnames starts with P, lastnames ends with J, the number of years in the institute is either 1, 4, 6, and they possess a clicker id.

The entry point to every standard dsl behavior is ues::where().

$filters = ues::where()
  ->firstname->starts_with('P')
  ->lastname->ends_with('J')
  ->user_year->in(1, 4, 6)
  ->user_keypadid->not_equal('')

$users = ues_user::get_all($filters);

The fields prefaces with user_ are designated meta fields. The API takes advantage of PHP magic methods __get and __call to provide pure PHP DSL through method chaining.

More Explicit

Some camps in PHP do not appreciate this form of dynamics. The DSL allows for explicit method invocation:

$filters = ues::where('firstname')->starts_with('P')
  ->plus('lastname')->ends_with('J')
  ->plus('user_year')->in(1, 4, 6)
  ->plus('user_keypadid')->not_equal('')

$users = ues_user::get_all($filters);

This pattern of filter building is more explicit, and reduces the need to invoke an __get calls and all the dsl methods are directly delegated to a build who defines these methods.

// This will throw an exception
$filters->plus('idnumber')->contains('1234');

Making your own words

Adding your own dsl is as simply as:

1. creating your own dsl field, and
2. providing a builder for your custom dsl field

class custom_field extends ues_dao_field {
    public function contains($value) {
        return $this->like($value);
    }
}

class custom_dsl extends ues_dao_filter_builder {
    public function create_filter($field) {
        return new custom_field($field);
    }
}

$filters = new custom_dsl();
// Works!
$filters->idnumber->contains('1234')