Version 15 Upgrade Notes

Thanks to all who helped make the v15 upgrade a success, and thanks also to everyone who has already downloaded and installed the new version. I’ve heard lots of good comments!

As I’ve helped install the upgrade for many of you, I’ve come across a few common situations that I thought I’d mention for the benefit of those who haven’t yet taken the step:

  1. The database step shows an error and nothing works. This usually means that you’re still running an older version of PHP. TNG v15 requires at least PHP 7.4, and I recommend going even higher if you can (8.0+). Most of you will be able to upgrade your PHP from the site control panel (or “cPanel”), or you can ask your hosting provider. If things still don’t work after upgrading PHP, look at the PHP config screen and make sure the following boxes are all checked: gd, mbstring, mysqli.
  2. The admin home page won’t come up. If the rest of the site works but the admin home page returns an error, it could be related to some changes with the Mod Manager (because of the counter there that shows how many mods you have, even if you have none). Here are the troubleshooting steps I take when I encounter this:
    • Make sure PHP has been upgraded (see above).
    • Install the 15.0.1 upgrade, as that includes a few fixes for the Mod Manager.
    • See if you have a file called version.php in the classes folder. If so, delete it.
    • Do you have an mmconfig.php file in the main TNG folder? If not, or if the file is there but isn’t writeable, that could be the issue. You can find this file in the v15 full version zip.
    • Is the Root Path still correct? Sometimes this can change without notice from your provider. Go to Admin/Setup/General Settings/Paths & Folders and blank out the Root Path, then save (TNG will now determine the correct path dynamically). But how do you get there if you can’t get to the Admin menu? Just go directly to admin_setup.php to get to the Setup page. It’s only the admin *menu* that doesn’t work in this situation.
  3. Menu options missing. TNG v15 now allows you to turn off individual menu options. If you didn’t do that but some are missing, go to Admin/Setup/General Setting/Menu to turn them back on. You can turn off media categories you’re not using by running the “Trim Media Menus” utility under Admin/Utilities/Post-Import Utilities.
  4. Everyone is marked as “Living”. Go to Admin/Setup/General Settings/Privacy and change the “Show living data” option from “Never” to “Depending on user rights”. The “Never” option there did not do what most people expected, so I removed it. Sites that had “Never” selected anyway might find themselves in this situation. The “Depending” option is what you wanted anyway. 🙂
  5. Google Maps show an error on top of the maps. This isn’t actually a result of the upgrade, but I’ve noticed it enough to say something. If you see the maps but there’s a message on top that says the maps are “for development purposes only”, that means that Google wants you to link a credit card to your Google account. They won’t charge you for using the maps unless you request an astronomical number of maps in a month, so there’s not much to worry about there.

Illegal mix of collations error

Tables and columns in a MySQL database are created with a “collation”, which dictates what characters can be used in the information. When new tables or columns are added to your TNG database during an upgrade, the database will use its default collation to create those. Normally that’s what we want, but if your default collation has changed since your tables were originally created, then you could end up with a mismatch that MySQL doesn’t like. That when you’ll see this message like this on your TNG site:

Illegal mix of collations (latin1_swedish_ci,IMPLICIT) and (utf8mb4_general_ci,COERCIBLE)

To fix this, you’ll need to edit your database structure and fix the mismatch so that everything is using the same collation.

Start by opening phpMyAdmin on your site control panel (aka, the “cpanel”). Ask your hosting provider if you need help finding it (it’s not part of TNG).

Once you’re in phpMyAdmin, select your database by clicking on it in the left column. You should now see all the tables in the database on the right, and one of the things listed for each table is the collation. Scan the list and take note of the predominant collation (the one used the most).

Next, click the Operations tab at the top of the page. In the Operations window, look for the Collation section near the bottom. It looks like this:

Now use the dropdown list to select the predominant collation you noticed earlier, then check the boxes below to propagate the collation to all tables and columns:

Finally, click “Go” in the lower right corner to make the change.

Uploading folders with “replace” vs “merge”

One problem TNG site owners sometimes have during an upgrade is discovering that some images or other files are missing when the upgrade is complete. How did that happen?

The cause of this trouble is folders that get uploaded in “replace” mode (as opposed to “merge” mode). When a folder is uploaded in “replace” mode, the new folder totally replaces the old folder, so if there were any files not included in the new folder, those files will end up getting deleted from the website. In contrast, uploading in “merge” mode will allow the new files to overwrite older files with the same names, but it won’t delete anything.

So how do I know when my FTP program is in “replace” or “merge” mode? Unfortunately there’s no definitive answer, since all programs are different, so you might have to hunt around in your settings. In the popular Mac program “Transmit”, this can be found under Settings and then Transfers:

In that image, notice the “Uploading folders” option at the bottom. Here’s what it looks like with the options open:

There you can see that you have both a “Replace the existing folder” option and a “Merge the existing folder” option (among others). If you use a different program, you will likely have a similar option. Ask the company that makes the software if you’re not sure where to find it.

If you do end up replacing a folder when you didn’t mean to (and thus end up deleting some files), you can get them back by downloading the TNG full version zip and then uploading the folder again from there. That should restore all the default files from that folder for the current version. If you had custom images or files that were removed from the folder in question, you will need to upload those again as well.

“Undefined function”: Time to upgrade

Like TNG, the underlying PHP is constantly changing, and new updates are released every few months. Hosting providers don’t always install the latest version right away, but they almost always get to it eventually.

When that happens, there are usually a handful of PHP functions that for whatever reason are no longer supported in the newer version. For example, the “session_register” and “session_unregister” functions were removed a while back, and all the “mysql” functions (like mysql_query) were removed with the jump to PHP 7.0.

I have always tried to keep pace with these changes, removing functions like that from the TNG code before PHP removes them, so if you keep your TNG up to date you shouldn’t experience any problems. If you’re still running an older version of TNG, however, you may suddenly run into trouble if your hosting provider upgrades PHP without notice. It won’t affect every page on your site, but if you happen to execute some of the problem code, you’ll be stopped short. Sometimes you might get a blank page, but most of the time you’ll see an error message like this:

Fatal error: Call to undefined function session_register() in /public_html/genealogy/globallib.php on line 5

It’s possible that a message like this would refer to a TNG problem, like if a key file was missing. If you want to know for sure, do a Google search on the the middle part of the error message (“Call to undefined function session_register()”, in this instance). If it’s just a problem with your TNG files, you probably won’t get many results. If the function named is one that PHP has removed though, you should see several hits referring to that fact, and you can know that it’s time to upgrade TNG.

To get the upgrade at a discount, you can always go back to your previous TNG downloads page. The payment options will be visible in the “TNG Updates” section. If you’ve lost the access info for that page, please feel free to drop me a note.