I was introduced to CiviCRM a few years ago when a new customer needed a replacement for an old poorly designed database solution and needed it quickly. After getting quotes starting at $10,000 for systems supposedly designed for non-profits, I stumbled on CiviCRM which was free, open source and seemed to have a good community behind it.  The project became one of my notable success stories as I was able to discover a new product and learn enough about it to implement it in a short time.  I even managed some advanced customizing of the system.

The system has worked without any serious issues for the past few years and I hadn’t heard from the customer very often.   Then, last week, I got an e-mail stating they’d moved their offices, made some changes to their network and needed me to come in and get the software working again. Everything went smoothly for the first 10 minutes I was there. Then I realized that CiviCRM was running incredibly slow and its top menu had disappeared which pretty much makes it unusable for anyone who doesn’t want to type in a lot of complicated URLs.  Again, it had been quite a while since I’d touched CiviCRM or dealt with the specifics of their system so I ended having do do a bit of research to find out what was going on.

In the end, the solution came down to updating the civicrm.settings.php file with the new network information. Once that was done, the system worked great but I ended up taking the long way around to discover it. Along the way, I refreshed my knowledge of CiviCRM and learned a few new things as well. This was just as well as I was able to be even more confident that no other problems lurking in their system when I was done.

The devil is in the civicrm.settings file …

As I mentioned above, the civicrm.settings.php file is one of the first places to check if you’re having problems with the site. This file contains a wealth of settings that control the operation of the plugin and you should know where it is and be generally familiar with its role. Among the settings it contains are:

• Links, login and password to the supporting CMS (WordPress, Drupal, etc..)
• CiviCRM database settings with login and password. This is important since the CRM can be housed in a separate database than the CMS. You can also change the database the CRM is pointing to just by changing the one line in this file.
• File system paths for referenced files
• Site URLs for system resources
• Memory limits

All of these, including the logins and passwords are automatically set by the installer but it is possible for the installer to set them wrong. I found this out when I was installing CiviCRM for my own use on one of my sites which I’ll mention more about later.

In older versions of CiviCRM, this file is located in the main plugin directory at ..\wp-content\plugins\civicrm\. In version 4.7 and later, the installer creates it in the ..\wp-content\uploads\civicrm\ directory. The settings file also contains a generous amount of instructions for the various settings which will guide you through making any necessary changes.

Another fun bit of trivia about this file is that if it’s not located in the right place, WordPress can actually deny you access to the CiviCRM settings pages in your site. You’ll get a blank page with the single apologetic line “Sorry. You do not have permissions to access this page.” which can be quite jarring to a site owner.

… and his minions might be the civicrm_settings table.

Depending on the version of CiviCRM you’re using, the civicrm_setting table might contain a number of paths that the system uses to access files. This can include image uploads, CSS files and other important items. In some of the posts I found online, the missing menu in CiviCRM was linked to a discrepancy between the Image Upload Directory and the Image Upload URL settings. These settings are no longer available in the newest version that I installed for my own use. If they are still present in your version, they are stored in the civicrm_setting table and can be edited there directly.

It’s best to make any changes through the interface but It’s also good to be generally familiar with the tables in your CiviCRM database, especially if you run into the access error mentioned in the last section. It might provide you with a quick way to fix your broken site or save you the time of navigating through lots of screens.

Make sure PHP is updated before you install the files.

CiviCRM is not the typical plugin where you just click Install and Activate from the Plugins page. The procedure is still simple but there’s a bit more manual work.

1. Download the appropriate ZIP file from CiviCRM.org.
2. Unzip the file into your wpcontent\plugins directory.
3. Create the ..\wp-content\plugins\files directory and make sure the site has write permissions on it.
4. Click Activate on the Plugins page if CiviCRM isn’t already activated.

WordPress might auto-activate the CiviCRM plugin and display a message at the top of the Plugins page that it needs to be configured which includes creating all the database tables. When I installed it on my own site this week and tried to configure the plugin, I was informed that the 5.x version of PHP my site was using was not sufficient for this version of CiviCRM; the new version needs 7.0 or above.

After updating PHP, I spent the next 15 minutes or so trying to fix the settings file and looking at plain white pages with lots of error code about login errors. It appeared that the system had already created the settings file at this point and assigned incorrect usernames and passwords to the database settings. I also discovered that the resulting errors had taken down the entire site. In order to get the site back, I had to delete all the CiviCRM files from the plugins directory and start the install from scratch. I was actually lucky that it was that easy.

Side note: It’s an excellent idea to make a backup before making any significant changes to your site. I recommend All-in-One WP Migration by ServMask. It’s a simple plugin to use that does quick exports and imports of a site and will even let you change specific text (such as a domain URL) throughout an entire site. It’s primarily meant for migrating a site from one server to another but works great for backups, too.

Documentation, as always, is key.

I’m not talking about the CiviCRM documentation here, although that’s helpful, too. I’m talking about the documentation you maintain as the site owner. This includes records of any changes that you make to the site, including customizing of the CRM. It’s a great idea to maintain a journal of any work done on the site and any troubleshooting of problems because history repeats in the tech world as in life.

This is an idea that I admit I have not implemented as well as I should have in my own work. I’ve made use of e-mail and even this site to save some of my notes and discoveries but the temptation to just jump in there and pound the problem into submission is strong. Midway through troubleshooting the client problem, I started to wish I had kept an explicit log of the process so I could more easily refer to some of the things I’d tried and options I’d chosen. In addition to avoiding repetition, it can help with the thought process to review what’s been done. Fortunately, it all worked out in the end but, going forward, I’ll be maintaining a lot more dedicated logs of my own work.

---

C# 13 and .NET 9 – Modern Cross-Platform Development Fundamentals: Start building websites and services with ASP.NET Core 9, Blazor, and EF Core 9

• Explore the newest additions to C# 13, the .NET 9 class libraries, and Entity Framework Core 9
• Build professional websites and services with ASP.NET Core 9 and Blazor
• Enhance your skills with step-by-step code examples and best practices tips

Check Price

ComeauSoftware.com uses affiliate links through which we earn commissions for sales.

---