Take a full backup before performing any upgrade, but especially a big one like this.
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.
ocPortal site stopped working entirely due to a PHP upgrade?
ocPortal is not compatible with anything newer than PHP 7.1, and older versions of ocPortal not even that. If PHP has been upgraded on your server and you cannot temporarily roll it back until you have upgraded, see this article:
Upgrading ocPortal sites if PHP compatibility breaks - Composr
Older than 9.0.33?
If you are on a v9 release older than 9.0.33, you can try your luck upgrading your upgrader by hand. If the upgrader is upgraded then you should then be able to use it to upgrade to Composr.
This is not guaranteed to work, as there are changes to many files between each version, but there's a reasonable chance the upgrader itself will be drop-in-compatible.
Here is where you can get the latest files:
sources/upgrade.php
data/upgrader2.php
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
utf-8
If you are not experienced working with database character sets, you may want to shelve this, see "Chickening out for now" below".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:
- Close your website
- Install the utf8 addon – the ocPortal site no longer exists, but this step was not necessary if you have committed yourself to doing the upgrade
- Export your database as an SQL dump in latin1 format (e.g. from phpMyAdmin, or with mysqldump --default-character-set=latin1)
- Take a backup of this file
- Open the SQL dump in a large-file supporting text editor (such as Large File Editor, or nedit) and search-replace all DEFAULT CHARSET=latin1 with DEFAULT CHARSET=utf8mb4, and save with the utf-8 character set (or if your text editor doesn't support character set changing, change it using iconv, iconv options -f iso-8859-1 -t utf-8 myfile.sql -o myfile-new.sql)
- 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 - Remove KEY `is_im` (`is_im`,`room_name`), if it is there
- Drop all the tables from your database
- Import the modified SQL dump back into your database
Chickening out for now
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:Code
[strings]
charset=ISO-8859-1
Themes
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:
Code
$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
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
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)
- 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)
- 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 †
- 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 †
- cedi_page → wiki_page
- seedy_page → wiki_page
- cedi_post → wiki_post
- seedy_post → wiki_post
- all → title
- rating → average_rating
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
Redirects
You may want to add a rewrite rule into your .htaccess for remapping old Wiki+ URLs, e.g:Code
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:Code
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_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
Edited
Comments
Prior to upgrading
utf-8
Modified the mysql database as suggested and received the following error after dropping the tables and importing the modified sql file…
Error
SQL query:
ALTER TABLE `ocl4_chat_rooms`
ADD PRIMARY KEY (`id`),
ADD KEY `room_name` (`room_name`),
ADD KEY `is_im` (`is_im`,`room_name`),
ADD KEY `first_public` (`is_im`,`id`),
ADD KEY `allow_list` (`allow_list`(30))
MySQL said: Documentation
#1071 - Specified key was too long; max key length is 1000 bytes
None of the keys were created. How can I fix this please?
Also, as a point of information the tables listed for modification here: Composr Tutorial: Localisation and internationalisation - Composr are different from the list of tables above.
Sorry about that. Somehow this slipped through our testing.
I have updated the instructions with some possibilities. I recommend moving over to InnoDB, which is one of those possibilities. A Commandr/OcCLE command is given which is for guiding Composr's performance.
Upgrading from ocPortal v8/v9 to Composr v10 - Composr
I competed step 7 but that is where the instructions stop. I assume the next step (8) would be to go to the upgrader, but I have no URL to give it.
Hi
I finish the install, and I am upgrading from Oc Portal 9 (latest version available before the composr switch.
Thansk
Not sure if it's a theme issue or not, maybe it is? My theme is simply CSS edits of the default theme, for the most part, with a script that was ran to replace button images with CSS buttons. But yes, no easy upgrade for me…
"Right now where it would show the tree lists of child pages on my wiki home page it just shows a number. " - could it be a themeing issue? A lot of templates have changed, we haven't been able to maintain compatibility with v9 themes to that level I'm afraid. Particularly what it could be is that what were previously separate templates are now merged together in a few cases.
Btw that's what I meant concerning child pages, the cold pages of a wiki page. Right now where it would show the tree lists of child pages on my wiki home page it just shows a number.
There are other issues to, like complaining about misusing front page symbols and the like. Lots of little things to track down.
I guess I'll retry it again later after more bugs have been worked out? Here's hoping that I'll even be able to upgrade my site - there is a quite a bit of custom work in it after all.
Missing image files, I'm guessing maybe menu icons? It might be that because the paths to the theme images have changed you'll need to re-associate these.
The Wiki+ tree feature is no longer there, but can be replicated via the new Sitemap functionality. You'd create a page with a menu block like:
Code
[block param="site:wiki:browse:1" type="sitemap" silent_failure="0" cache="0"]menu[/block]
The nice thing about the Sitemap is it's one unified system that's very flexible, as opposed to v9 having lots of separate systems doing similar things.
"child pages" - not sure what that issue would be, if there's a bug please report.
Fatal error: Call to undefined function has_solemnly_declared() in /home/diablus/public_html/portal/sources/tempcode.php on line 730
I think that i did some mistakes in importing database. I have downloaded my sql in the server then uninstalling OCPortal. I didn't read this guidence before.
Now, i have backed up data base sql but in latin1 format. I try to import but the database can not be used because different type with Composr database (utf8). So, how can i importing or converting database from db ocportal 9 to composr in this condition?
Thanks.
We acknowledge that the latin1 to utf8 jump makes things awkward.
You may want to just defer the change. Make a lang_custom/EN/global.ini file that specifies iso-8859-1 (i.e. latin1 in MySQL terms) as the instructions suggest.