Development Changes - 4.2 branch

Version 4.2 release is aimed at making Agile Toolkit cleaner, more documented, more flexible and scalable. Your web software developed with 4.1 can be easily adopted to use with 4.2. This version is highly recommended for new software. You should upgrade to 4.2 if your software is still in it's development phase. For software already deployed with 4.1 we have released the 4.1.4 version.

Compatibility Mode

To get into 4.2 quickly with minimum amount of changes, we've created a "Compatibility" layer. To activate it, you need to add the following line to your Application's init() code (preferably right after parent::init())


With this you will be able to switch between 4.1 and 4.2 easily.


Most of the functionality in 4.2 is syntactically compatible with 4.1, although some things will require changes. The 4.1.4 will attempt to provide a common syntax which will help switching between version easier.

If you are upgrading, read this document carefully. Features labeled "IMPORTANT" require change of your code.

Database access

DSQL, Models, and Database access classes have been fully rewritten. DSQL is now PDO-compatible and will work with non-MySQL databases. It has been tested with Sqlite and PostreSQL. The new implementation is compatible, but also more powerful, cleaner and flexible. New features:

  • Support for sub-selects
  • Proper suppor for "or"
  • Support for expressions
  • Vendor-specific syntax changes (such as $dsql->limit($a,$b))
  • Custom arguments and templates
  • Full iterator support

foreach($this->api->db->dsql()->table('user') as $row){
"User ".$row['name']." found\n";
See Full documentation of DB and DSQL, DB class reference, DSQL class reference.


The implementation of models in 4.1 have been considered an add-on due to poor quality of the code. In 4.2 model code has been completely rewritten and the new version is much more powerful and much better integrated. Models have also been divided into two classes: Relational models and non-relational. You can extend non-relational models to use with no-SQL databases by adding Data Controllers. (note: MemCached data controller is not included with Agile Toolkit)

$book $this->add('Model_Book')

Non-relational models represent most of the no-sql storage options. They maintain the "ID"=> "hash of fields" relationship, can load, store, delete and add records through appropriate controller. They have nothing to do with SQL. Model represent a classic implementation of active record. Model class implements the following features:

  • Separation of Model logic and Controller logic
  • Array-like access ($model['name']='John')
  • Full iterator support
  • Lightweight and fast implementation
  • Compatible with all View classes
  • Support for "id" and "table"
  • Much better support for custom fields

The model field definition object have been rewritten also. It can now participate in query building and even add hooks into the model, so it's much easier now to add custom field types.

See Full documentation of Model, Model class reference.

Relational Models

Model_Table class is more powerful than ever. It takes advantage of new field definition classes to implement relations and references. Relation are "joins" between multiple tables and references are "links" between models. This concept is separated very specifically in 4.2. The model implementation in 4.2 is also much more consistent in it's mechanics too.

class Model_Book extends Model_Table {

$details $this->join('book_details');

While in the above definition Agile Toolkit makes even more assumptions (such as book.author_id exists and needs to be defined as sub-select and show, also that chapter.book_id is set and book.book_details_id exists and points to It also assumes that boolean is represented with 0=false 1=true) ALL of those assumptions can be corrected.

class Model_Book extends Model_Table {

$details $this->join('book_details.isbn','isbn');
$details -> addField('details')->rename('book_details');

The later declaration solves many problems users of Agile Toolkit 4.1 had in the past. It defines a different ID field for the table and also defines a title field, which is used by other model with "hasOne" reference. Boolean value uses compatible Y/N format and when joining "book_details" table book_details.isbn=book.isbn is used (although 2nd argument could have been ommited). Below is the list of all other features:

  • Improved model loading and saving consistency
  • Allows joining model with additional tables
  • Join return "relation" object which can be joined again or import fields from joined table
  • Joins extend inserting and deleting data by populating joined tables too
  • Model implements "countable". echo count($this->add('Model_Book')
  • Model creates shortcut for sum: echo $this->add('Model_Book')->sum('price')

See Full documentation of Relational Model, Model_Table class reference.

Core Changes

  • IMPORTANT: All hook functions will now receive first argument a reference to a calling object. (before: myHook($foo,$bar), now: myHook($caller,$foo,$bar) )
  • adding certain objects (such as models and controllers) will not have reference stored through elements array (for better garbage collecting)
  • added support for add('namespace/my_object'); for including classes from add-ons
  • introduced $object->rename()
  • new exception mechanics fully adopted. throw $this->exception()
  • recursive downCall removed. Forms now rely on hooks, which is faster anyway
  • SMlite's set() will now use htmlspecialchars. Much better protection against JS injection. setHTML method added.
  • setModel and setController refactored.

See Full documentation of Core Objects, AbstractObject class reference.

API Changes

  • api->getDestinationURL renamed to $api->url(). Previous functions is obsolete, but will work until 4.3
  • Magic Quotes are oficially cleaned up if they are enabled in PHP
  • Error reports are much more precise
  • If model raised error, it's possible to activate debug from UI exception/action

See Full documentation of Application Classes, API class reference.

View changes

  • HtmlElement merged into View.
  • Lister, CompleteLister fully refactored. Can now use setSource(any iterator)
  • Form can now import fileds from multiple models.
  • MVCForm and MVCGrid are obsolete. Regular form will make use of respective controller if you call $form->setModel()
  • Menu is now based on CompleteLister and is therefore simpler
  • Grid split into Basic and Advanced and Advanced will gradually be further split into objects.
  • Columns can now accept argument of 1..12, percents or it can be omited altogether
  • Order of addMenuItem arguments changed. It's now similar to addField() - first is page name, next label
  • Order of addTabURL arguments changed. It's now similar to addField() - first is page name, next label
  • View_Error and View_Info have a nice box now
  • univ()->errorMessage() can be used to show red notifications

See Full documentation of View Class, API class reference.

CSS Changes

  • All of Agile Toolkit CSS now is written with LESS
  • CSS styles completely redesigned. Now uses 12-column grid system by default
  • display: block is actively used


  • Filestore moved into namespaced add-on
  • Filestore new field type for image and file
  • Item re-orderer moved into namespaced add-on

Older Entries

Development History

All changes to the development version of Agile Toolkit are listed below.

Agile Toolkit Core
  • Release 4.2 NEW!
  • Release 4.1.2
  • August 2011
  • July 2011
  • June 2011
  • May 2011
  • April 2011
  • Mart 2011
  • February 2011

    • To stay up to date, by following @atk4 on twitter. Use Git / master branch for most recent version.