Upgrading from ocPortal v8/v9 to Composr v10

  • Added
  • Author:
The general approach to upgrading to Composr is similar as upgrading between ocPortal releases.

You use the upgrader script (upgrader.php) to proceed through the steps. One of these steps includes pasting in a URL to an upgrader file, which is provided below:
Omni-upgrader package

This "omni-upgrader" package works with 8.1.37+ and 9.0.33+, so there's no need for generating custom packages for different origin versions for this particular upgrade.

If you are not upgrading from the last release of ocPortal, make sure the data/upgrader2.php file is that of the latest version – as there is an important bug fix in that file.

A key objective of Composr v10 is to create a more streamlined product. In order to make things more consistent, or to remove bloat, some compatibility changes have occurred. We recommend reading this full article, and plan the process out, before starting the upgrading.

Upgrading from before v8 (i.e. v7 and lower) is not supported anymore – as a lot of legacy upgrade code has been removed from our code base. We have tested doing upgrades from v8 and v9. If you have a very old version, you should upgrade to v9, then separately from v9 to v10 (don't bother making any custom themes work with the intermediate v9 step though).

ocPortal v9 themes are not directly compatible with Composr v10. However, themes can be converted without a huge amount of work. Guidelines are provided for this below.

Prior to upgrading


We have moved our default from using region-specific character sets, such as latin1 (aka ISO-8859-1), to Unicode.

This is an important step for us, but unfortunately is complex and disruptive.

It is best to convert your website to utf-8 before upgrading, by following these instructions:
  1. Close your website
  2. Install the utf8 addon
  3. Export your database as an SQL dump (e.g. from phpMyAdmin)
  4. Take a backup of this file
  5. Open the SQL dump in a text editor and search-replace all DEFAULT CHARSET=latin1 with DEFAULT CHARSET=utf8mb4
  6. Following from the above, change utf8mb4 to utf8 for just the following tables: addons, f_saved_warnings, gsp, msp, newsletter_subscribe, theme_images, tickets, import_parts_done, and, wordfilter
  7. Remove KEY `is_im` (`is_im`,`room_name`), if it is there
  8. Drop all the tables from your database
  9. Import the modified SQL dump back into your database
(more detailed instructions, written for phpMyAdmin, are in the internationalisation tutorial)

Alternatively, you can continue to use latin1/ISO-8859-1 by putting this into your lang_custom/EN/global.ini file after upgrading to Composr v10:




Any custom themes or overridden templates/CSS on the default theme, should be backed up then deleting on disk. i.e. delete the themes/<themename> directories for any custom themes and any themes/default/templates_custom/*.tpl and themes/default/css_custom/*.css files.

Order of steps

It is very important that you run the "4) Do a file integrity scan" step of the upgrader before the "5) Do a database upgrade" step, and you remove alien .php files that relate to the earlier ocPortal version (these will be automatically checked for deletion).
If you do not do it in the correct order then old ocPortal modules still on disk will try and reinstall themselves and it will make a mess.

Detailed upgrading

The normal upgrade process will cover the most critical aspects of upgrading. Some special cases are described below, some of which we try and automatically handle for you or only apply to some servers.

File permissions

If your server doesn't have suEXEC or equivalent (i.e. if you need to set file permissions), set the following new directories to 777 (full directory permissions):
  • caches/guest_pages
  • caches/lang/<for-each-language>
  • caches/lang
  • caches/persistent
  • caches/self_learning
  • data_custom/modules/web_notifications
  • data_custom/sitemaps
  • data_custom/xml_config
  • uploads/cns_avatars
  • uploads/cns_cpf_upload
  • uploads/cns_photos
  • uploads/cns_photos_thumbs
  • uploads/repimages

XML files

If you have used customised breadcrumbs or field filters, be aware that data_custom/*.xml have moved to data_custom/xml_config/*.xml.

The upgrader handles this automatically if file permissions are set correctly (see above).

info.php is now _config.php

info.php is now _config.php, as we wanted a clearer filename that is consistent with our current terminology and stands out.
Also you need to change ocf_table_prefix to cns_table_prefix, and use_mem_cache to use_persistent_cache.

Composr will try and do the above changes automatically, but it can't do this on all servers. If it can't, it will provide an error during upgrade and you'll need to do it yourself.

We also recommend you add this line:


$SITE_INFO['self_learning_cache'] = '1';
… to get the full benefit of v10 performance improvements.

Updating content & navigation

The following bundled addons are now non-bundled:
  • weather
  • iotds
  • community_billboard (formerly referred to as flagrant text)
  • tester
(you will be able to have this functionality back by installing the respective non-bundled addons)

The following addons are now removed entirely:
  • devguide (some of it rolled into non-bundled testing_platform addon)
  • guestbook (the new page templates system has a guestbook template)
  • bulkupload

Items below marked with a dagger (†) will be automatically handled within the upgrader.

The following blocks have been discontinued:
  • main_feedback (use the main_contact_us or main_contact_simple block instead) †
  • main_sitemap (the menu block now provides the same functionality) †
  • main_as_zone_access (Tempcode programming can provide equivalent functionality)
  • main_recent_galleries (use main_multi_content)
  • main_top_galleries (use main_multi_content)
  • main_recent_cc_entries (use main_multi_content)
  • main_recent_downloads (use main_multi_content)
  • main_top_downloads (use main_multi_content)
  • main_download_tease (use main_multi_content)
  • main_gallery_tease (use main_multi_content)

The following Comcode tags have been discontinued:
  • thread (use the topic tag)
  • php (use the code tag)
  • sql (use the code tag)
  • internal_table (use the box tag) †
  • external_table (use the box tag) †
  • upload (use the media tag)
  • exp_ref (use the media tag)
  • exp_thumb (use the media tag)
(Custom Comcode tags may be created to provide backward compatibility if required)
Additionally, the bundled youtube Custom Comcode tag is discontinued, because the new media API provides equivalent but broader functionality.

The following screens have been discontinued, as they were rarely used and redundant:
  • "List of galleries"
  • "Downloads Tree"
  • "Wiki+ Tree"
  • "Catalogue Category Tree"
(they may all now be fabricated using the new Sitemap functionality, via the menu block)

The following other features have been discontinued:
  • Saved searches (you can simply bookmark search result screens instead)
  • Comcode XML (XML has gone out of favour / Comcode/HTML5 has evolved past it)
  • Add-New-Page Wizard / automatic adding of new catalogues to menus (automatically managed menus are the new helping hand for newbies, and the normal Comcode page editor has been enhanced)
  • Wide Zones (if you want a zone to be wide, just leave the left/right panels blank - user configurability of zone layout was bloat, given all the cool new features users have to come to grips with, and given what responsive design techniques can now achieve)

The following front-end modules have been renamed:
  • cediwiki
  • contactmembercontact_member
  • onlinemembersusers_online
  • leaderboardleader_board
Menu links will be adjusted automatically.

The following blocks are now renamed:
  • side_ocf_personal_topicsside_cns_private_topics
  • side_stored_menumenu
  • side_root_galleriesside_galleries

Certain block parameter names have been changed:
  • main_news: filterselect, filter_andselect_and, selectfilter
  • main_multi_content: filterselect, filter_bselect_b, ocselectfilter
  • main_gallery_embed: selectfilter, video_selectvideo_filter, ocselectfilter
  • main_cc_embed: ocselectfilter

Certain special block parameter values (e.g. to main_awards) or URL parameter values (e.g. to the search module) have been renamed:
  • cedi_pagewiki_page
  • seedy_pagewiki_page
  • cedi_postwiki_post
  • seedy_postwiki_post
And specifically just for main_multi_content:
  • alltitle
  • ratingaverage_rating

Some main_leader_board block options are now config options instead. This is necessary given the leader-board snapshots were never isolated between different block instances, which led to possible inconsistencies.

Wiki+ changes history and post edit/delete history will be lost on upgrade, as the new revisions system replaces these features.

Upgrading ocPortal v9 themes

The best approach is to create a new base theme using the same mechanism you did for your original theme (either using the Theme Wizard or making an empty theme), then to start applying your changes back file-by-file.

Use a diff tool such as DiffMerge to compare your theme files to the originals. This is easy, as ocPortal saved the originals as <file>.editfrom. For whatever changes you had made, re-apply those same changes in your new Composr theme. In most cases the changes will be exactly the same, it's just the files aren't all directly compatible anymore.

The process may be a bit tedious, but shouldn't take more than a few hours unless you have a very highly-customised theme.

Important structural changes:
  • ocf.css is now cns.css
  • JavaScript files are now stored in their own directories, rather than the main templates directories, e.g. templates/JAVASCRIPT_STAFF.tpl is now javascript/staff.js
    • A special case: templates/JAVASCRIPT.tpl is now javascript/global.js


You may want to add a rewrite rule into your .htaccess for remapping old Wiki+ URLs, e.g:


RewriteRule ^(.*)cedi(.*)$ $1wiki$2 [R=301,NC,L]

A primer on new terminology

Old ocPortal term New Composr term
ocPortal Composr CMS (or just Composr)
ocP (abbreviation) CMS (abbreviation)
OcCLE Commandr
OCF (our forum) Conversr (our forum) or CNS (abbreviation)
ocFilter Selectcode
ocSelect Filtercode
Validation (as in web standards, not content validation) Web standards
Validation (as in forms, not content validation) Checking / Sanitisation

Note that the words 'select' and 'filter' have been flipped around. We feel this is better terminology.

Any technologies or addons that started with 'oc' now have new names. For example, our ocWorld addon is now called Buildr.

Issues with CPFs

If you get any errors a bit like:


Unfortunately a query has failed [UPDATE ocp_f_member_custom_fields SET field_3='', field_4='', field_5='', field_11=8, field_12=NULL, field_21='', field_22='', field_23='', field_24='', field_26='', field_27='', field_28=545, field_29=825, field_30=2650, field_31=1, field_32=NULL WHERE (mf_member_id=2) LIMIT 1] [Column 'field_12' cannot be null] (version: 10 RC8, PHP version: 5.6.8, URL: /composr/index.php?page=members&type=view&id=2)
… when editing member profiles, then this is likely due to a previous bug in an ocPortal version now triggering an issue with Composr's increased strictness. To resolve observe the CPF ID involved (#12 in this case) and then pass that CPF through an empty edit. It should automatically fix the underlying DB schema for that field.

Notes for developers

The following functions have been renamed:
  • query_valuequery_select_value
  • query_value_null_okquery_select_value_if_there
  • query_value_null_ok_fullquery_value_if_there
  • has_specific_permissionhas_privilege
  • get_page_titleget_screen_title

Additional changes:
  • unneeded parameters to the pagination function has been removed
  • The USER database field type is now MEMBER


Back to Top