I have a good number of my clients running Joomla on their web sites, many of them large organization web sites with hundreds of articles and some of the most data-intensive extensions. I had been following the development progress of Joomla 1.5 for several months after its release, at which point I was still chained to the 1.0.x series for most existing sites because compatible extensions hadn't been released. Now that most of the extensions that matter are at the very least compatible in legacy mode, I've been slowly working over the summer to get my clients migrated from the 1.0.x series to 1.5. It's not the easiest process, in fact I think it's the most complicated, rage-inducing software upgrade I've ever had to deal with... However it has gotten easier as I've encountered some common issues that can be (sometimes easily) avoided.
Character Encoding
By far, the most irksome (and most common) issue with Joomla 1.5 migration is encoding. Joomla 1.0.x uses latin character encoding (iso-8859-1), while 1.5 uses the more standardized UTF-8. I'm definitely not saying it's a bad thing to convert your data to UTF-8, but I will warn that it can cause a severe headache if you go at it by trial and error. Unfortunately, in my experience (so far) it will come down to some trial and error. There are, however, several steps you can take that if performed correctly, will save you from throwing your computer out the window.
I will start by saying that so far, I have not successfully migrated data from 1.0 to 1.5 without first converting the 1.0 database to UTF-8 manually. I will go through the steps to accomplish this shortly. I just want to clarify because this seems to be the recurring theme in my migration-issues. The Joomla 1.5 installer does have the capacity to convert your migration files from iso-8859-1 (or other character set) to UTF-8 on the fly using PHP's iconv function, but every time I've attempted this I have ended up with major problems with character encoding on my new 1.5 installation (this mostly results with special characters and punctuation missing or replaced in the migrated content). I've also attempted to convert my migration files to UTF-8 manually with the iconv command in Unix, with similar issues. Sometimes it has worked better than others, but it seems there is always some sort of problem with it. Basically, if you can get your Joomla 1.0.x install working properly with UTF-8 encoding, migrating to Joomla 1.5 will be a much simpler endeavor.
Converting Joomla 1.0.x to UTF-8
For the purpose of migrating, we should only have to get the database converted to UTF-8, and ensure that when we generate a migration file from the Joomla administrator, that file will be UTF-8 as well. The following steps should accomplish this. I highly recommend first creating a copy of your production Joomla installation and database to work with.
1. Create a dump file (I'll call this "joomla-latin.sql") of your existing Joomla database using phpMyAdmin or the command-line. Remember, the command for dumping a database is:
mysqldump --opt -u username -p database_name > joomla-latin.sql
2. Create an empty MySQL database (we'll call it "joomla10-utf8"). Make sure the character set is UTF-8, and use a UTF-8 coalition such as utf8_general_ci
3. Before we can import any data, we need to take the dump file we created in step one and convert it to UTF-8 as well. For this step we'll use sed from the command-line to convert the file:
sed -r 's/latin1/utf8/g' joomla-latin.sql > joomla-utf8.sql
4. Now that we've got our UTF-8 dump file, we can finally import it into the new UTF-8 database that we created in step 2:
mysql -u username -p joomla10-utf8 < joomla-utf8.sql
5. We should now have a UTF-8 database which is identical to our production Joomla database, save for the encoding. To test it, open up your Joomla configuration.php and replace the old database name with the new database.
6. If you view your Joomla web site at this point, you should at least see that your data is there, however there may be some encoding problems because Joomla still thinks it's using iso-8859-1. To fix this, open up your language file and set the _ISO definition to "charset=utf-8".
7. You may also need to modify your includes/database.php file to complete the conversion. Open the file and go to line 102, and find the following line and uncomment it:
$this->_table_prefix = $table_prefix;
//@mysql_query("SET NAMES 'utf8'", $this->_resource); <-- Uncomment
$this->_ticker = 0;
$this->_log = array();
If you follow these steps exactly, you should be up and running with a workable UTF-8 version of your Joomla 1.0.x web site. Verify that your data is displaying correctly, and then you can create your migration file using the 1.0 migrator component and proceed to your Joomla 1.5 installation. When you load your migration file during the 1.5 installation, you will need to select UTF-8 as the encoding since your migration file has already been converted. If you fail to select the UTF-8 character set, the migration will fail with an iconv error (it will be trying to convert the file to UTF-8 when that is what it already is).
For more information regarding UTF-8 encoding and Joomla, check out David Gal's Joomla UTF-8 Guide.
Errors during migration
If you encounter errors during the migration process (while installing Joomla 1.5), you will have to reset your Joomla installation and start over from scratch. Unless I'm completely inept, it's not uncommon to encounter some errors during the migration (it's easy to miss something). A few things to consider when resetting your installation:
- Empty your Joomla 1.5 installation database, as the installer probably created some tables
- Delete the migration file that you uploaded via the installer or copied manually, located here: installation/sql/migration/migrate.sql
- If the installation completed but something went wrong, you will also have to delete or empty your configuration.php file.
One other thing is that when you complete a Joomla 1.5 installation using your 1.0 migration script, you will have to remove the installation directory before you can view the new web site to verify that your data is intact. Instead of deleting the directory, I'd recommend renaming it until you are certain you won't have to start over with your installation/migration, otherwise you will have to replace it from a fresh Joomla distribution in the event that you need to try again. In fact, it will be a good idea to keep your installation directory until you're ready to go live with your migrated Joomla 1.5 web site. One time I got to the point of updating my 1.0 template to be 1.5 compatible and realized the data wasn't quite right, and had to re-install with a fixed migration script. Luckily all I had to do was rename the directory back to "installation", and follow the steps I mentioned above before re-installing and then going back to work on my template updates.
These are a few of the major issues that I (and many others) have encountered while attempting to migrate Joomla 1.0 to 1.5. Luckily, the headache is definitely worth it, Joomla 1.5 has solved a lot of major complaints I had with 1.0, and is a much more mature platform all around. I've developed several 1.5 native extensions so far and am much happier with the framework than I was with 1.0.x. There is definitely more I could write on the subject of migration, I may add to this article as I have the time and as I encounter any new problems since I am still in the process of migrating a few sites myself.
