Nothing major to consider in this release. The basic instructions above should be sufficient.

Overall this upgrade is a simple one, following all the standard advice.

BUT, it does include significant changes to many parts of the code to accommodate users of PHP version 8 (tested up to 8.0.14) and/or MySQL 8. All of these changes have been extensively tested, but no testing is perfect!
You do not NEED to upgrade PHP or MySQL to use this version of kiwitrees. It will continue to work just fine for earlier versions of MySQL, and for PHP version 7.3 or later. But please note that PHP 7.3 is no longer supported by it’s developers, so you are strongly advised to have your server upgraded in that regard.
If you do find any issues immediately after the upgrade please do the following:
1 – Log out of kiwitrees, close your browser and restart it. A number of the changes relate to session IDs, so this will reset them to a new format, and clear most issues.
2 – If the problem persist, check the Kiwitrees Support forum in case any one else has already reported the SAME issue.
3 – If they have, feel free to add to the discussion if necessary. Fixing this sort of bug is a priority, so you should not have to wait more than a couple of days for a fix. But if you prefer not to wait, you may be able to avoid it by moving your server back to versions of PHP and / or MySQL earlier than 8 temporarily. If necessary discurr that with your web host.
4 – If your problem has not already been noted, please add a new forum thread for it. PLease include a copy of any error messages you have, and a brief summary of whatever you were doing when the problem appeared.

If you use HTML blocks, the Stories module or any similar module, and you have enabled “CKEditor” (or “CKE”) to upload and display images that you don’t need to store in the normal kiwitrees private “/data/media/” folder, then there is one important factor you need to consider BEFORE starting the upgrade.

In previous versions CKE stored those images in one or both of these locations: a) an “uploads” folder in the root of your kiwitrees site (kiwitrees/uploads) or b) a subfolder of CKE itself (kiwitrees/modules_v4/ckeditor/kcfinder/upload/). Therefore you should re-locate any such images as soon as possible.

Nothing major to consider in this release. The basic instructions above should be sufficient.

Nothing major to consider in this release. The basic instructions above should be sufficient.

No significant upgrade issues in this release. The basic instructions above should be sufficient, but you should be aware of a couple of changes:

1. As always, do ensure you visit Dashboard > Home immediately after uploading the new files. This will trigger a couple of database updates, and remove a couple of no-longer needed files.
2. The page “Charts > Statistics” has had a major re-write. Therefore some “cookies” used by the old version may prevent the new version from displaying correctly (mainly missing the tabs for the Individual, Families, and Other sections). Use your browser’s settings to delete cookies then refresh the page to fix this.
3. There are some new features you might want to enable. See the Change Lists page (for Kiwitrees 3.3.6) for more information about these.

No significant upgrade issues in this release. The basic instructions above should be sufficient but do ensure you visit Dashboard > Home immediately after uploading the new files. This will trigger a couple of important database updates.

No significant upgrade issues in this release. The basic instructions above should be sufficient but do ensure you visit Dashboard > Home immediately after uploading the new files. This will trigger a couple of important database updates.

Nothing major to account for in this release. The basic instructions above should be sufficient.

The majority of this upgrade concerns bug fixes and minor improvements. However, there is one change that impacts almost EVERY file in the system. Throughout this version, the legacy code utilising the prefix “WT_” has been replaced with the prefix “KT_” for reasons that will be obvious to anyone who knows the history of kiwitrees! For any standard site, this will be totally automatic and will have no visible effect on either the operation of kiwitrees or the upgrade process.

But if you have ANY custom files on your system it is likely they will contain the “WT_” prefix, and they must all, therefore, be changed to use “KT_”. If you miss one case, either that page or your site will fail to open, and you will have somewhere an error message similar to “HTTP ERROR 403 ACCESS FORBIDDEN”. Typical custom files would include custom theme files (mystyle.css, myheader.php, mytheme.php, myfooter.php); custom language files, custom “histo” files, custom modules or copied modules, non-kiwitrees html or php files.

Note: If after your upgrade, you see error messages like this:

ERROR 8: Use of undefined constant KT_USER_ID – assumed ‘KT_USER_ID’

do not be concerned. They are caused by the stored session details from before you upgraded still expecting to see “WT_xxxx”. They do not mean the upgrade failed. Logout, close your browser and log back in. You will not see those messages again.

If you are upgrading from any version earlier than 3.3.1 please read the upgrade instructions for each version since yours before proceeding. You can upgrade safely from any version to the latest in one go, but it is wise to understand the specific issues that might arise from each version change.

