LookUps are a fun way to wrap Models for easy querying and consistent fields returned. You must at the minimum define protected $fields, protected $Model and protected $searchableFields to implement a LookUp.

LookUps should only be used in very rare circumstance and only in very select projects, you should mainly opt to using pure Models or Records to keep extraneous data from being fetched from the database. We have only included it in the framework for these rare cases.

Lets dive into an example:

namespace App\lookup;

class User extends \Disco\classes\LookUp {

    protected $Model = 'App\model\User';

    protected $fields = Array(
        'id' => 'u.id',
        'age' => 'u.age',
        'username' => 'u.username',
        'todoId' => 't.id',
        'todo' => 't.todo'
    );

    protected $searchableFields = Array(
        'username',
        'todo',
    );


    public function preFetch(){
        $this->Model->alias('u')
            ->ljoin('App\model\ToDo AS t', 't.user_id=u.id');
    }

}

In the above User LookUp we defined the Model being used by the lookup, the fields we want returned from the lookup, the fields that should be search-able, and the join necessary to tie the user and their to dos together.

Lookups work by converting the defined fields into methods of the lookup which can then be used to build the query for what to lookup. Once the conditions have been specified you call the fetch() method to execute the lookup and get the results.

The searchableFields are what is used when the method search() is called and a LIKE condition is used with the data passed to the the search() method to perform a LIKE comparison on the fields in the database.

The preFetch() method allows you to manipulate the LookUp prior to executing the query, and the postFetch() method allows you to manipulate the LookUp after its conditions have been set on the Model. If you use the postFetch() method you are responsible for executing the query and returning the data as you see fit, by default the postFetch() method will just return the results of the lookup as an array.

Lets look at how we can use this lookup:

$UserLookUp = new \App\lookup\User;

// This will return the results from the user model where the id=22 and the username='bobby'
$bobby = $UserLookUp->id(22)->username('bobby')->fetch();

// Lets get all the users who are over the age of 40
$oldUsers = $UserLookUp->age('> 40')->fetch();

// Lets get all the users who are under the age of 20 and have a to do that talks about pokemon
$users = $UserLookUp->age('< 20')->search('pokemon')->fetch();

You can use the comparators >, >=, <, <=, !, LIKE to manipulate conditions as seen above.

You can also use the methods limit(), order(), and page() to manipulate what is returned:

$UserLookUp = new \App\lookup\User;

$byAgePage2 = $UserLookUp->age('>= 30')->username('! bobby')->order('age DESC')->limit(5)->page(2)->fetch();

See the full API docs (linked at the top of the page) for more on LookUps. It's worth saying again, LookUps should only be used in VERY rare circumstances.