Ryan Snyder

RSS

Upgrading from Kohana 2.3.x to 2.4

At Mozilla we’re using Kohana as the PHP framework behind a number of our sites, including the UI for the Crash Reporter, the Creative Collective and Jetpack Gallery

I’ve been upgrading one of our sites from Kohana 2.3.4 to Kohana 2.4 to determine how difficult it will be to upgrade our other Kohana sites.  For a dot release, this upgrade is much more time intensive than I’d originally anticipated (anyone remember upgrading from Drupal 4.6 to 4.7?). 

I’ve recorded my upgrade notes for 1 site so that we could implement this upgrade on our other Mozilla sites using the framework.  These notes assume that you’ve downloaded the most recent version of Kohana 2.4 and that you are comfortable working from the *nix command line. As a reminder, make sure you have backups of your code so that you can revert your changes in case you run into any major problems.


1. Move the new system folder into your repository.

cd existing_kohana_dir
mv system system.2.3.4
rsync -av new_kohana_dir/system ./

2. Copy Bootstrap.php into the root of the application folder.

cp new_kohana_dir/application/Bootstrap.php application/Bootstrap.php

3. Copy over the new index.php. Update directory settings in this file if necessary.

mv index.php index.php.2.3.4
cp new_kohana_dir/index.php ./

4. Add $config[‘config_drivers’] setting to application/config/config.php

/**
 * An optional list of Config Drivers to use, they “fallback” to the one below them if they
 * dont work so the first driver is tried then so on until it hits the built in “array” driver and fails
 */
$config[‘config_drivers’] = array();

5. Add $config[‘_default’] to application/config/routes.php to define the default controller for your app.

$config[‘_default’] = ‘home’;

6. Add $config[‘connection’][‘params’] to application/config/database.php

$config[‘connection’] => array
(

‘params’ => NULL
)

7. Change html::specialchars() to html::chars() in the application and modules directories.

find . -name “*.php” -print | xargs sed -i “s/specialchars/chars/g”

8. Change Kohana::log() to Kohana_Log::add() in the application and modules directories.

find . -name “*.php” -print | xargs sed -i “s/Kohana::log/Kohana_Log::add/g”

9. Change Kohana::show_404() to Kohana_404_Exception() in the application and modules directories.

find . -name “*.php” -print | xargs sed -i “s/Kohana::show_404()/throw new Kohana_404_Exception()/g”

10. Update all Kohana::lang() references, which have been split into messages, accessed via Kohana::message(), and i18n, accessed via __().

11. Change all references from Controller::$input to Input::instance().

12. Many methods have been deprecated, including html::specialurlencode(), form::close() and form::close_fieldset(), and you’ll need to update those on a case by case basis.

Now, this was not a tremendously difficult upgrade - unless your app uses either ORM or the Database Builder.  In either case, you’ll need to review all of your database statements to ensure that they’re working properly after the upgrade.  I don’t consider this a complete list, because even after upgrading one of the sites, I’m still finding gotchas here and there.

13. Update all methods using the query builder or ORM.

  • `Database::instance()` should be changed to `db::build()`
  • `groupby` method is now `group_by`.
  • `orderby` method is now `order_by`.
  • The method limit($items_per_page, $offset) has been split into 2 methods: limit($items_per_page) and offset($items_per_page).
  • get() is no longer available.  Statements will intuitively understand that this is a select statment. Use execute() at the end of your database statement.
  • select(“DISTINCT … “) is now select_distinct().
  • Aliases are not supported within a select statement; instead use an array with the key as the alias name. Change “select(‘foo as bar’)” to “select(array(‘foo’ => ‘bar’))”.

14. ORM::where() now accepts 3 parameters, the middle of which is a comparator.  ORM::in() is no longer available, and can be replaced using ORM::where() with the comparator parameter defined as ‘in’.  For example:

->where(
  array(
    array(‘designs.id’, ‘=’,  $id),
    array(‘users.status’, ‘>=’, 1),
    array(‘badges.id’, ‘in’, array(1, 2, 3))
  )
)

Outside of Mozilla, I also maintain a few sites that use the Kohana framework, and I won’t be updating those sites because the cost of development outweighs the benefits provided by the new framework.