Filters

This builds on top of the Entities and the Entity Repository so make sure you are familiar with these.

Filter class

You can write your own filter_by_... methods within a specific repository. But those filters are still bound to this entity and cannot easily be used by other entities.

To provide better reusability entity repositories can use filter objects. A filter object extends the base filter class and needs to implement the apply() method. The filter automatically receives a builder instance and can add conditions on it.

class path extends \core\orm\entity\filter\filter {

	public function apply() {
    	if ($this->value > 0) {
            $value = $this->value;
     		// get all children of given id
        	$this->builder->where_like('path', "/{$value}/");
    	}
   }
}

The filter can receive params on initialisation, they can be passed either via the constructor or the set_param() method. How the params are used is totally up to the filter. It could be one or more column names, additional params, etc.

public function apply() {
    // params are store in a property
    $column = $this->params[0];
    $case_sensitive = $this->params[1] ?? false;
    
    // ...
}

// on usage
$filer = new my_filter('column', true);

Default filters

If you want to make the filter always available for an entity define it as a default filter.

class competency_repository extends \core\orm\entity\repository {

     /**
 	   * Define available default filters
 	   *
	   * @return array
 	   */
	protected function get_default_filters(): array {
    	return [
            'path' => new path(),
        ];
    }

}

Then you can just pass a key value pair when you want to filter by it. For example to pass through filters from the UI to the actual entity.

$competencies = competency::repository()
    ->set_filters(['path' => 23])
    ->get();

// OR

$competencies = competency::repository()
    ->set_filter('path', 23)
    ->get();

On-demand filters

You don't have to define a filter in the default filters method to apply it. You can always pass in the filter object into the set_filter() or set_filters() method:

$path = new path();
$path->set_value(23);

$competencies = competency::repository()
    ->set_filter($path)
    ->get();

// OR

$filters = [
	$path,
	// ...
	// other filters
];

$competencies = competency::repository()
    ->set_filters($filters)
    ->get();

Generic filters

We provide a few generic filters which you can use directly or extend:

// results in: firstname = 'Max'
$equal = new equal('firstname');
$equal->set_value('Max'); 

// you can filter over multiple columns (automatically uses OR between it)

// results in: firstname = 'Max' OR middlename = 'Max'
$like = new equal(['firstname', 'middlename']);
$equal->set_value('Max'); 

// results in: firstname LIKE '%Max%'
$like = new like('firstname');
$like->set_value('Max');

// by default uses a placeholder wrapped with percentage signs, resulting in '%value%'
// placeholder can be changed with second param

// results in: firstname LIKE 'Max%'
$like = new like('firstname', '[text]%');
$like->set_value('Max');

// you can filter over multiple columns (automatically uses OR between it)

// results in: firstname LIKE '%Max%' OR middlename LIKE '%Max%'
$like = new like(['firstname', 'middlename']);
$like->set_value('Max');

// results in: firstname IN ('John', 'Max', 'Bob')
$in = new in('column');
$in->set_value(['John', 'Max', 'Bob']);