From jD2.5.x on Joomla 2.5 to jD3.2 on Joomla 3.3 or higher

This takes us from jD2.5.x on Joomla! 2.5.28 to jD3.2.x on Joomla! 3.3.x or later .  Includes notes on migration from Joomla! 2.5.x to Joomla 3.3.x.  Also included is an addendum on creating a test site on the same server.

The scene here is upgrading from jDownloads version 2.5.x running on Joomla! 2.5 to jDownloads 3.2.x (jD3.2.x) running on Joomla! 3.3.6 or higher.

Please advise if you find differences or better ways.

This article has some similarities to migrating from 1.9.1.x on Joomla!2.5.28 or higher to jD 3.2 series on Joomla! 3.3.6 or higher. The major difference is that with the jD2.5.x series we already have User Groups, User Group Settings, Permissions and View Access levels.  The scheme should preserve Category and Download ids.  Most of this article is about using a test site as once that has been done then doing it on the 'live site' should just be restoring a backup from the working version of the test site. Some notes on making a test site are given in an addendum below.

In summary the major steps are:

  1. ensure you have the latest jD 2.5.x version - at time of writing this is 2.5.26;
  2. make a 'live site' backup using say Akeeba, just in case it all goes wrong!
  3. create and restore to a test site (see addendum);
  4. prepare test site for migration from Joomla! 2.5.x to Joomla! 3.3.x (or later), 
  5. take a backup of test site;
  6. migrate from Joomla! 2.5.x to Joomla! 3.x - this is the most 'nervous' stage;
  7. take anothe backup of test site;
  8. update jD1.9.1.6 to jD1.9.2.11;
  9. take yet another backup of test site;
  10. enable or update or replace remaining Joomla! 2.5 versions;
  11. and again take a test site backup

There are several articles available on migrating from Joomla! 2.5 to Jommla! 3.x. One which gives a good overview is Practical Guide for upgrade/mini-migrate an existing Joomla 2.5 site to Joomla 3.x by Leo Lammerink, who is a 'Joomla! Master'. Another useful article is

In the more detailed section below the general scheme is supplemented with a few notes from my own experiencies.  In doing the migration I used Akeeba Backup and Restore for all backups, and File Zilla for any FTP transfers of backups.

Allow yourself plenty of time, if you need a break then do another backup. Make notes of what you are doing at each stage



  1. Backup.
  2. Make test site ( see addendum) - all of the following is assumed to be on a Test Site.
  3. Check you have jD1.9.6 or later.
  4. Using Extension Manager - Manage facility then:
    1. disable all Components other than Joomla Project and those you know run on both platforms, that is on both Joomla! 2.5 and Joomla! 3.x - in my case that was Akeeba Backup and the JCE Editor;
    2. similarly disable all  Modules and Plugins that are not Joomla! Project or you are not certain they run on both platforms, it is better to err on the side of caution so if in doubt disable;
    3. where possible update to components, modules and plugins that do work on both platforms.  Again it is better to be cautious especially when some plugins and modules run automatically on page loading! Also for any 'relacements I would suggest it is better to evaluate on the final platform than on a platform you will no longer be using.
  5. Do NOT uninstall jDownloads, but ensure component, modules and plugins are disabled.  We need to keep ids, permissions and so on.
  6. Change if possible to a front end template which is known to work on both platforms - if not change to something like Beez 2 and see if site still runs in a basic sense.  There is not a problem with the Admin template as the migration from 2.5 to 3.2 automatically switches admin to the isis template
  7. Make sure you Assign menu pages as appropriate to the new template, something easily forgotten!
  8. In Extension Manager - Database check you have no errors and if there are use the Fix button (I had two "Database schema version (2.5.14) does not match CMS version (2.5.27)." errors which meant starting again because I did not check! And yes it took quite some time to find this was a problem).
  9. Use Joomla! Update component to do the actual migration from Joomla 2.5.27 to 3.3.6 - this usually means using the Options in the Updater to select Short Term support before you see an appropriate 'target' such as indicated by a line like: "Update package URL ..."
  10. For me the Admin switched fine because it automatically switched the admin template to isis but because my site template did not support Joomla! 3.x then the site page just came up blank!  So I switched to Beez 3 to check out a couple of basics thing like seeing an article.
  11. Then Enable, but do not use, the  jDownloads 2.5.26 (or later) component; leave all other jDownloads modules and plugins Disabled.
  12. Now use the Extension Manager Install to update jDownloads to 3.2.26 or later, remember all the categories, files and database options are still in place.
  13. Make a new menu item of say List All Categories and try it out.  Do not be too ambitiuous but go to the next step.
  14. Take another Backup as things may still foul up! - Whilst it's backing up take time for a coffee or tea, or even a plain glass of water!
  15. We are now nearly there, just need to update to jD3.2.x series.  This is already covered by another article, namely Upgrade from to latest 3.2.x version so switch to that article to complete this step in the migration.
  16. Now all that is necessary is the arduous chore of updating the missing components, modules and plugins needed for your site; and also sorting out any template and menu items.

