Jump to Main Content
XOOPS 2.3.x Overview, Installation, and Upgrade (from 2.0.x)

Author Me Date 2009/5/16

These are my notes on XOOPS 2.3.x, especially focusing on the upgrade from XOOPS 2.0.x and other related aspects of maintaining a XOOPS 2.3.x website.

This documentation focus on the 2.3.x release (updated for 2.3.3 so far), mainly from an upgrade standpoint. I have numerous sites using XOOPS with several more in the works, so I try to keep them all generally synchronized or it'd be a real nightmare keeping up with them as separate solutions.


There is solid documentation on performing a clean installation; however, most XOOPS users want to use the latest version with the latest capabilities, so that means upgrading what you currently have installed, and chances are, you've got a number of modules in place and a number of modifications to language files and the likes. The upgrade documentation published with the 2.3.x release confused me a little bit -- at first, but I figured it out after working on it for awhile. The only lacking feature to the upgrade release documentation is that it assumes you don't have any modifications to your installation (core and/or modules). This document is designed to be a high-level guide for those with "mature" installations (call them institutionalized, or whatever you want) and want to apply 2.3.x to your existing 2.0.x installations per.

Major Changes

This list focuses on upgrade issues; others major changes are outlined in the Release Notes.

  • Profile Module included (i used SmartProfiles previously, and had to migrate over) - usage "detected" by core
  • Private Messenging (PM) now modularized - usage "detected" by core
  • Frameworks embraced and restructured
  • WYSIWYG Editors (aka XOOPSeditors) now part of release package (includes FCKeditor 2.6.3)
  • Captcha (what about Re-Captcha for people with sight disability)
  • Protector Module (by GIJoe) "ready-to-install" (may not be latest, though, so check)
  • Themes
    • Language support (main.php in theme/language/<langname>) - See structure in Zetagenesis
    • ThAdmin "ready-to-install" allowing theming of the Admin Menu/Control Panel
  • AltSys Module - file update included in extras for install
  • Directory Restructuring
    • XOOPS_TRUSTED_ROOT methodology embraced (new Library/Data area)
    • Cache Directories (cache/templates_c) moved to XOOPS_TRUSTED_ROOT

New Stuff

  • XOOPS Library
  • XOOPS Data Storage
  • Core Functional Changes
    • Account Functions looks to see if 'profile' module installed and redirects there
    • PM looks to see if 'pm' module installed and redirects there
  • system_homepage.html template - for homepage content

I'll note to develop this, I first did a clean installation of 2.3.x, reviewed it against my installations (with modifications as well as a clean install) and then merged it all together, merging and migrating as appropriate along the way and then applied it to my integrated version with all the modules I use.


Clean Install

Why reinvent the wheel? See the official XOOPS 2.3.x Installation Notes (aka guide) posted in the Core Documentation. I'll note that it's easy to install XOOPS the first time, especially if you've ever installed a database-driven, php-based application. I can do a new one in about 3 minutes now. It's the upgrade of mature, institutionalized installations that requires some planning (as does any CMS).


These instructions are valid for upgrading to XOOPS 2.3.x from the 2.0.x series starting with 2.0.14+. If you have an installation older than that (as far back as 2.0.7.x), then there are just a few more instructions to follow (use the upgrade instructions in the release notes and/or my older article on upgrading the 2.0.x series ). Beyond that will require some legacy research on your part.

These instructions are not written for what is affectionately called a newbie, so it doesn't explain everything in detail, but it can be considered a checklist to cover all the bases to hopefully make it easier to upgrade any XOOPS site.

