Chaining method calls
There are no procedures in PHP, only functions. Functions can return something. When return of object method is not obvious, Agile Toolkit methods return reference of the same object - '$this'. These methods are called "chainable", because you can use return of one method to call other method.
This approach is used to improve code readability. You don't need temporary variables. Below is the example of method chaining:
$users = $this->api->db->dsql()
In the code above, the first function being called belongs to the "DBlite" object, which can be accessed through $this->api->db. This function returns a new instance of a DSQL object.
Calling "table", "where" and "order" on a DSQL object returns reference to the same object. It's the equivalent of the following code:
$dsql = $users = $this->api->db->dsql();
$users = $dsql->get();
How can I know what the method will return?
Most of the methods in Agile Toolkit return an instance of the same object for chaining. There are exceptions, which are easy to spot:
Those will most likely create or return a new object.
// all objects have an add() method, returning an instance of a specified class
$form = $page->add('Form');
// Form has addField(), returning a Form_Field_<type>
$field = $form->addField('type','name');
// Models also have addField, but return a FieldDefinition
$field_definition = $model -> addField('surname');
// Grid's addColumn currently returns a Grid, but potentially can return other object
$do_not_chain = $gird->addColumn('type','name');
$users = $dsql->do_getAllHash();
$this->api->db->dsql() will return a new instance of a DBlite_dsql() object. All views have a js() method, which returns a new instance of a jQuery_Chain class.
$chain = $form->js(true);
get* methods return a contextual value
Methods starting with "get" often return some value relevant to the context in which they are used. You should look into the documentation of those methods to find out what they return.
$child = $object->getElement('abc');
$value = $model->get('name');
$url_object = $api->url('user/account'); // used to be getDestinatiounURL