Document how to bootstrap Drupal from other scripts

Please read the definition of the issue queue priority levels: http://drupal.org/node/45111
This is by no means critical.

The workflow for external scripts to bootstrap Drupal is:

define('DRUPAL_ROOT', '/path/to/drupal');
require_once DRUPAL_ROOT . '/includes/bootstrap.inc';
drupal_boostrap(DRUPAL_BOOTSTRAP_FULL);

Or something like that.
Please describe the problem you have with that.
Is the only problem the duplication of the definition of the constant in index.php, update.php, etc.? That doesn't seem to be much of a problem, I think.

Crosspost, so setting to "needs review". For me personally, this is a "won't fix", though. I think the code flow described in #2 is quite nice, because it allows other scripts to integrate with Drupal regardless of where Drupal is relative is to the script, simply by adapting DRUPAL_ROOT.

No harm taken. It is just that marking issues critical can stop development because of the issue queue thresholds: http://drupal.org/node/1201874

Regarding changing DRUPAL_ROOT, I meant the following: I develop an external script, which integrates with Drupal, then I can do write my script as I did in #2, and then tell people in my installation instructions: "Change the value of DRUPAL_ROOT to where your installation of Drupal is." I think that is better than: "Change the first part of the require_once line to point to the Drupal installation."

In the end it's a matter of taste, though.
See: http://drupal.org/node/259623 for additional considerations.

The whole purpose of DRUPAL_ROOT is to make it possible for cwd() to be a directory *other* than the Drupal root. The patch has define('DRUPAL_ROOT', getcwd()); inside bootstrap.inc, which is regressing to D6 thinking and clearly defeating the purpose. Nothing is broken here, unless it's a lack of documentation, which is a separate issue.

I'm not going to play issue ping-pong. But just so we're clear, there is no bug here. And there's no chance of changing the D7 API a year after it was released, so please discuss new stuff in the context of D8.

Moving this to documentation.
I also think DRUPAL_ROOT is fine the way it is, but you are correct that #2 should be documented somewhere. I could swear that I have seen this somewhere before, but a quick search on d.o didn't reveal anything, so.
The API doc for drupal_bootstrap() says:

To access the Drupal database from a script without loading anything else, include bootstrap.inc and call drupal_bootstrap(DRUPAL_BOOTSTRAP_DATABASE).