Useful information

1. This version has a complete upgrade to the messaging system, including the removal of the internal messaging system. As part of the upgrade, the system will change any user’s accounts set to use “Kiwitrees uses internal messaging” to “Kiwitrees sends emails”.
2. Any messages previously stored in the internal messaging system will NOT be deleted. They remain in the same “xxx_message” table of your database, but will no longer be accessible other than by directly accessing the database. You can choose whether to retain or delete that table at any time.
3. Changes to the census assistant may result in some minor changes to the way existing census transcriptions (shared notes) are displayed compared to new ones. If you prefer to change the old ones to match the new that can be done in most cases using the Batch update (search and replace) tool. This includes the more significant change for the UK 1939 Register from RESI tags to CENS tags.

WARNING

This upgrade will DELETE the complete folder “kiwitrees/modules_v3” that was rendered obsolete at the earlier (3.3.0) upgrade if you haven’t already removed it manually. Before you start this upgrade you MUST ensure any files or data you need to keep or transfer to the new folder “kiwitrees/modules_v4” are moved out of modules_v3, or backed up in some way.

Examples of such files could include images uploaded using the WYSIWYG editor (the ckeditor module) and stored in its uploads folder (“modules_V3/ckeditor/kcfinder/uploads/image“); custom copies of standard modules; or your own custom modules.

There are no special requirements if you are upgrading from any version in the 3 series. Just follow the steps above. But if you are upgrading from a version earlier than 3.0.0 you should also follow the instructions for “Upgrading to kiwitrees 3.0.0”.

Version 3.3.0 includes many more changes than any other recent upgrade. As a result, the upgrade process is a little more complex than usual and includes a complete replacement of all modules, in a new “modules_v4” folder. The old “modules_v3” is not removed in this process so you will not accidentally lose any customisations. It will be removed at the next upgrade though. Before starting it is more important than ever that you read and follow the general upgrade instructions above and also note carefully the following additional considerations.

• Minimum requirements for kiwitrees have changed. The minimum version of PHP is now 5.6.0, and the maximum is 7.0. PHP 7.1 is not yet fully tested. Version earlier than 5.6 “might” work OK but cannot be guaranteed, and cannot be supported. If you need to change your version of PHP, do so before you upgrade, but AFTER you switch your site to “maintenance mode”. This will prevent your users (and search engines) from experiencing fatal errors they do not understand.
• If you have any custom modules (in the folder “modules_v3”) these can be safely left there until later in the process. The upgrade process will NOT lose the data stored in such modules. It will still be there when you put the modules back later.
• It is ABSOLUTELY ESSENTIAL that if you use any custom theme files (mystyle.css, myheader.php, mytheme.php, myfooter.php) or any other custom files (other than complete modules) of any kind, these files are REMOVED BEFORE you start the upgrade process. If you miss any, you will get a fatal error “403 ACCESS FORBIDDEN” when you try to re-start your upgraded site.
• Now you can safely proceed with the upgrade as described in points one to seven above.
• Once your site upgrade finishes do not forget to
  • clear and refresh your browser cache (so any display style changes are actioned)
  • review your Administration > Modules > Manage modules list and delete the ones highlighted in red (Click on the red text to delete). These are modules no longer required, and this time there will be a large number of them! BUT DO NOT DO THIS UNTIL YOU ARE ABSOLUTELY SURE ALL PAGES ARE WORKING CORRECTLY.
  • while reviewing the modules list, check that the ones you need are all enabled. It is likely that the new and replaced “Report” modules will need to be enabled
  • unset “Maintenance mode”
• Once your site is back up and running correctly, but without your custom modules and files, you can proceed to make a simple change to your customisations, then re-instate the files.
  • In each file near the top, just below the copyright statement, look for a block of code like

