Add PDO to installation requirements

Here is my patch. I don't know if there is a t() like function or an l() like function available during the DRUPAL_BOOTSTRAP_DATABASE phase. If there is, the patch will need to be updated to reflect this.

This needs to be in system.module's hook_requirements, there's no point checking on every page load. We'll also need to document it in the handbook.

I had it there first, unfortunately you will get a PDO error before you hit the hook_requirements. As soon as database.inc is included an error will popup. Unless I'm missing something, which is definitely possible since this is my first time working with the bootstrap process. This line is what first calls PDO in includes/database/database.inc:
abstract class DatabaseConnection extends PDO {

Hmm. Not sure how this works with the installer partial bootstrap, but assuming the same issue, we could maybe special case it in install.php/install.inc?

This requirement should be added to system_requirements() in modules/system.install, which is checked during the install process. I've confirmed my patch works properly during the install process and is ready for testing.

Nevermind...looking into install_main in install.php...

Maybe better to see if the PDO - if it does exist - is the PDO that does database stuff, someone could use code that happens to contain class PDO that aint the PDO you think it is

New patch that checks to see if the 'PDO' class exists and if the 'PDO' class has the 'query' function right before needing database access. The language for the error screen is my first attempt, so feel free to modify and/or clarify. Sadly, not really much we can do to SimpleTest this, but I studied the install functions and this should be the right spot. Could use some help on some PHP 4 installs to see if this works.

When an installation process starts, the first script requested is index.php, which starts a full bootstrap. During the bootstrap the file includes/database/database.inc is included, resulting in a fatal error in the definition of DatabaseConnection class: "Class 'PDO' not found" (when PDO is unavailable ofcourse). We shoud find other way to check if PDO is available before including the database.inc file.

When an installation process starts, the first script requested is index.php, which starts a full bootstrap. During the bootstrap the file includes/database/database.inc is included, resulting in a fatal error in the definition of DatabaseConnection class: "Class 'PDO' not found" (when PDO is unavailable ofcourse). We shoud find other way to check if PDO is available before including the database.inc file.

subscribing

subscribing

Hmm... I really don't see any other options besides to make a some kind of check in the database.inc file itself. Attached patch checks in the DRUPAL_BOOTSTRAP_DATABASE in bootstrap.inc and transfers to a PDO error page in install.php

We will require an approach like this #315513: Catch the absence of $databases settings array early. I can provide a patch now that #281446: Add 'status report' for installer requirements has been committed.

The problem is that the database.inc is included in drupal_maintenance_theme() within install_main(), which is called much, much before the call to install_check_requirements.

@Dave Reid: We must avoid this kind of checking in every request since it burns CPU cycles on bootstrap. Checking before the installation process should be enough.

I have created a patch that actually works as expected. It checks the PDO availability in install_check_requirements, before the inclusion of the DB API files. The patch at #315513: Catch the absence of $databases settings array early is a subset of this one, which is required to detects during the DRUPAL_BOOTSTRAP_CONFIGURATION if there is a connection defined, and if not redirect to the installer before continuing to the next bootstrap phase.

These are screenshots of the Installer status report page, the first with PDO not-enabled and the second with PDO enabled.

Tests and feedback are welcome!

Trying the patch in #16, changed the following line in includes/database/database.inc to emulate not having PDO:

Result on request to install.php:
Fatal error: Class 'DatabaseConnection' not found in /home/davereid/Projects/drupal-head/includes/database/mysql/database.inc on line 14

Result on request to index.php:
Fatal error: Class 'PDO_INVALID' not found in /home/davereid/Projects/drupal-head/includes/database/database.inc on line 137

Line 75 of install_main() in install.php require_once DRUPAL_ROOT . '/includes/database/database.inc'; runs before the call to install_check_requirements in line 125.

That would be expected as PDO_INVALID doesn't exist but PDO does. To emulate it you have to disable PDO in php.

If PDO is disabled, it would also be an invalid class, would it not? I'm just worried this is not actually being tested on a truly PDO-disabled PHP install.

So I took the time to actually disable PDO I get the same results as my emulation of renaming extends PDO:

Result on request to install.php (with patch from #16):
Fatal error: Class 'DatabaseConnection' not found in /home/davereid/Projects/drupal-head/includes/database/mysql/database.inc on line 14

Result on request to index.php (with patch from #16):
Fatal error: Class 'PDO' not found in /home/davereid/Projects/drupal-head/includes/database/database.inc on line 137

Please read my logic in #17 for why this patch does not work. There is a call to include 'database.inc' that happens before install_check_requirements in install_main().

Also, if I have PDO enabled, and the patch from #16 applied, I get the same Fatal error: Class 'DatabaseConnection' not found in /home/davereid/Projects/drupal-head/includes/database/mysql/database.inc on line 14 fatal error in install.php, so this is definitely code needs work.

It says in patch #16 that it requires the patch from #315513: Catch the absence of $databases settings array early Did you apply that also?

Patch in #16 contains the changes in the patch from #315513: Catch the absence of $databases settings array early and is the only one that needs to be applied.

@Dave Reid: To test this patch, you should disable PDO extension in the PHP configuration. It is being tested on a truly PDO-disabled PHP install.

Line 75 of install_main() in install.php require_once DRUPAL_ROOT . '/includes/database/database.inc'; runs before the call to install_check_requirements in line 125.

Yes, but it is only included when

Attached an updated patch, fixing the problems reported in #20. Since I removed the inclusion of the database.inc file from theme.maintenance.inc, is required to include it in any other place, after the requirements checking.

Please test against HEAD.

@dropcube, It's perfectly valid for a user to have their DB information in their settings.php, but not have PDO enabled. That's why I was getting the error. I'm am actually testing this with actual PDO disabled instead of emulating missing PDO. Sorry I keep chiming in, but I truly want to help and get this fixed.

Using patch in #24, valid DB connection settings, but PDO is disabled. Request to index.php or install.php results in:
Fatal error: Class 'PDO' not found in /home/davereid/Projects/drupal-head/includes/database/database.inc on line 137

Another reason it would be perfectly valid to have a valid db connection setting already is if users are upgrading from D6 to D7. Overall, this new direction of checking for PDO in install_check_requirements does the same thing as was attempted in #2-5 (by checking for PDO in system_requirements in system.install) since install_check_requirements checks all the hook_requirements of the profile's modules, which all by default include the system module.

We need to make this a special case that runs very early in install_main(), change install_verify_settings() to return FALSE if PDO is not found, or make a special case install_check_d7_requirements() that runs very early in the install to check for fatal error-making requirements, such as PDO not found.

@Dave Reid: Could you please test with a clean Drupal installation. During an installation process, that started from 0, there is not a valid DB information in settings.php. You are right, when a valid DB configuration is already created, it fails.

To fix this, is required to make some changes in the installer workflow. Also, we can not check requirements in every request, they are just checked one time, before the installation process.

Since the database information changed in D7, people won't be able to simply drop their settings.php into their install - it'll have to be fixed as part of the upgrade process (still pending) - so if they're missing PDO or some other requirement they'll hopefully find out early on there.

Another reason it would be perfectly valid to have a valid db connection setting already is if users are upgrading from D6 to D7

Yes, the same will happen to PHP 5 -only functions/features, will fail with unrecoverable fatal errors. So I think we should rework the way the requirements are checked befor continuing with this.

What do you guys think about something like #252100: "Drupal Scout": check if basic requirements are met before installing/upgrading without requiring to upload the full package

Here's another patch built off of #24.
- Moves the PDO check to system_requirements so that it can be checked by install.php and update.php
- If PDO is disabled, the install.php is allowed to get to the requirements page (and system_requirements).
- A graceful PDO error message is also displayed on update.php.

Tested on HEAD with and without PDO enabled.

@dropcube, I think install.php ought to handle fatal errors as quickly as possible - ideally moving the basic system checks before install profile installation. The scout seems like a contrib project to me.

@catch: Yes!, I just changed my mind about that. Too much to include and require to be an standalone script ;)

@Dave Reid: Even when this patch actually works and fixes the issue, I have been thinking and I would like a better approach:

The first step of the installation/upgrade process should be to run the requirements verification. For this, only bootstrap with the basis to display a maintenance theme, without including the DB layer nor any other layer that is not required.

Once the the server capabilities are checked, the user may continue with the other installer steps as it is now.

This will allow us to include as many basic requiremets as we need, without having to hard code checks before including files.

Here is an screenshot of what I mean:

Issue: #315901: Add server capabilities check to installation/upgrade tasks

@dropcube, I think that would be a good step for the install process, although it's too bad that we'd have to have two different verify requirements-type tasks. The patch I have in #31 seems to work with just the one screen. I should test it on PHP4 though.

@Dave Reid: Have in mind that if there are not server/requirements problems those screens will be skiped.

My idea is to have an initial task, where only the very basic code is loaded. Also, I don't like to do things like if (class_exists('PDO') && !empty($databases)) { include the files }. what about if tomorrow we need to check if class Foo exists before including bar.php file.

The first task may be called "Verify server capabilities" and the other one "Verify profile requirements", or whatever you guys sugest ;)

@dropcube: You make a good point. I'm not sure how it could be accomplished since on PHP4 the install.php fails to run no matter what since there are try-catch statements that fail parsing.

An approach could be to move the install.php functions to other file, and to include that file if the basic requirements are meet, but not sure if this is the Drupal way. Please follow up in this issue: #315901: Add server capabilities check to installation/upgrade tasks

@dropcube: That's a good idea and direction for the server capabilities. I'm still going to continue effort here since this will become a potential issue during D6 to D7 upgrades with fatal PDO errors when running upgrade.php. Here's a revised patch that sticks to the issue at hand.

If and when #315901: Add server capabilities check to installation/upgrade tasks lands, this changes in this patch to the install.php file can be dropped, but the rest will still be important to prevent fatal errors when running update.php.

Actually, I'm just being stubborn. #315901: Add server capabilities check to installation/upgrade tasks would be useful on update.php as well for when Drupal is updated to another major version with different system requirements.

Why are we using class_exists() to check for PDO? That will trip the autoload functionality and depend on parsing order and so forth. Instead, http://us.php.net/extension_loaded is designed for exactly this purpose. :-)

Good call Crell. Revised patch using extension_loaded.

The patch in #42 works fine with and without PDO enabled and with and without $databases setting in settings.php.

When linking to the PHP manual, I suggest using www.php.net rather than us.php.net or other national mirrors.

Code looks OK visually on quick inspection. I will take simpletest's word for it that it passes. #43 is correct about the link, though.

Doc update in #43

FYI: I think the larger size is because my ide removed some spaces at the end of some lines.

The last submitted patch failed testing.

Rollin', rollin', rollin' keep them patches rollin' rawhide.

I would suggest the change in theme.maintenance.inc gets documented better. My guess is it's made so database.inc doesn't get called prematurely. But a comment on why it's not included with the rest of them would be helpful.

The last submitted patch failed testing.

bot how you scared me so

Is there a good reason not to move all requirement checks to precede the database loading? This "server capabilities / requirements check" duplication seems likely to cause confusion.

#334086: Consistent error - declares PHP doesn't support database type has been marked as duplicate of this issue.

error message:

In your ./sites/default/settings.php file you have configured Drupal to use a mysql server, however your PHP installation currently does not support this database type.

Possible cause: PDO availble, mysql availble, PDO driver not availble.
Result: User Confusion.

Someone on #drupal had a similar issue to the one linked above - pdo and mysql installed, but not pdo_mysql. Most hosts only mention whether they have php or mysql (and maybe versions if you're lucky) - and a lot of users will only have ever needed to worry about that rather than specific extensions/drivers, so the more help we can give here the better. For a lot of people downloading Drupal 7, these errors will be the first they ever hear about the new requirements, and they're likely to be people on either commercial shared hosting, or on centrally managed servers in an organisation. We've also got the fact that this will affect people installing Drupal 7 on servers where Drupal 6 worked fine.

So if I've got it right, we need to first check if pdo is available, then check if there's a driver available. With either failure, seems like our best bet is to link to http://drupal.org/requirements - could probably start a Drupal 7 sub-page of that for now until we get to Beta ,so it doesn't get too cluttered (it's already a very complicated read).

can we have a drupal upgrade requirements checker module, so people can check if their server is capable before they upgrade.

Also +1 @dropcube

The first task may be called "Verify server capabilities" and the other one "Verify profile requirements"

as certain profiles may add additional requirements based on the modules that get loaded, also errors in the second part mean drupal can run but encountered simply fixable errors, while errors in the first part are usually unfixable without changing the server configuration.

alexandarpas - you mean for Drupal 5 / 6? - that sounds like a good idea, just needs someone to volunteer for it in contrib.

Note that this patch conflicts with #332303: bootstrap from sqlite - but we need to keep graceful error handling/information whatever happens with that.

A D6 version of Upgrade status can/should include such checks for D7.

Tested the patch by renaming /etc/apache2/conf.d/pdo.ini

It picks up the requirements check fine. A couple of things though - I agree with redndahead that this could use some more inline code comments. Also, the link should go to drupal.org/requirements - and we can link to php.net from there if needs be. For many people, enabling PDO will be 'send an e-mail to your hosting provider' or similar - so we need a nice friendly page for those people to visit when they completely fail to install Drupal on their random ass host.

Also, "availablility" is a typo.

This is still a problem on the current D7 head. On a test setup without PHP PDO enabled, Drupal just provides the following error:

Fatal error: Class 'PDO' not found in /home/kdeez/workspace/playground/drupal/includes/database/database.inc on line 184

Bumping as it doesn't seem there has been any activity on this recently and it's a critical usability issue.

ChrisBryant is right. I found this issue because what is described in #58 happened to me too with the latest D7 tar.

Sorry but is this patch adding another step to the installer?

No, it just makes sure that if PDO is not enabled, that it is caught on the 'requirements' task of the installer and that things don't fail spectacularly because PDO is not enabled (if you try it now, it's a potential massive upgrade #fail for users).

Re-roll with spelling correction and change of URL to requirements page. Is there a reason for install_verify_pdo() instead of just calling extension_loaded('pdo')?

"drupal" should be "Drupal". Or you could leave it out altogether as surely its clear what system requirements page is being referenced.

A larger issue is that I don't see on installation instructions on the requirements page except for a mention in a comment. It seems like, on a quick review, that the requirements page should list PDO as a requirement with a link to an existing or new handbook page that details installation.

patch needs to be reviewed

removed drupal from name.

Requirements page needs and will be updated for D7. I'm just preparing ahead of time.

The description is still far from good, assume one that doesn't know what PDO and API is. Try to start from scratch again, reworking this description without adding to much information.

Maybe we should not even try to explain PDO, and just forward people to on how to fix it.

Maybe we should not even try to explain PDO, and just forward people to on how to fix it.

But isn't that exactly what this does?

keith.smith: Yes it links, but what about the rest of the text? Remember that the audience of this text is the one with a "bad" host, so most likely won't know much about this stuff.

Bojhan - Can you give an example? I think this description does well to tell that there is an issue, what is the issue and where to go to fix the issue.

How about:

Your server does not have the PHP PDO extension enabled. [link to drupal.org]

The main thing is making sure people know it's a server issue (i.e. they can't just download something called PDO from somewhere to their Drupal directory to make it work). But the bulk of the work should be on the requirements page.