(http://api.drupal.org/api/drupal/core!includes!bootstrap.inc/function/dr...)
But I think that could be more explicit.
Also not sure, whether this should be online documentation or in-code or both.

Fix title.

So it sounds like the proposed resolution here is to put the information from #2 into the documentation for drupal_bootstrap()? If so, I think this is a fine idea.

Then in addition if someone wants to write up an expanded page on the subject and put it into the online Community Documentation somewhere (somewhere below http://drupal.org/documentation that is), that would also be a fine idea.

Adding this information seems like a good Novice project?

I've taken the code from #2 and put it into a patch to the documentation of bootstrap.inc.

Umm. I think it should replace the sentence in the previous paragraph that says:

To access the Drupal database from a script without loading anything else, include bootstrap.inc and call drupal_bootstrap(DRUPAL_BOOTSTRAP_DATABASE).

right?

Maybe you're right. But I'd expect that there would be reasons to do a full bootstrap and also to do a database-only bootstrap in other cases. I'll admit that I've never done either of these; I'm just trying to help out the documentation in the event that I do need them and try to look it up.

Maybe something like this:

In order to bootstrap Drupal from another PHP script, you can use this code:
@code
define('DRUPAL_ROOT', '/path/to/drupal');
require_once DRUPAL_ROOT . '/includes/bootstrap.inc';
drupal_boostrap(DRUPAL_BOOTSTRAP_FULL);
@endcode
In this example the Drupal installation to bootstrap is located at '/path/to/drupal'. If you only want to bootstrap the Drupal database you can use DRUPAL_BOOTSTRAP_DATABASE instead of DRUPAL_BOOTSTRAP_FULL. For a full description of the different bootstrap levels see the $phase argument below.
...
@param $phase
A Drupal bootstrap constant. The possible bootstrap levels are:
- DRUPAL_BOOTSTRAP_CONFIGURATION: Initializes configuration.
- DRUPAL_BOOTSTRAP_PAGE_CACHE: Tries to server a cached page.
- DRUPAL_BOOTSTRAP_DATABASE: Initializes the database layer.
- DRUPAL_BOOTSTRAP_VARIABLES: Initializes the variable system.
- DRUPAL_BOOTSTRAP_SESSION: Initializes session handling.
- DRUPAL_BOOTSTRAP_PAGE_HEADER: Sets up the page header.
- DRUPAL_BOOTSTRAP_LANGUAGE: Finds out the language of the page.
- DRUPAL_BOOTSTRAP_FULL: Fully loads Drupal. Validates and fixes input data.

I removed the 'fully' from the top sentence and referenced the $phase parameter for the bootstrap levels. There I documented all the levels explicitly. I think that is more obvious than the current documentation. The downside is that the in-code documentation of the constants is largely duplicated, but I think that is worth it. Also got rid of the word 'included' as that could be mistaken by the PHP include statement. I also added a note about the '/path/to/drupal' bit.

I can't be bothered to roll a patch right now, so just as text for now.

I think that this wording (#16) would be good.

Here's a patch with the updated documentation.

Since this needs a re-roll anyways:

+++ b/core/includes/bootstrap.inc
@@ -1971,9 +1971,29 @@ function drupal_anonymous_user() {
+ * description of the different bootstrap levels see the $phase argument below.

Since we do "@param" maybe we should call it "$phase parameter" instead of "$phase argument".

Here's the fixed version.

Ummm... Unless I am mistaken, we don't actually want to lose this line, which describes what this function does:

 /**
- * Ensures Drupal is bootstrapped to the specified phase.

We also don't want to lose this information that describes that earlier phases are automatically run if you request a later phase:

- * The bootstrap phase is an integer constant identifying a phase of Drupal
- * to load. Each phase adds to the previous one, so invoking a later phase
- * automatically runs the earlier phases as well. 

Oh, I see, it's been added to the paragraph about how to bootstrap Drupal. I don't think it belongs with that paragraph. It needs to be where it was, in its own paragraph, with the sample code afterwards.

Also, this line has a typo:

+ *   - DRUPAL_BOOTSTRAP_PAGE_CACHE: Tries to server a cached page.

server -> serve... I guess? It doesn't quite make sense to me, maybe could be rewritten to be clearer what it means.

Also, just below the fixed lines in this patch, I see:

 *   A boolean, set to FALSE if calling drupal_bootstrap from inside a
  *   function called from drupal_bootstrap (recursion).

Whenever a function is referred to in documentation, put () after the function name.

I think the suggested wording in #24 is better. Something like that could go into the @param $phase documentation actually... maybe saying:

 @param $phase
    A constant telling which phase to boostrap to. When you bootstrap to a particular phase, all earlier phases are run automatically. Possible values:
(list goes here)

That might still be a bit awkward... it's getting kind of late and my brain is not working well, but something similar should work, and I think putting it with the @param documentation makes more sense than having it above.

I *think* I caught all of the suggestions from above. Interdiff'd against #22.

Looks good! One thing to fix... This is an 8.x patch, so this line isn't correct:

+ *   require_once DRUPAL_ROOT . '/includes/bootstrap.inc';

The path should be core/includes.

Yeah, that makes sense.

+++ b/core/includes/bootstrap.inc
@@ -2130,14 +2130,26 @@ function drupal_anonymous_user() {
+ *   - DRUPAL_BOOTSTRAP_LANGUAGE: Finds out the language of the page.

Sadly, I need to mark this "needs work" again. In the meantime our bootstrap constants have changed. Specifically DRUPAL_BOOTSTRAP_LANGUAGE was removed and at the same point (after _PAGE_HEADER and before _FULL) there should now be DRUPAL_BOOTSTRAP_CODE. The line should read:
"DRUPAL_BOOTSTRAP_CODE: Loads code for subsystems and modules."

Interdiff'd against #26.

Awesome!

+++ b/core/includes/bootstrap.incundefined
@@ -2091,14 +2091,26 @@ function drupal_anonymous_user() {
+ *   A constant telling which phase to boostrap to. When you bootstrap to a

Typo: boostrap.

Fixed.

Good catch, @Tor Arne Thune.

Thanks all -- a real group effort here! I've committed the patch there to 8.x. The port to 7.x will need to have slightly different bootstrap constants in it, since the function is different there.

D7 backport.

I verified that the bootstrap constants, including their order and their description are correct. Also the "core" directory is correctly removed from the example code include statement.

Looks good to me.

Looks good to me too -- thanks all! Committed to 7.x.

I must that the trick with
define('DRUPAL_ROOT', '/var/www/drupal');
require_once DRUPAL_ROOT . '/includes/bootstrap.inc';
drupal_bootstrap(DRUPAL_BOOTSTRAP_SESSION);

doesn't always work out of the box.

eg. I am using it with PMapper but immediately after PMapper does complete all its includes, if not something in drupal_bootstrap fools PMapper as it tries to include from root filesystem (linux here) resulting in PMapper not loading.

updating issue summary