if (!defined('WT_WEBTREES')) {
header('HTTP/1.0 403 Forbidden');
exit;

Simply change “WT_WEBTREES” to “WT_KIWITREES”, save your file, and upload it back to its original location. For your custom modules, the change is the same but you will probably only find that section of code in files named “module.php”. Once that change is made copy your custom module(s) to the new “modules_v4” folder. If you have transferred all custom modules or had none, and you are satisfied your site is working OK, you may now (optionally) remove the no-longer used “modules_v3” folder and all its contents. If you don’t feel any need to remove it now, it will be automatically removed as part of the next upgrade in a couple of months time.

The upgrade to 3.2.3 from 3.2.2 should be quite straightforward. However there are some NEW options which will make the upgrade even smoother than before, so I do recommend you read the general upgrade instructions (above) carefully before you start. By that I mean read the top section of this page and follow the NEW steps carefully. These are different to the steps you would have read for earlier upgrades.

If you are upgrading from any version earlier than 3.0.0 you should also follow the instructions for “Upgrading to kiwitrees 3.0.0”.

The upgrade to 3.2.2 should be straightforward with no special actions required.

After the upgrade to 3.2.2 you should review your menu settings for charts and lists. These can now be configured to restrict access to different member roles. If you use the “Research links” sidebar module you will also need to reset your list of preferred links for that.

• First visit Administration > Modules > Manage modules and ensure the charts and lists you want to use are all enabled. You can simplify this process by clicking on the table headers to sort each type to the top of the list.
• Then visit Administration > Modules > Charts and Administration > Modules > Lists in turn to set your preferred access restrictions for each menu item.
• To reset links for the “Research links” module visit it’s configuration screen at Administration > Tools > Research links select the links you want and click “save”.

If you are upgrading from any version earlier than 3.0.0 you should also follow the instructions for “Upgrading to kiwitrees 3.0.0”.

There are no special requirements if you are upgrading from any version later than 3.0.0. but you are likely to find initially that you have no menus displayed. To fix this login (if necessary set your browser URL to your-domain/login.php to do this), and visit the administration pages. Just visiting there is sufficient to complete the upgrade process and allow the menus to display normally again. If you cannot access log in at all, simply delete the folder /modules_v3/menu_calendar/ from your server. That is the one causing this issue.

After upgrading from any version to 3.2.1 there are two changes you need to be aware of:

• The “Calendar” menu item no longer exists. Its sub-menu items have been moved to the “Lists” menu group, and the Day, Month, Year alternative displays combined into a single page. This is a) in preparation for making all menu sub-items fully configurable (next release), and b) to reduce the growing number of main menu items.
• The group of edit links at the base of the Families tab of individual’s pages have been moved to the main menu Edit drop-down group. This makes these edit options available from ANY of the Individual page tabs and is more consistent with the general use of the “Edit” main menu item throughout the system.

Examples of these changes can be seen on the “Changes” list page.

There are no special requirements if you are upgrading from any version later than 3.0.0

If you are upgrading from any version earlier than 3.0.0 you should also follow the instructions for “Upgrading to kiwitrees 3.0.0”.

After upgrading from any version to 3.2.0 there are a couple of things to be aware of:

• The changes affect a lot of files, and all the themes, So it is even more important this time that you thoroughly clear your browser cache before trying to use your site after the upgrade. If you see anything that doesn’t “look right”, it will almost always mean you need to clear that cache 🙂
• Like most new modules on existing sites, the new Resources menu is not enabled automatically. Details for setting it up are on the Resource menu FAQ page, in the paragraph titled “Configuration”.
• Two modules, the Changes report and the Individual report are removed in this version (replaced by new versions under “Resources”). In Administration > Modules > Manage modules you will see beside each of these the red warning: “This module cannot be found. Delete its configuration settings.” Click on that text to complete the remove of these modules.
• You should read the blog post about the new tabbed edit screens before using your upgraded site, so as not to be too surprised at this very different operation.
• You may want to review the Research links configuration (Administration > Tools > Research links) if you have it enabled. At least one new link has been added. You will need to enable it here if you want to use it. Perhaps a good time to review your list of links anyway)

There are no special requirements if you are upgrading from 3.1.0 or even 3.0.0. But if you are upgrading from any version earlier than 3.0.0 you should also follow the instructions for “Upgrading to kiwitrees 3.0.0”.

Some users have reported seeing an error message like this immediately after the upgrade, either on screen (if PHP error reporting is enabled on your server) or in the kiwitrees error log):

Notice: Undefined index: characterOrder in /xxxxxxxxxxxxxxxx/kiwitrees/library/WT/I18N.php on line 276

This is a temporary error that can either:

1. be ignored. It will disappear when the kiwitrees cache is updated (roughly every two hours), or
2. you can clear it by deleting the cache. Go to Administration > Clean up data folder > delete the “cache” folder, then refresh your browser window.

There are no special requirements in this case. But if you are upgrading from any version earlier than 3.0.0, then you should also follow the instructions for “Upgrading to kiwitrees 3.0.0”.

Kiwitrees 3.0.0 is a major update including a number of changes that affect the way you have viewed and managed your site. The basic upgrade process is exactly the same as normal (see above), but once completed there are a couple of additional steps and some possible issues to be aware of. This is not a complete list of changes, just those that might cause concern during the upgrade. The full change list is available here.

