From Habari Project

Revision as of 22:34, 25 November 2012 by Michaeltwofish (Talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search


Before You Upgrade

Before making any major change in your Habari installation, it would be prudent to create a backup of your database and your installation, in particular all the files in your Habari /user directory. The /user directory should contain all files which you have customized - plugins you have installed, themes you have installed, class files you may have modified, or locale files you have installed.

The Upgrade Process

  1. Download the new version of Habari that you will be installing. Unzipping it will create a directory named after the Habari release, for example habari-0.9, which we'll use in this description.
  2. You may wish to deactivate your active plugins. Some of the system plugins may have been changed. Some of the plugins you got in other places may not be compatible with the new version of Habari.
  3. Delete all files from your installation's '/user/cache' directory.
  4. Copy the following from your old installation to habari-0.9:
    • user directory
    • .htaccess file (depending on your settings, this file may be hidden from you)
    • config.php file
  5. Rename your old installation to make a backup.
  6. Move the habari-0.9 directory to the directory name of your old installation.
  7. Using your web browser, navigate to your site. If there are any database changes that need to be made, they will be made automatically at this time.
  8. Log into your Habari administrative area and reactivate any plugins you deactivated.
  9. Celebrate and enjoy the new features of your latest version of Habari!

Version Specific Instructions

Upgrading from Version 0.8.x to Version 0.9

Version 0.8 incorporates many bug fixes and new features. For details see the release notes.

There are several changes that you should take into account when upgrading.

Support for PHP 5.2 Removed

Before upgrading to Habari 0.9 you should ensure that you have at least PHP 5.3.3 installed. Do not upgrade Habari if you are unable to confirm your host is running at least PHP 5.3.3.

Dashboard Module Functionality Re-Implemented

In Habari 0.9, we've re-used the code that Habari uses for blocks and areas in the theme to implement the dashboard. There are two consequences to this.

First, when loading the Habari dashboard for the first time, the dashboard will no longer have the original modules that were present. Modules will need to be re-added to the dashboard manually.

Second, implementing dashboard modules is now done differently. If you have installed plugins in Habari 0.8 that provide custom dashboard blocks, these will need to be upgraded to use the new 0.9 functionality before their modules appear for use in the dashboard.

Upgrading from Version 0.7.x to Version 0.8

Version 0.8 incorporates many bug fixes and new features. For details see the release notes.

There are several changes that you should take into account when upgrading.

Theme Functions

Theme functions no longer print content by default but now return a value. This means that you need to tell your theme to echo the returned value. For example, all themes should call the header() function, which should be changed from this:

<?php $theme->header(); ?>

to this:

<?php echo $theme->header(); ?>

You should check your calls to at least header(), footer(), prev_page_link(), next_page_link(), page_selector(), and feed_alternate() in your theme.

k2 Theme Removal

The k2 theme that was previously included in Habari has been removed. If you are using k2, you can download it and put it in your themes directory, user/themes. k2 can now be found in habari-extras.

Prevent Installation Path Disclosure

A path disclosure is an error that can show the directory where your software is installed, which can be seen as a security issue. To protect existing Habari installations from a potential path disclosure issue, you can modify your config.php file and include the following line at the start of the file. New installations will be protected by default.

<?php if ( !defined( 'HABARI_PATH' ) ) { die( 'No direct access' ); } ?>

Upgrading from Version 0.7 to Version 0.7.1

Users should have no difficulty upgrading to 0.7.1 from 0.7. Users of 0.6.x should read the section below this first. For details see the release notes.

Upgrading from Version 0.6.x to Version 0.7

Version 0.7 incorporates many changes from the previous version, both in bug fixes and new features. For details see the release notes.

There are four major changes that have the potential to break your installation.

Legacy Themes

XML File Changes

Your theme files may need to be updated, but to even be activated the theme's type needs to be properly set in the theme.xml file. If that file currently looks like this:

<?xml version="1.0" encoding="UTF-8" ?>

you must change <theme> and </theme> as follows:

<?xml version="1.0" encoding="UTF-8" ?>
<pluggable type="theme">

THEME_CLASS Declaration

Additionally any THEME_CLASS declaration at the top of your theme.php should be removed to avoid conflicts.

Incompatible Plugins

You must deactivate all plugins when upgrading to version 0.7 as version 0.6 plugins are not compatible with version 0.7. The core plugins, those that come with Habari, have all been updated. Most of the plugins in the extras repository have also been updated. You can download a zip archive of plugins from the Habari webpage. You should choose the version tagged 0.7 or trunk if there is no 0.7 tag yet. If you find a plugin in the extras repository that is not updated for 0.7, ask on IRC and someone will likely fix it for you immediately.

If you get the error Cannot override final method Plugin::info(), that means you have upgraded to 0.7 while an incompatible plugin is active. To recover your site, either upgrade the plugin or find the offending plugin in your Habari installation, and move the whole directory for that plugin out of the plugins directory.

To fix your own plugins, you need to add an XML configuration file, as described on the page Creating a Plugin, and remove the function called info() from the plugin code. The file for the plugin code is called, for example, myplugin.plugin.php in the plugin's directory.

Comment Forms Must Use FormUI

To make it easier for plugins to customize comment forms, for example for spam prevention, comments must now be submitted through a FormUI comment form. This has been possible for some time, so many forms already use this method. If your theme submits comments through a normal HTML form, they won't be saved. Adding a Comment Form describes how to add and customize Habari's comment form.

Tags Schema Changes

If your theme or a plugin retrieves tags, upgrading to version 0.7 is likely to break that code. This is because internally, the Habari tags system now uses the Taxonomy system. On a technical level, Tag is now a subclass of the Term class, and Tags is a subclass of the Vocabulary class, so the tag-specific database tables, tags and tag2posts, aren't used any more. The tables will still be in your database, and will be removed in a later upgrade.

Specifically, if your theme does something like this, in 0.7 the tags retrieved will not be up to date and an error is likely to occur.

$tags = DB::get_results( 'SELECT * FROM ' . DB::table('tags') );

This code can be changed to the following to get an alphabetical listing of the tags.

$tags = Tags::vocabulary()->get_tree( 'term_display ASC' );

In addition, themes often use code similar to the following to see whether to output a post's tags or not:

<?php if( is_array( $post->tags ) ) : ?>

This will no longer work. Post tags are no longer stored as an array of text strings. They are now an ArrayObject of Tag objects. A suitable replacement for the above code is:

<?php if( count( $post->tags ) ) : ?>

For the same reason, this code will no longer work:

<?php if( in_array( 'Some tag', $post->tags ) ) : ?>

In it's place use:

<?php if( $post->tags->has( 'Some tag' ) ) : ?>

See this post to the -dev mailing list for more details.

Additionally, the way that posts are retrieved according to the tags that are attached to them has changed. Previously, you might have used something like the following:

<?php $asides = Posts::get( array( 'tag' => 'asides' ) ); ?>

Those posts should now be retrieved through the tags vocabulary.

<?php $asides = Posts::get( array( 'vocabulary' => array( 'tags:term' => 'asides' ) ) ); ?>

See the Retrieving Posts page for more details.

Upgrading from Version 0.5.2 to Version 0.6

Version 0.6 incorporates many changes from the previous version, both in bug fixes and new features. For details see the release notes.

Habari's upgrade process is designed to be transparent, with the only indication that an upgrade is happening being a slightly longer page load time the first time the site is visited after the software is updated.

One major change that affects the upgrade process in this release is in how Habari stores it's configuration details. Habari 0.5.2 and earlier stored site configuration details in global variables. Habari 0.6 marks the move to using a config class, so the variables aren't globally available, a change that was made to improve security. These details are stored in the site's config.php file, which is located either in the root of the site's directory, or, for multisite users, in Habari's /user/sites/site_name directory.

For users who have left their config.php file writable, the necessary changes to the configuration file will be handled by the upgrade process transparently. For users who have made their configuration file read only, some manual changes will have to be made before the upgrade process can begin.

Manually Updating The Configuration File

The config.php file for Habari version 0.5.2 and below looks like this:


$db_connection= array(


For SQLite

$db_connection= array(


With version 0.6 the config file looks like this:


Config::set( 'db_connection', array(


For SQLite

Config::set( 'db_connection', array(


The easiest thing to do is, before upgrading, make the configuration file writable. Perform the upgrade, then make the file read only again.

If you don't wish to do that, open the configuration file in a text editor and make the changes shown above, save your changes, then navigate to your site so the upgrade process can proceed.

Upgrading from Version 0.5 or 0.5.1 to Version 0.5.2

Version 0.5.2 is a bugfix release only. No new functionality has been incorporated into Habari. The only files that have changed are located in the /system/classes directory, so if you wish you can just delete the files from that subdirectory, then copy the updated /system/classes files to it. To be completely safe, follow the upgrade process detailed above.

Upgrading from Version 0.5 to Version 0.5.1

Version 0.5.1 is a bugfix release only. No new functionality has been incorporated into Habari. The only files that have changed are located in the /system/classes directory, so if you wish you can just delete the files from that subdirectory, then copy the updated /system/classes files to it. To be completely safe, follow the upgrade process detailed above.

Upgrading from Version 0.4.1 To Version 0.5

Many changes have been incorporated into version 0.5. For details of the changes that have been made see the release notes.

In particular, upgrade functions have been incorporated into the install handler, so when you upgrade your Habari installation, any required base database changes will be automatically handled without user intervention. However, the following are issues to note:

  • The first page load after upgrading may be slow due to the conversion of the database to use UTF-8.
  • Version 0.5 incorporates updates to Habari's form creation system that changes how the options for plugins are stored. This means that you will need to reconfigure any of your plugins that require configuration for them to work properly.
  • The location of the filecache has been moved from /system/cache to /user/cache. If your /user directory is not writable by the web server, you will need to create the /user/cache directory by hand and set it to be writable by the web server.

Upgrading From Version 0.3.3 to 0.4

Upgrading From Version 0.2 To Version 0.3

Before Upgrading

This upgrade process assumes you are somewhat familiar with accessing your database, via an admin interface like phpMyAdmin, if you are unfamiliar with this, you should contact your host and completely familiarize yourself with their database administration.

It is recommended that you rename your version of K2 if you are using that (change the name in the theme.xml file and the /user/themes directory).


It is safe to use the same database as 0.2, but if possible, the following actions should be taken:

  • Remove the `themes` table.
  • Clear the `rewrite_rules` table.


The upgrading process with MySQL is transparent as of the 0.3 release.


Please note: If you need a web manager for SQLite dabases, SQLite Manager looks like a sane solution.

  1. Move the database file to a different location.
  2. Install Habari.
  3. Overwrite the created database file with the one from step 1.
  4. Create the tables: `groups`, `groups_permissions`, `permissions` and `users_groups`. Refer to the SQL schema files for the CREATE statements.

The only difference left is the tables' structure. From 0.2 to 0.3 we modified column types, INT became SMALLINT and such. It should not affect your installation.

Personal tools