The basic scheme relies on the compatibility of the jD2.5 series and jD3.2 series databases, they have in fact an identical structure.

So first upgrade site to Joomla 2.5.28 (or higher) and jDownloads to jD2.5.25 or higher.  Then make sure you have a good tested backup.  I personally use WAMP for checking out the migration.  Joomla has an excellent set of notes on the Migration so before doing anything about jDownloads you need to make sure your site is otherwise operating AOK except for jDownloads and those other components, modules and plugins that have different releases for Joomla! 2.5 and 3.x.

The main cause of complication are the Users, Access levels and the Permissions.  jDownloads recognises these by their 'id' so if they change between Joomla! 2.5.x and Joomla! 3.3.x then confusion reigns!!.  So that is why, in principle, it is best to migrate onto your active site.  But that is difficult to get that right first time.  Hence the best way is to practice using WAMP or similar. Then overload the working site with the revised items, etc., etc.  Easy to say but can be a bit 'testing' but backups are vital!

The only jDownload parts that cannot be done automatically (at the moment) are as below.

  • Reinstating the permissions of the Component, the Categories and the Downloads.  This is not a problem as usually only the top level categories have permissions set positively, and also perhaps the Component permissions. They are usually 'set to 'allow'. Most permissions have 'inherited'  so the calculated permissions become allowed as appropriate.  If you have had to set any permissions to 'deny' then please re-examine why that is necessary.
  • Again as the process involves uninstalling jDownloads from the Joomla! 2.5 site and reinstalling on the Joomla! 3.x site then jD content items in articles may need looking at, again because of potential id changes.
  • The above will also apply to any Menu item.  Personally I unpublish the menu items relating to jDownloads in the 2.5 system and 'remake' them in the 3.x system.  I also take plenty of notes and screen dumps, and have a copy of the original working site on WAMP so I have a reference.  More work of course but less worry!

Before uninstalling jD 2.5.25 you need to do following.

  • Take a complete copy of directory <your-site>/jdownloads and its sub directories.  These are all the download files themselves.
  • Take a complete copy of directory <your-site>/images/jdownloads and its sub directories.  These are all the download picture and other files.
  • Turn off Auto-monitoring in the configuration.  This is to stop jD busily recreating the database in what is almost certainly a different order and in consequence with different ids.
  • Next use the Tools - backup, ensuring you tick the option for user groups.  This is a copy of the jDownloads database which will subsequently be re-loaded using the backup restore.
  • Disable all jDownloads Menus.  They will be disabled anyway when jDownloads is uninstalled but I just prefere to do this manually.  They will need re - enabling later when jDownloads is re-installed but sometimes this re-enabling has happened automatically, and it seems better to be in 'control'!
  • At this point we can Uninstall jDownloads. By this I also mean uninstalling the jD plugins and modules as well. I usually uninstall plugins and modules first, then the component. It will leave the database and the two sets of directories and files in place. 
  • Now upgrade site to Joomla! 3.x following the Joomla! Migration instructions.
  • As a precaution check the various 'ids'
  • Once Joomla! 3.x is up and running we can Install the latest jD3.2.x version.  Because it is a few weeks since I last did this myself I must confess I do not recall if jDowloads accepts the existing database entries or objects.  If it accepts them then most things should be OK.
  • If jDownloads objects to the existing database and/or the existing directories then rename the directories and either rename the relevant database tables or remove them.  If you are unsure about that please ask.  Should now be able to install jD 3.2.x.  Nearly there!!
  • Double check that auto monitoring is off.
  • Reinstate the directories <your-site>/jdownloads and its sub directories, and also <your-site>/images/jdownloads and its sub directories.  If you did the rename earlier then just rename back to original.
  • Check over and fixup the menu items
  • --  jDownloads should now be working OK, but check the Content items in articles etc
    If I have made any errors or you find improvements please let me know.  Also please let me kow if it worked and what you found 'challenging' so others can benefit from your experiences.

