Migrating from Agile Toolkit 4.1.3 to 4.2 master branch. Notes.

by Janis Volbergs, June 11th,2012

It has been a while since Agile Toolkit 4.2 version was introduced. I was involved in testing it and creating some compatibility patches. It feels that now 4.2 is stable enough to move older products to this newer, much more enhanced version of agile toolkit. This time, I will take notes, while migrating to ease up migration for other developers.

Updating Agile Toolkit libraries

All right. Let’s start with getting atk4 and addons updated. To do so, it’s really simple:

1. cd atk4
2. git checkout master
3. git pull

and

1. cd atk4-addons
2. git checkout master
3. git pull

Fixing authorization

Now, we have the latest 4.2 version installed. Let us proceed with compatibility fixes. First thing I noticed is following:

Fatal error: Call to a member function loaded() on a non-object in /var/www/gtd42.bdsa.biz/htdocs/atk4/lib/Auth/Basic.php on line 242

In 4.2 we have radically redesigned authorization class, which supports fancy add-ons. So my old code was like:

$this->auth = $auth=$this->add('SQLAuth');
$this->auth->setSource("user", "username", "password");
$this->auth->usePasswordEncryption("sha256/salt");

Now, there is more simplified model based implementation:

$this->auth = $auth=$this->add('Auth_Basic');
$this->auth->setModel("user", “username”); //second param indicates login field
$this->auth->usePasswordEncryption("sha256/salt");

4.2 comes with new Model implementation

With this sorted, I get next error:

Fatal error: Access level to Model_MVCTable::$id must be public (as in class Model) in /var/www/gtd42.bdsa.biz/htdocs/atk4-addons/mvc/Model/MVCTable.php on line 9

This is because I had my own Model_Table model implementation that extends Model_MVCTable. The latter is 4.1 implementation of models, and we definitely want to use 4.2 Model instead. However, Model_Table is no more user re-definable, thus, whatever extra features we have in the custom implementation, we can move those away to Controllers and use following technique:

So, here is the original Model

We remove this custom model class, and create a controller class Controller/ModelEnhancer.php

and final step is adding controller in models, that require the enhancment. Pay attention, that we are also now using 4.2 feature where Model class implements ArrayAccess. 

Now, we check all lib, pages which previously used getValues() method, and update models to add our new controller.

Okay, after this fix, first success - login form is now visible and I can login.

Now let’s check how rest of the things work. Menu is no more working, as name and path are swapped. So, let’s fix that quickly:

Adding menu items - slight change

addMenuItem('Project Management', 'pm')

to

addMenuItem('pm', 'Project Management')

Adjusting Models to enable the power of the new implemetation

Next, in 4.2 if you have datatype(“boolean”), you have to explicitly add enum(array(‘Y’,’N’)) to make it compatible with the same db.

Next, comes model adjustments.

1. refModel is gone, thus change:

$this->addField(“foo_id”)->refModel(“Foo”);

to

$this->hasOne(“Foo”, “foo_id”);

2. boolean fields need to be adjusted

...->datatype(“boolean”)

to

...->datatype(“boolean”)->enum(array(“Y”,”N”))

Note, you can void enum, if in db you store 1/0 opposed to Y/N

3. calculated fields are different

to

$this->addExpression(“x”, “concat(‘id#’, id)”);

4. filestore integration

$this->addField(“filestore_file_id”)->display(“file”)->refModel(“Filestore_File”)

to

$this->add(“filestore/Field_File”, “filestore_file_id”);

Outro

This covers brief outlook of changes that you will have to implement to move to latest Agile Toolkit version As you can see, most are rather trivial and will not take much time. Unless you have many models. I did not touch upon new form styling - yep, setFormClass(“vertical”) is gone and instead you should use setFormClass(“stacked”). There are changes in templates, new fields and UI elements. If you had many custom form layouts, those will require some update as well.

Surely, there are other minor issues that you might runinto. There is new implementation of Export addon, OAuth, Social Integration addons - they are more powerful and flexible. Some of the old addons are not ported to 4.2 just yet, so if you relay heavily on addons, there might be some extra work to be done.

Is it worth updating to 4.2 after all? Short answer - definitely. MVC has become integral part of Agile Toolkit and not only it has been written from scratch, but also many new great php features have been applied to even further enhance the development experience.

That then summarizes my notes on 4.2 agile toolkit migration. Good luck with Agile Toolkit and see you around!