The Settings File Conundrum Settled Once and for All...

...Quite Possibly.

NOTE - This is basically a living document, so expect it to grow be revised and changed!

There's a long somewhat religious war as far as what you should do with the settings.php file when checking it out to your local and deploying to dev, test and prod environments. The most common and now NOT my recommended way is to simply set svn ignore on the settings.php file on the directory above it... so: Exclude settings.php from a directory by typing (in this directory): svn propset svn:ignore settings.php To show the ignored files, type: svn status --no-ignore

The general idea here is that you would simply manage your own local file and svn should just leave you alone to your own management of it AFTER you've already deployed to your web server. Honestly this can get you by, but for a myriad of reasons is a really bad idea for more developers than one.

The real option (or options). At first it will seem crazy but give it a chance. We want at least 5 settings files checked into svn, one for each environment and a standard settings.php file. Now we can set these on a global environment variable or what I'll refer to as realpath. The global environment variable will not always be so doable for the common developer so we'll cover the realpath solution. Let's say your site is drupaldeveloper.com. Make a folder in your sites directory with the name of your site ie. drupaldeveloper.com. Make 5 files in this directory... settings.php, settings-local.php, settings-tst.drupaldeveloper.php, settings-drupaldeveloper.php and settings-dev.drupaldeveloper.php. Use the attached files to fill each of them out... (remove the _.txt from the end)

For core we need a patch for multisites and support for a sites.php file that aliases to the sites folders in different environments. I'll attach a patched set of files and the url that covers this hole monstrosity. In d7 it's supposed to be included (hehe, I said include.)

In Drupal 6 we need a patch to some includes files: http://drupal.org/node/231298#comment-3833390 issue thread 107 for the present (at the time I wrote this) version of Drupal-6x, Drupal-6.20. Or you can just trust me and use the attached patched bootstrap.inc file which replaces your Drupal core/includes/bootstrap.inc file (AS LONG AS YOU HAVE NOT ALREADY PATCHED THIS FILE, my attached version should be fine for 6.20). Now if you wanna be a pro you'd include your patches in a patch file available to future developers.

If you need to know how to apply patches see: the Git way http://drupal.org/patch/apply

Ok so after we have that in place we can now put our sites.php in place and this is the little file that kind of puts all of this together and should provide the AHA! moment for you. (See attached example file)

Inside you have an array of site names and their corresponding folders they point to so Drupal can serve up the different environments but without different folder names. In our example we have at the end of our sites.php file: $sites = array( 'drupaldeveloper' => 'drupaldeveloper.com', 'drupaldeveloper.local' => 'drupaldeveloper.com', 'dev.drupaldeveloper.com' => 'drupaldeveloper.com', 'tst.drupaldeveloper.com' => 'drupaldeveloper.com', 'drupaldeveloper.com' => 'drupaldeveloper.com',

'cip.drupaldevloper' => 'cip.drupaldeveloper.com', 'cip.drupaldeveloper.local' => 'cip.drupaldeveloper.com', 'cip-dev.drupaldeveloper.com' => 'cip.drupaldeveloper.com', 'cip-tst.drupaldeveloper.com' => 'cip.drupaldeveloper.com', 'cip.drupaldeveloper.com' => 'cip.drupaldeveloper.com', );

Ok so what we have here is each item on the left of => is what site the request is for and the right is what the actual folder name is that drupal actually gets everything from. The cip stuff is there to show you how to add even more sites... The trick here is as you can see that all these folder names are the same? Why? Well on your dev server you have Drupal and inside of Drupal you have sites/all, sites/default and you can also have sites/drupaldeveloper.com... you can have this same repeating system on your dev server, your test server and your prod server as well as your local. Why this part is ultimately important is that the web request and display get to the right environment and display the right stuff in the browser regardless of the folder name. So why is the folder name important you ask?

The folder name is better as the same folder name because you will find major serialized errors when you move the site (and really the site database) from local dev to tst to prod and so on if you have different names of these folders based on the actual domain name!

http://drupal.org/node/529866 contains some of the troubleshooting techniques and some of the causes... but to be clear on what we've seen as the major cause is the sudden change in serailized data. Serialized data isn't plain text like most things in the database it's serialized, sorta like encrypted... but mainly it checks the number of characters in the data. If this serialized field in the database changes from say: dev.drupaldeveloper.com/modules/page_titles to drupaldeveloper.com/modules/page_titles the number of characters have changed and the whole way drupal is built when using the variables table (where these things are held) is not capable of figuring out how many characters this needs to be and freaks out filling your logs with tons of errors... so there you have it.

Now if your environment is all basically in ONE Drupal multisite with just one core for all and your db always heads "south" as it should you'll need separate multisite names within the sites folder... and this part of the tricks listed isn't so helpful or worth doing...