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:
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.
It is strongly advised to not seriously attempt upgrading until Composr v10-final is released, as things are more likely to be unstable until then. We will update the omni-upgrader link above as new releases come out.
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
utf-8We 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:
- Close your website
- Install the utf8 addon
- Export your database as an SQL dump (e.g. from phpMyAdmin)
- Take a backup of this file
- Open the SQL dump in a text editor and search-replace all DEFAULT CHARSET=latin1 with DEFAULT CHARSET=utf8mb4
- 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
- Drop all the tables from your database
- Import the modified SQL dump back into your database
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:
ThemesAny 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 stepsIt 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 upgradingThe 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 permissionsIf 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):
XML filesIf 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.phpinfo.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';
Updating content & navigationThe following bundled addons are now non-bundled:
- community_billboard (formerly referred to as flagrant text)
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)
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)
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"
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:
- cedi → wiki †
- contactmember → contact_member
- onlinemembers → users_online
- leaderboard → leader_board
The following blocks are now renamed:
- side_ocf_personal_topics → side_cns_private_topics †
- side_stored_menu → menu †
- side_root_galleries → side_galleries †
Certain block parameter names have been changed:
- main_news: filter → select, filter_and → select_and, select → filter †
- main_multi_content: filter → select, filter_b → select_b, ocselect → filter †
- main_gallery_embed: select → filter, video_select → video_filter, ocselect → filter †
- main_cc_embed: ocselect → filter †
Certain special block parameter values (e.g. to main_awards) or URL parameter values (e.g. to the search module) have been renamed:
- cedi_page → wiki_page
- seedy_page → wiki_page
- cedi_post → wiki_post
- seedy_post → wiki_post
- all → title
- rating → average_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 themesThe 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
RedirectsYou 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)|
|OCF (our forum)||Conversr (our forum) or CNS (abbreviation)|
|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 CPFsIf 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)
Notes for developersThe following functions have been renamed:
- query_value → query_select_value
- query_value_null_ok → query_select_value_if_there
- query_value_null_ok_full → query_value_if_there
- has_specific_permission → has_privilege
- get_page_title → get_screen_title
- unneeded parameters to the pagination function has been removed
- The USER database field type is now MEMBER