I like it.

Let's remove See the system requirements page for more information. from the sentence. I don't think we should link to a requirements page on d.o -- better to have the information in your Drupal site. Less indirections is better. Especially because the requirements page on d.o is not exactly user-friendly.

@Dries

It seems to me that linking to the requirements page would be best. As we come up with new ways this error can occur we can document it there instead of waiting for a commit. Especially after D7 is released.

Maybe we should make the requirements page more user-friendly.

If someone gets this error message, they're not going to be able to get past it without a significant change to their hosting environment - whether that's upgrading/recompiling PHP, modifying php.ini etc. - in most places where PDO isn't already enabled, this is going to require contacting their hosting provider, possibly changing hosting provider. In other words, there's a decent chance they won't be able to finish installing Drupal in one sitting.

We need to be able to take people through the process of understanding what PDO is, why the error might be showing up (is the extension just not enabled or is it completely missing?), and how to get it changed - which eventually could involve instructions for specific hosts (or at leat we can't only assume ssh access to the server). This is a lot of information to convey, and if we do a bad job of it, people are going to end up on google or giving up (and hopefully drupal.org/requirements eventually if we're lucky). Additionally the description for the error is absolutely not the place to put this information since there's going to be more than a couple of sentences.

There's various ways this could be done:

1. Commit the patch as is and make sure the requirements page is massively revamped as part of the d.o redesign (which it has to be anyway for people who get there before installing Drupal).