Note: Prior to the 2.3.x branch, I used SmartProfiles, and if you did, too, then you will need to migrate user data to the new module as I had continuing problems with SmartProfiles which appears to be abandoned. Migration isn't hard, but requires some effort.

  • Backup - I backed everything up of course; you should too (files & database)
  • Pre-Upgrade Instructions (per XOOPS instructions)
    • Unzip XOOPS release into a temporary folder
    • Delete Unneeded Files/Folders from htdocs
      • Delete install folder
      • Delete mainfile.php, favicon.ico (typically, but leave if you didn't modify)
    • Protector Module
      • Copy extras/mainfile.dist.php.protector file to upgrade/upd-2.0.18-to-2.3.0/mainfile.dist.php (edited for my debug script)
      • Move upgrade folder into htdocs
    • AltSys Module - Prevent Admin Blank Screen (if installed)
      • Copy altsys folder in current XOOPS_TRUST folder to xoops_lib/modules folder
      • In xoops_lib folder, make symlink of libs -> modules (for altsys compatibility)
      • extras/altsys_functions.php - the instructions say to move this, but don't - this release is no longer useful as the latest version of altsys (0.71a, and possible some earlier) supercedes the one published with XOOPS
  • Merge Core/Module Modifications (if in core release)
    • Merge any core files modified for your installations
      • robots.txt (only if changed)
    • Merge Frameworks
      • Essentially, start with the latest Frameworks 1.22 (and/or merged with 1.35 if used), then add/overwrite files with Frameworks for XOOPS 2.3.0, then add/overwrite files with the XOOPS 2.3.x core files. More comments in the comments section below.
    • Merge images, languages, uploads folders
    • Merge WYSIWYG editors changes (I make mods to FCKeditor, restructured again)
  • Copy/Move Files (over existing site)
  • Perform Upgrade
    • Remove files from cache and templates_c folders (keep index.html)
    • Make mainfile.php writeable
    • Run upgrade script (http://yoursite.com/upgrade)
      • Point to xoops_data and xoops_lib directories (note, you'll have problems upgrading from XOOPS 2.0.x if these aren't in your XOOPS_ROOT directory)
    • Delete upgrade folder
    • Update system, protector, and other core modules if installed
    • Update non-core modules individually (make sure using the latest versions)
  • Post-Upgrade File Restructuring
    • Move new xoops_lib and xoops_data folders into XOOPS_TRUST directory; remove the old, unneeded files and folders
      • Update mainfile.php to reflect the above changes
    • Delete cache and templates_c folders and redirect via symbolic link
    • Make mainfile.php unwriteable
    • Module Specific Changes
      • xcGal - move images folder in XOOPS_TRUST to xoops_data; requires update to module preferences, dB and/or symlink
    • Remove old, unneeded files (do check against your release)
    • Update FCKeditor module-specific configurations in all modules (if any)
  • Test - Perform integration/regression testing on all modules
    • Review templates changes/updates for all modules and incorporate as appropriate
    • If you don't want your content area to show on the home page, then you will need to empty the new system_homepage.html template

Must Installs

These will overall enhance your installation and make it much easier for you to do your business.


  • XOOPSeditors - FCKeditor - a number of WYSIWYG editors and my updated version of FCKeditor
  • Frameworks - enhancements used for a number of modules including CBB
  • SmartObjects - enhanced object framework used by SmartFactory modules, among others (may no longer be required; need to check with SmartSection)
  • Profiles - Extended User Profiles

Admin Modules

  • Protector - prevents many security issues
  • AltSys - admin module to manage blocks, templates and permissions
  • ThAdmin - theme your administration panel
  • XoopsInfo - provides information about XOOPS, server environment, etc.
  • XoopsCare - helps automatically maintain your XOOPS site
  • Backup & Restore - automatic backup of your database, other related
  • Waiting Module - implements extensible block replacing core waiting contents block
  • iStats - site usage module
  • iSearch - search stats for your site
  • MultiMenu - highly configurable menu system
  • Avatar Manager (if necessary)

Core Files Changed in NoiseMaker

These are the core files I've changed/added for my own needs. Files are listed from XOOPS_ROOT and good for noiseMaker and 2.3.2bMB01

  • class
    • smarty/xoops_plugins
      • function.block.php - Block anywhere (trabis)
      • function.xoops_block.php - Block Anywhere (Catzwolf)
      • modifier.sortby.php - my found-online code for on-the-fly sorting
      • outputfilter.xoRewriteModule.php - for xoRewriteModule (URL rewrite)
    • theme.php - additional smarty variables for templates (in xoInit function) (xoops_modid, xoops_modname, xoops_modsearch, xoops_name)
    • xoopseditor/fckeditor/<all> (several, see FCKeditor)
    • xoopsform/formtextdateselect.php - incorporated formulize default date info
    • xoopsmailer.php - RealName token added
  • edituser.php - xoRewriteModule URLs
  • header.php - for xoRewriteModule
  • language/english/<all> (several)
  • lostpass.php - to not reveal usernames, add'l tokens for mailer, xoRewriteModule URLs
  • mainfile.php (of course configs, but also debugging script, protector, SmartSection rewrite if used)
  • modules/system/
    • admin/
      • findusers/main.php (to default search to both in/active accounts)
      • users/main.php (to redirect to profile module)
    • blocks/system_blocks.php
    • language/english/blocks.php
  • pmlite.php (to send email instead of use webmail)
  • register.php - xoRewriteModule URLs
  • user.php - additional tokens for mail templates, xoRewriteModule URLs
  • userinfo.php - xoRewriteModule URLs

Post Comment
Comment Rules*
Auto Approval for Registrants
Msg Icon*
URL Email Images Inside images Smiley Flash _XOOPS_FORM_ALTYOUTUBE Source code Quote

Bold Italic Underline Linethrough  Left Center Right  

Click the Preview to see the content in action.
Enable Smiley Icons 
Enable XOOPS Codes (BBCode) 
Auto wrap lines 
Confirmation Code*

Click to refresh the image if it is not clear enough.

Input letters in the image
The code is case-insensitive



(c) 2006-2007 - Mark Boyden
Privacy - Legal Stuff - Contacts