CiviCRM upgrade oddities: file overrides

One of the best things about CiviCRM is that it's customizable — you can modify it in just about any way you want.

But this great and wonderful thing can make your upgrades awful and painful, if your customizations rely on custom file overrides of PHP or Smarty *.tpl files. This is an officially supported but lightly documented way to customize CiviCRM behavior. It’s falling out of favor for all the reasons I mention here, but it still might affect you.

By the way, this doesn’t even cover any direct modifications of CiviCRM code files that you or other developers may have made on your site. That’s totally unsupported and officially a Bad Idea™.

Why is this an upgrade oddity?

If you have customized files like this, you'll need developer skills to sort it out. This is not a task for a non-technical site owner.

So can you skip this step?

No, unfortunately.

How can you know if this affects you?

It's pretty easy to know, with these steps:

• In CiviCRM, navigate to Administer > System Settings > Directories. This takes you to the Upload Directories page

• Notice these two settings:

  • Custom Templates Directory

  • Custom PHP Directory

• If both of those are blank, you can stop here. This issue doesn't affect you.

• But if there's a value in either of those, more the directory that each one is set to.

• In your hosting system file browser, navigate to those directories and examine their contents.

• If the directories are empty, to can stop here. This issue doesn't affect you.

• But if there are files in either of these directories, this needs your attention. somebody with developer skills needs to examine them and ensure they stay compatible with the upgraded CiviCRM version.

“This sucks. How can I just avoid this?”

Yeah, it’s a mess.

If you're not already in this situation, yes you can avoid it. Just don't use file overrides. And if you hire a developer for custom features, insist that they should not use file overrides either.

If you're already in this situation, there's probably a way to remove those file overrides completely. Whatever customizations they're providing, there probably another way to do it - without file overrides.

A good CiviCRM developer should be able to help you with that. You should probably explain that you're trying to keep your customizations while making upgrades as easy as possible.

Your pre-upgrade homework:

Before your next upgrade, follow the steps above to see if this issue affects you. If it does, ask your CiviCRM coach or a developer for help.

You'll want to get this sorted out before it's time to upgrade.

All the best,
A.