The most important file on your Drupal site is the settings.php file.
The settings.php is unique to every site and contains all of the important information that Drupal needs to run.
Inside settings.php you’ll find everything from your database type and login details to your URL and multisite options.
This tutorial is your guided tour of settings.php. If you run a Drupal site, here’s what you need to know about this vital file.
The settings.php file is what makes your site run. It’s the glue that connects your code to the database and various other things such as:
- Configuration directory
- Database settings
- Access control for update.php script
- Salt for one-time login links and cancel links, form tokens, etc.
- Base URL (optional)
- PHP Settings such as: garbage collection, session cookie settings, large text output.
- Variable overrides
- Reverse proxy configuration. This applies when Drupal is behind a reverse proxy.
- Page caching. In this instance, you have the option to omit the Vary cookie. If you do this “authenticated users would also be served the anonymous page from the cache.”
- CSS/JS aggregated file gzip compression
- String overrides
- IP blocking
- Fast 404 pages
- External access proxy settings
- Authorized file system operations
The settings.php file does a nice job explaining most of these but we will explore a few of the options that you are likely to need.
Where is the settings.php file?
If you manually installed your Drupal site, you will already know where this file is. Recall that you were asked to make a copy of default.settings.php and call it settings.php. For those who are working with a Drupal site that was setup for them (such as the case with Acquia’s Dev Desktop), then the following is of interest to you.
Each Drupal site has a directory called sites. Search/find the directories and files that make up your Drupal site (as shown in the image above).
- Open the sites directory and see a directory called default.
- Open the default directory and see the settings.php file.
- Open the settings.php file using a tool such as Notepad++ (it’s free for PC and Mac). Or if you have Dreamweaver or some other webdev application, of course that would work as well.
Domains and Paths in Drupal
Every site has a domain. Okay, that’s stating the obvious but did you know that sometimes you need to tell Drupal which domain it should use? The first set of comments you see when you open the settings.php file talks about the sites.php file and multisite configuration. Multisite configuration is beyond the scope of this tutorial but if you have a need, now you know where to start. For now, let’s keep things simple.
When you followed the steps above to locate the settings.php file, the path you followed was sites/default/settings.php. If you scroll down a bit in the file, you will see a list of sample paths denoting the various directories Drupal will look for when trying to find the settings.php file for the site whose URL is http://www.drupal.org:8080/mysite/test. In the end, Drupal doesn’t find a directory it can relate the URL to, it will seek out the default directory.
Why does this matter? Well, for most installations, it doesn’t. But one day you might want to install a new Drupal site but use the same code-base. That’s when knowing this comes in handy. Also, if you are using Acquia Dev Desktop and you use its control panel to create multiple practice sites, the feature that creates the new sites for you is actually creating multiple site directories in sites.
Since we are on the topic of URL’s, scroll down until you find the section entitled, Base URL. As the comment suggests, assigning a base URL is optional but in the event you are having issues with your base URL being detected correctly by Drupal, this is one option for trying to rectify the issue.
Default Database in Drupal
Okay, now that we have URL’s out of the way, scroll back up until you find the section on Database settings.
As you know, Drupal relies on a database to store all the configuration information as well as your content. When you download Drupal, you aren’t downloading the database that goes with it. You are downloading code that will populate an empty database with all the tables Drupal needs. This means, when you manual install Drupal, you are expected to create an empty database that Drupal can use.
Typically, all you need to know is the name of the database (let’s say you call it widget for your site widget.mydomain.com). The process by which you create your database will vary depending on your hosting environment but someplace in the process, your empty database will need to be assigned to a user and given a password as well. It’s these three pieces of data you will need when completing the installation form Drupal presents in the browser.
If Drupal is going to take care of updating the settings.php file for you, why do you need to know about this? As you can see there are other settings in the database array and if your environment expects something different, then you might need to make a change. BUT, the most common reason I can think of is when you migrate from your local installation to an installation on a live server.
Imagine if you will, you’ve built your site using Acquia’s Dev Destop and you the name of the database turns out to be a name you don’t want to use on the live server. The steps you would need to follow in migrating your site would be:
- Copy all the files to the server (this means all the files shown in the first screen shot of this tutorial).
- Use phpmyadmin to export the database from your practice site.
- Create an empty database on the server with the name, username, and password you prefer (or what your IT guy told you it needed to be).
- Using phpmyadmin on the live server, import your sql file from your localhost site.
- Edit your sites/default/settings.php file and change the databasename, username, password so that Drupal can find all your data.
Shared Databases in Drupal
If you have a situation where you need multiple sites but instead of just sharing the code-base (as we discussed earlier) you need to share the database, the settings.php file is where you tell Drupal what to do. The key to sharing one Drupal database with multiple sites is the prefix. The prefix allows you to have multiple users tables, menus tables, etc. such that site1.com and site2.com will each have it’s own users but can share the content.
There are alot of tables in a Drupal database so before you decide this is the way to go, you should spend some time understanding what each table stores so that you can ensure all the tables that need to be unique from site to site are indeed that.
As you scroll down, you will also seem other options available to advanced users but this tutorial will not dig that deep.
Controlling Access to update.php
In order to update your site’s code, your userid needs permission to run the update.php script. In the event something goes wrong and you need to log in as a user who does not have these permissions, you can temporarily turn off this access control and run the update. I would try to avoid disabling this security feature as much as possible.
You need to be aware of this next setting option if your site is deployed on a cluster of web servers or if you want to enhance security by contents from a file outside your document root. As the comments state, “you must ensure that this variable has the same value on each server” if your site is deployed on a cluster of web servers.
As you can imagine, this security feature is not something you need to worry about for most sites but if you are involved in building a large, busy site or one requiring additional security options, this will be one of your stops.
Before you go crazy changing strings via the settings.php file, just know that there are modules that can help you do that as well. Such as http://drupal.org/project/stringoverrides.
Similar to string overrides, before you try to customize $conf[‘404_fast_html’] within the settings.php file, consider utilizing the option to use a node to hold the message you desire. Visit your configuration>site information page and insert the node ID for the page that contains your desired message.
As you can see, the settings.php file has a lot going on. Depending on the site you are building and the anticipated traffic expected, most of the settings will remain as is. If you find you need to make a change, please read the instructions carefully. If they are unclear, try Googling the topic to see if others are experiencing the same issues you are to determine if the changes you want to make will be accommodated by the setting in this file.