I didn't use any of these. I used the docu for upgrading JDownload 1.9 to 2.5 on Joomla 2.5.

I did exactly the same for my Joomla 3 upgrade:

In detail:

- backup the site & database
- installed latest 2.5.25 JDownloads Component
- backup of
   - your-site /administrator/language/YOUR_LANGUAGE_PREFIX/com_jdownloads.ini
   - your-site /administrator/language/YOUR_LANGUAGE_PREFIX/com_jdownloads.sys.ini
   - your-site /language/YOUR_LANGUAGE_PREFIX/com_jdownloads.ini
   - your-site /components/com_jdownloads/jdownloads_fe.css
- switch of the automatic download monitoring (Jdownloads Configuration Downloads)
- uninstall jdownloads 2.5.25 from Joomla 2.5 homepage
- deactivate all non-Joomla core plugins, modules, components at Joomla 2.5 homepage
- activate beez5 template as default if used default template does not work on Joomla 3
- switch on error logging = maximum (Global Configuration)
- make sure that post_max_size is at least 14 M in php.ini (restart php) - may you have to ask your provider or see php info at your global configuration
   - in my case it was only 8 M, this was not enough for any reason, the installer aborted without any error message (php error log rescued my project)
- install Joomla 3.3.x on your homepage using the Joomla Installer
- install new template for Joomla 3
- install JDownloads 3.2 on Joomla 3.3.x using Joomla Installer
- recreated the JDownloads User Groups and Authorizations
- reactivated all Components, Modules and Plugins one by one to see if anyone leads to an error
   - I had to re-install some modules whose version was not the latest and did not work on Joomla 3.3.x
- make sure the positions for your modules are present within the new template if required
- voyla, everythin works for me
- Rem: if your homepage changed the location, don't forget to change the default upload path (JDownloads Configuration Downloads)
- now you could also switch on Download Directory monitoring = yes


Addendum: Making a Test Site

Assumption is that Akeeba back up/restore is being used, and that the test site will be on the same server.  Make sure you have enough disk space on your server, not only for the live and test sites but also for several backups.  Assume your site is called "", that is it is located in the  public_html directory.

For the first five steps below it is probably worthwhile putting your site 'off line', see System - Global Configuration.

  1. Make backup of live site.  This is our 'get out of jail card' if things go "pear shaped" with our live site.
  2. Now turn off any SEO in System-Global Congiuration
  3. Either rename or modify the file  .htaccess so that it effectively does nothing  (I put # signs in front of various lines to make them like a commen)t.  Also disable any component, module or plugin that does SEO or Alias things.
  4. Take another Backup - Backup2.  This is the one that will be used for creating the test site.
  5. Set SEO and .htaccess back to normal live site conditions.
  6. Use your favourite FTP program to make copies of the backups onto your PC
  7. Create a directory called say 'test'. Ultimately the location of your test site will be
  8. Copy Backup2 to the test directory.
  9. Make a new Database. On CPanel this is done with MySQL Database Wizard. The new database will need a different prefix, for example jtst.  One can either use a new database user or an existing one but in either case the user needs all priveleges and you will need to know the database user name and that users password.  These have nothing whatsoever to do with any Joomla user or password, remember it is a MySQLi user and password.
  10. Copy Akeeba's 'restorer' currently called kickstart.php to directory test.  If you are using the pro version you have to rename it to something else.
  11. In you browser go to (or whatever you renamed kickstart.php).  This is all spelt out in Akeeba's documentation.
  12. During the restoration stage and almost at the last stage you get the opportunity to enter in details of the new database name, user and password; and also the new suffix. In next stage you can  set the new test sites live address (https://www.livesite/test), Cookie site ( - no http or www bits), and cookie path (/test  -with no trailing /).  Make sure you check the tick box to override the log and tmp file locations, this is easily missed.
  13. After the Clean Up stage you get button links to the Admin and Front End pages.  Try out the Admin first. if that is good then things have basically succeeded. If the front end site just comes up with a blank page or similar it probably means your template is not 'Joomla! 3.x' compatible.  Switching to the Beez 3 template for the front end usually give some sort of running front end, thus allowing basic testing whilst you sort out your front end template. You may need to Unassign menu items from another template. If the Admin does not work then you have to resore from an earlier backup and repaet  carefully.  In one case, which was late at night, I even had to delete everything in the test directory and in the new database before making a fresh start the next morning!
  14. If you are using Akeeba then do not forget to change the output directory in the Akeeba Configuration to the test site - insert /test in the directory string.

Colin Mercer, October 2014

Print Email