2. Ship with extra documentation on these major errors which can be viewed without a full Drupal bootstrap.

This could go two ways

a. Linking from the status report to .html files shipped with Drupal (similar to the new help system although wouldn't necessarily be connected unless we also wanted them available after install).

b. Class certain install requirement failures as COMPLETE INSTALL FAIL!11!! and make a new splash screen which looks completely different to the status report - "Sorry, your hosting environment is not configured to support Drupal, here's how to fix it".

c. link to INSTALL.txt and put the extra instructions in there.

d. some other relatively large reworking of this page.

However, these are significant changes to the installer, and are likely to need significant discussion before we can implement them - and they apply equally to incorrect MySQL, PHP versions etc.

fwiw, we already link to http://drupal.org/requirements in the following places in core:

At the moment we either have a nasty PHP error as the first thing people see when they try to install Drupal, or an addition to the status report. However I think we need to seriously consider what to do in these situations since even if a small percentage of people run into this issue.

Personally I'd support committing the patch as is, then opening a critical/release blocker issue for the "what to say if someone isn't going to make it through the installer in one sitting". I also agree with redndahead that the /requirements page is more likely to stay up to date over the 2-3 years Drupal 7 will be in production.

What about a specific handbook page on this? And then 1.

IMO, the requirements need to be prominent at d.o. and a check box completed that the user understands the requirements before downloading the file. Alright, the check box idea is a bit much but the download page must give text that gives strong warning that the hosting provider must have these installed or installable for you. And if the user has an exception the user is redirected to the download page giving the requirements after and error stating that the environment doesn't meet the requirements.

There's a related discussion over at #315901: Add server capabilities check to installation/upgrade tasks - although the fixes in this patch probably be enough to un-postpone that issue now.

Pick the right option

If a user can't get past the PDO error message he will: -
a) Work with the hosting provider
b) Re-configure his hosting environment
c) Hack through the drupal files to get past the error message
d) Wait for Drupal to resolve the issue in a newer version for all the rocket-science in the CMS
e) Dump Drupal and move on with a random CMS that doesn't do "PDO" or whatever it means or matters :)

