How Agile Toolkit keeps PHP Simple?

The PHP language packs an insane amount of features. When all of them are mashed together, your code starts to look complex, creepy and very Java-like. Agile Toolkit specifically tries to avoid some of the features, and tones down some other features.

PHP5 Features Agile Toolkit avoids using

Below are the list of features and concepts which Agile Toolkit avoids, as well as the reasoning behind the decision:

Command-line code generation

There is no magic command-line utility to generate a bunch of code on your behalf. Generation of repeated code is a violation of the DRY (Don't Repeat Yourself) principle. It also often adds stuff to your project that you are not aware of, but which you will need to continue to maintain.

Agile Toolkit provides many ways to simplify your project structure and reduce the amount of code you will need to write, therefore code generation is not needed.

Singletons

Singletons are evil. Especially in PHP. They give no benefits, not even memory saving. They might have some use in Java (or multi-threaded environments), but are generally considered a bad design in PHP language.

Agile Toolkit never relies on singletons. Each object must be dynamically generated before it's used. For developers well familiar with Object Oriented development this offers a much more powerful architecture and most importantly it helps avoid direct dependencies between classes

Protected and Private properties

Access restriction is a way to tell users "keep away from the core". Unfortunately PHP does not implement any support which would allow specific classes (friendly as in C++ or package as in Java) access to those properties.

Agile Toolkit keeps properties and functions public. Even though you might not need to call them, some Controller may use them directly to enhance functionality of an object in a certain context.

Setters and Getters

There is a school of thought that all properties should be declared as 'private', and should only be accessible through accessor functions such as getMyProperty / setMyProperty. This principle seems to work fine in the C language, which can optimize the use of those functions to the same level as accessing the properties directly. In PHP, using this approach slows down both the development and execution slightly.

In Agile Toolkit you will often see the use of $obj->set() and $obj->get() methods, which functionally vary depending on the object type. Usually those methods deal with complex logic, such as setting tag values in templates. Other properties can be accessed directly, such as $view->template or $view->model. Do not be afraid to access properties directly if they are declared as public.

Models definitions rely on setters/getters primarily to make it easier to chain calls.

Long variable or class names

Typing long variable names takes time. Methods, classes and properties in Agile Toolkit use compact names to produce as little code as possible. However all methods must be meaningful.

In Agile Toolkit you will find that certain objects use set() differently. $button->set() changes label on the button and $model->set() changes field value. PHP is a dynamic language and does not require overridden functions to have the same set of arguments, therefore Agile Toolkit takes advantage of that fact.

Namespaces

Agile Toolkit uses namespaces for add-ons. It is to avoid class name collisions between different add-ons and base classes. Read add-on development guide for more information. Namespaces are not used within Core or your code.

Features to be careful about

IDEs and code type hinting

Some of the constructions in Agile Toolkit make it impossible for type hinting to work correctly in IDEs. This is because IDE's are having difficulties with type-less code parsing. The following code is picked up by IDE:

$form = new Form();

But when add() is called, IDEs are getting confused. You can use the following syntax to force type hinting:

/* @var $form Form */
$form=$page->add('Form');
/* completion works now on $form */

However if you know a way to improve the hinting in IDE with the add('class') pattern of Agile Toolkit, tell us how to do it.

Interfaces

An Interface is a design feature in PHP, by which you can set the requirements for class implementation. While it might have some use when designing software architecture, it has little use in Agile Toolkit.

That said, in a normal model design you will find it very useful to use type hinting

// class "User"
function purchaseTicket(Model_Bus_Route $route){
  
//..
}

In general, software you develop with Agile Toolkit would not be sufficiently complex to have a big necessity for interfaces.

Traits

PHP 5.4 introduced "traits". It's a very powerful feature of PHP, but Agile Toolkit already has "Controllers" which perform a very similar job.

Validation

Agile Toolkit implements certain model hooks such as beforeSave or beforeDelete. You may add tiny methods there which perform a validation check and throw errors.

$model->addHook('beforeSave',function($m){
    if(
$m['age']<18)throw $m->exception('Must be 18+')->addMoreInfo('age',$m['age']);
});

Localization

Agile Toolkit channels it's system messages through $api->_() method. By default this method is not doing anything, but you can extend it to call "gettext" or look up translation in any other way. Controllers can also add localization through a hook which is placed in this function.