1. If your site includes any custom or old un-modified modules, these may cause a fatal error with a message like

This is because all modules that create menu items now require a simple statement describing the ‘type’ of menu they are. The options are ‘main’ for the main header menu and ‘other’ for the smaller menu group containing ‘languages, favourites, login, etc.. To fix these errors you just need to add the following code, using either ‘main’ or ‘other’, into the module.php file of the offending module(s):

// Implement WT_Module_Menu public function MenuType() { return 'main'; } 

Some users have found that after the upgrade they have no menu items at all, and no link to login or reach the administration area. If this happens to you try one or both of these URL’s:

1. your domain/admin.php If you are logged in this will get you straight to the administration screens.
2. your domain/login.php This will get you to the login page. Once logged in you can use 1 (above) to access the administration pages

Once you reach the administration pages use Administration > Modules > Manage modules to enable the menus you require, and Administration > Modules > Menus to give them the correct access levels and positions along the menu bar(s). You might find it useful to initially enable ALL modules, then disable any you subsequently decide not to use. The greatest change in this version is the complete removal of “My page”. This has involved some re-location of menu items. Ones like “My account, My individual record, Logout, and Administration” that used be part of the My page menu can now be found under your name in the top or ‘other’ menu group. click to enlarge Also resulting from the removal of “My page” is the introduction of it’s replacement, the “widget bar”. This new feature appears on all pages except the “Home” page when users are logged in. It is displayed or hidden by using a new button on the left-end of the main menu. It’s content is managed by users with the role family tree manager or site administrator from the administration pages. click to enlarge When you first upgrade you will not see this feature until you have set it up. That requires the following steps:

1. Go to Administration > Modules > Manage modules
2. Click on the column header “Widgets” twice to bring all the new widget modules to the top of the list. These are the same ones previously available on My page except for a couple not suitable for a side bar (like “charts”). click to enlarge
3. Tick “enable” for each of these you want to use. It is not advisable to try and use too many as they are positioned in a single vertical column which would become unmanageable. Just select perhaps four or five that provide the information you regularly use. Save your selection
4. Note that the above list of widgets includes one new module called “Quick links”. At present this contains links to My account, My pedigree, My individual record, and Administration.It is recommended (but not compulsory) you include this in your widget bar for convenient navigation. I hope in future to expand the use of this to allow any link to be added to or removed from this module, in much the same way as favourites are added and removed.
5. Now go to Administration > Modules > Widgets. Here you can refine the access level of each widget, and change their display order (move them up or down). Complete these setting by clicking ‘save’.

A number of themes have been removed from this release following a user survey regarding which were popular and used. The removed ones are Clouds, FAB, Minimal, and Simpl_grey. If you or your users had any of these set as their default they will revert to the kiwitrees theme. This can be changed at Administration > Family trees > your family tree > Theme tab. The use of themes has been simplified. It is no longer possible for individual users to set their own tree, nor is there any site default theme. There is now only a single place to select a theme to be used for each family tree: Administration > Family trees > your family tree > Theme tab ( or the widget module “Theme select” which does the same thing). If that is not set the display will default to the kiwitrees theme. click to enlarge Simpl_menu2. This add-on has now been included in the core code under the module name “extra menus”. The old module will still work, but only if you first amend it’s module.php as described in point 1.(Fatal error) above. However, you are recommended to transfer your simpl_menu2 settings across to the new module to avoid future upgrade complications. The change of module name does ensure your settings will be intact after the upgrade, so you only need to copy them to the new module within the administration pages. Then you can physically delete the old module from your server. Once all of the above is completed you are likely to have a number of modules appearing in the Administration > Modules > Manage modules list with the warning “This module cannot be found. Delete its configuration settings”. Once you are satisfied any settings you need to copy have been done click on that warning to complete the removal of the old module from your system.

There are no special requirements in these cases.

If you want to upgrade from any version of webtrees older than 1.4.4 the instructions are the same with one key exception. Before upgrading delete ALL the contents of the folder /modules_V3/ckeditor/. This is to accommodate the different file structure of this latest version of the CKEditor WYSIWYG editor. This is not necessary if upgrading from kiwitrees 1.4.4.0, or webtrees 1.4.5.

If you have already upgraded to webtrees 1.5, 1.6, or 1.7 series and want move to kiwitrees you will need to make changes to the database structure. If you need help with this please contact me.