He'll do the same as if he's on a host that doesn't support PHP 5.2. The only real options are A, B, and E. Proper error messages are there to encourage A and B rather than E. Some people will always do E, though, because they'd rather use their POS web host than Drupal. That's the price we pay for using technology that's less than ten years old.

How about helping come up with better error messages so that we can maximize A and B?

I tried to install drupal 7 today for several hours. I spent them with debugging ... as I run in several errors in the following order:

XAMPP 1.7.0 on Windows ... Apache crashes because it's not working properly with PDO (As I found out later)

I changed to another server with Ubuntu/dapper and PHP 5.1.2 and got these errors: http://drupal.org/node/540034 because drupal 7 needs PHP 5.2 as minimum. (As I found out later, too)

After this I searched in the drupal forum for the requirements. I could not find a simple page for it but several entries for different versions of drupal, lots of questions and different answers. So I wrote a polite support request to which I wanted to upload the file with my error report. The upload failed and my elaborated text to ask for help was vanished. I thought 'This is a sign, not to ask stupid questions' ... and gave up asking.

I then tried to install the latest XAMPP Version 1.7.2 for Windows Vista ... but in this Versions seems to be a bug as I couldn't get php and mysql working together. (I really tried - but only for 20 minutes.)

I then decided to fix my XAMPP 1.7.0 as described here: http://www.apachefriends.org/f/viewtopic.php?f=16&t=32617 (hint: to download latest php version rewrite the path as link is broken)

Now XAMPP works and I get this error: Fatal error: Class 'MergeQuery' not found in D:\http\drupal7\html\includes\database\database.inc on line 721

Well, I'm rather discouraged now (or one could say depressed). It would be really nice to have a simple list for checking the proper requirements or - even better - to have a 'check requirements' page as first step of the installation process.

Whith this post I vote for it - and I hope to spare somebody hours of searching and trying, searching and trying, search ...

@anschinsan: You mean like http://drupal.org/requirements that's easily findable, linked from either the README or INSTALL.txt in your Drupal download and is the #1 Google result for "Drupal requirements"?

Is this actually a support request now, or did varun21 make a mistake at #78?

Yeah that was a bad meta-data change as well as a bad attempt at sarcasm.

This is going to put up some really bad roadblocks for your average Drupal users.
I thought one of the over-arching concepts behind Drupal 7 was to make it easier to use.
At this stage of the game it won't even install on servers that have been happily running Drupal 6.