bootstrap.inc 25 KB
Newer Older
1
<?php
2

3
4
5
6
/**
 * @file
 * Functions that need to be loaded on every Drupal request.
 */
Dries's avatar
   
Dries committed
7

8
use Drupal\Component\Utility\Crypt;
9
use Drupal\Core\Logger\RfcLogLevel;
10
use Drupal\Core\Test\TestDatabase;
11
use Drupal\Core\Utility\Error;
12
use Drupal\Core\StringTranslation\TranslatableMarkup;
13
use Symfony\Component\DependencyInjection\Exception\ServiceNotFoundException;
14

15
/**
16
17
18
19
20
21
22
23
 * Minimum allowed version of PHP.
 *
 * Below this version:
 * - The installer cannot be run.
 * - Updates cannot be run.
 * - Modules and themes cannot be enabled.
 * - If a site managed to bypass all of the above, then an error is shown in
 *   the status report and various fatal errors occur on various pages.
24
 *
25
 * @see install.php
26
27
28
 *
 * @todo Move this to an appropriate autoloadable class. See
 *   https://www.drupal.org/project/drupal/issues/2908079
29
 */
30
const DRUPAL_MINIMUM_PHP = '7.3.0';
31

32
33
34
35
36
37
38
39
40
41
42
43
/**
 * Minimum supported version of PHP.
 *
 * Below this version:
 * - New sites cannot be installed, except from within tests.
 * - Updates from previous Drupal versions can be run, but users are warned
 *   that Drupal no longer supports that PHP version.
 * - An error is shown in the status report that the PHP version is too old.
 *
 * @todo Move this to an appropriate autoloadable class. See
 *   https://www.drupal.org/project/drupal/issues/2908079
 */
44
const DRUPAL_MINIMUM_SUPPORTED_PHP = '7.3.0';
45

46
47
48
49
50
51
/**
 * Minimum recommended version of PHP.
 *
 * Sites installing Drupal on PHP versions lower than this will see a warning
 * message, but Drupal can still be installed. Used for (e.g.) PHP versions
 * that have reached their EOL or will in the near future.
52
53
54
 *
 * @todo Move this to an appropriate autoloadable class. See
 *   https://www.drupal.org/project/drupal/issues/2908079
55
 */
56
const DRUPAL_RECOMMENDED_PHP = '7.3';
57

58
59
/**
 * Minimum recommended value of PHP memory_limit.
60
 *
61
62
63
 * 64M was chosen as a minimum requirement in order to allow for additional
 * contributed modules to be installed prior to hitting the limit. However,
 * 40M is the target for the Standard installation profile.
64
65
66
 *
 * @todo Move this to an appropriate autoloadable class. See
 *   https://www.drupal.org/project/drupal/issues/2908079
67
 */
68
const DRUPAL_MINIMUM_PHP_MEMORY_LIMIT = '64M';
69

70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
/**
 * Error reporting level: display no errors.
 */
const ERROR_REPORTING_HIDE = 'hide';

/**
 * Error reporting level: display errors and warnings.
 */
const ERROR_REPORTING_DISPLAY_SOME = 'some';

/**
 * Error reporting level: display all messages.
 */
const ERROR_REPORTING_DISPLAY_ALL = 'all';

/**
 * Error reporting level: display all messages, plus backtrace information.
 */
const ERROR_REPORTING_DISPLAY_VERBOSE = 'verbose';

90
91
92
93
94
/**
 * The maximum number of characters in a module or theme name.
 */
const DRUPAL_EXTENSION_NAME_MAX_LENGTH = 50;

95
/**
96
 * Time of the current request in seconds elapsed since the Unix Epoch.
97
 *
98
99
100
101
102
103
 * This differs from $_SERVER['REQUEST_TIME'], which is stored as a float
 * since PHP 5.4.0. Float timestamps confuse most PHP functions
 * (including date_create()).
 *
 * @see http://php.net/manual/reserved.variables.server.php
 * @see http://php.net/manual/function.time.php
104
 *
105
 * @deprecated in drupal:8.3.0 and is removed from drupal:10.0.0.
106
 *   Use \Drupal::time()->getRequestTime();
107
108
 *
 * @see https://www.drupal.org/node/2785211
109
 */
110
define('REQUEST_TIME', (int) $_SERVER['REQUEST_TIME']);
111

112
113
114
115
116
117
118
/**
 * Defines the root directory of the Drupal installation.
 *
 * This strips two levels of directories off the current directory.
 */
define('DRUPAL_ROOT', dirname(dirname(__DIR__)));

Dries's avatar
Dries committed
119
/**
120
121
122
123
 * Returns and optionally sets the filename for a system resource.
 *
 * The filename, whether provided, cached, or retrieved from the database, is
 * only returned if the file exists.
Dries's avatar
Dries committed
124
 *
Dries's avatar
Dries committed
125
126
 * This function plays a key role in allowing Drupal's resources (modules
 * and themes) to be located in different places depending on a site's
127
 * configuration. For example, a module 'foo' may legally be located
Dries's avatar
Dries committed
128
129
 * in any of these three places:
 *
130
131
132
 * core/modules/foo/foo.info.yml
 * modules/foo/foo.info.yml
 * sites/example.com/modules/foo/foo.info.yml
Dries's avatar
Dries committed
133
134
135
136
 *
 * Calling drupal_get_filename('module', 'foo') will give you one of
 * the above, depending on where the module is located.
 *
Dries's avatar
Dries committed
137
 * @param $type
138
139
 *   The type of the item; one of 'core', 'profile', 'module', 'theme', or
 *   'theme_engine'.
Dries's avatar
Dries committed
140
 * @param $name
141
142
 *   The name of the item for which the filename is requested. Ignored for
 *   $type 'core'.
Dries's avatar
Dries committed
143
144
145
146
 * @param $filename
 *   The filename of the item if it is to be set explicitly rather
 *   than by consulting the database.
 *
147
 * @return string
148
 *   The filename of the requested item or NULL if the item is not found.
Dries's avatar
Dries committed
149
 */
Dries's avatar
Dries committed
150
function drupal_get_filename($type, $name, $filename = NULL) {
151
152
153
154
155
156
157
158
  // Type 'core' only exists to simplify application-level logic; it always maps
  // to the /core directory, whereas $name is ignored. It is only requested via
  // drupal_get_path(). /core/core.info.yml does not exist, but is required
  // since drupal_get_path() returns the dirname() of the returned pathname.
  if ($type === 'core') {
    return 'core/core.info.yml';
  }

159
  try {
160
    /** @var \Drupal\Core\Extension\ExtensionList $extension_list */
161
    $extension_list = \Drupal::service("extension.list.$type");
162
163
164
165
    if (isset($filename)) {
      // Manually add the info file path of an extension.
      $extension_list->setPathname($name, $filename);
    }
166
    return $extension_list->getPathname($name);
Dries's avatar
Dries committed
167
  }
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
  catch (ServiceNotFoundException $e) {
    // Catch the exception. This will result in triggering an error.
    // If the service is unknown, create a user-level error message.
    trigger_error(
      sprintf('Unknown type specified: "%s". Must be one of: "core", "profile", "module", "theme", or "theme_engine".', $type),
      E_USER_WARNING
    );
  }
  catch (\InvalidArgumentException $e) {
    // Catch the exception. This will result in triggering an error.
    // If the filename is still unknown, create a user-level error message.
    trigger_error(
      sprintf('The following %s is missing from the file system: %s', $type, $name),
      E_USER_WARNING
    );
183
  }
Dries's avatar
Dries committed
184
185
}

186
187
188
189
190
191
192
193
194
195
/**
 * Returns the path to a system item (module, theme, etc.).
 *
 * @param $type
 *   The type of the item; one of 'core', 'profile', 'module', 'theme', or
 *   'theme_engine'.
 * @param $name
 *   The name of the item for which the path is requested. Ignored for
 *   $type 'core'.
 *
196
 * @return string
197
198
199
200
201
202
 *   The path to the requested item or an empty string if the item is not found.
 */
function drupal_get_path($type, $name) {
  return dirname(drupal_get_filename($type, $name));
}

203
/**
204
 * Translates a string to the current language or to a given language.
205
 *
206
 * In order for strings to be localized, make them available in one of the ways
207
208
209
210
 * supported by the @link i18n Localization API. @endlink When possible, use
 * the \Drupal\Core\StringTranslation\StringTranslationTrait $this->t().
 * Otherwise create a new \Drupal\Core\StringTranslation\TranslatableMarkup
 * object directly.
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
 *
 * See \Drupal\Core\StringTranslation\TranslatableMarkup::__construct() for
 * important security information and usage guidelines.
 *
 * @param string $string
 *   A string containing the English text to translate.
 * @param array $args
 *   (optional) An associative array of replacements to make after translation.
 *   Based on the first character of the key, the value is escaped and/or
 *   themed. See
 *   \Drupal\Component\Render\FormattableMarkup::placeholderFormat() for
 *   details.
 * @param array $options
 *   (optional) An associative array of additional options, with the following
 *   elements:
 *   - 'langcode' (defaults to the current language): A language code, to
227
228
 *     translate to a language other than what is used to display the page.
 *   - 'context' (defaults to the empty context): The context the source string
229
230
 *     belongs to. See the @link i18n Internationalization topic @endlink for
 *     more information about string contexts.
231
 *
232
 * @return \Drupal\Core\StringTranslation\TranslatableMarkup
233
234
235
236
237
 *   An object that, when cast to a string, returns the translated string.
 *
 * @see \Drupal\Component\Render\FormattableMarkup::placeholderFormat()
 * @see \Drupal\Core\StringTranslation\StringTranslationTrait::t()
 * @see \Drupal\Core\StringTranslation\TranslatableMarkup::__construct()
238
239
 *
 * @ingroup sanitization
240
 */
241
function t($string, array $args = [], array $options = []) {
242
  return new TranslatableMarkup($string, $args, $options);
243
244
}

245
/**
246
 * Logs an exception.
247
 *
248
 * This is a wrapper logging function which automatically decodes an exception.
249
250
251
252
253
254
255
 *
 * @param $type
 *   The category to which this message belongs.
 * @param $exception
 *   The exception that is going to be logged.
 * @param $message
 *   The message to store in the log. If empty, a text that contains all useful
256
 *   information about the passed-in exception is used.
257
 * @param $variables
258
259
260
 *   Array of variables to replace in the message on display or
 *   NULL if message is already translated or not possible to
 *   translate.
261
262
263
264
265
 * @param $severity
 *   The severity of the message, as per RFC 3164.
 * @param $link
 *   A link to associate with the message.
 *
266
 * @see \Drupal\Core\Utility\Error::decodeException()
267
 */
268
function watchdog_exception($type, Exception $exception, $message = NULL, $variables = [], $severity = RfcLogLevel::ERROR, $link = NULL) {
269

270
271
  // Use a default value if $message is not set.
  if (empty($message)) {
272
    $message = '%type: @message in %function (line %line of %file).';
273
274
275
276
277
278
279
280
281
  }

  if ($link) {
    $variables['link'] = $link;
  }

  $variables += Error::decodeException($exception);

  \Drupal::logger($type)->log($severity, $message, $variables);
282
283
}

284
/**
285
 * Provides custom PHP error handling.
286
287
288
289
290
291
 *
 * @param $error_level
 *   The level of the error raised.
 * @param $message
 *   The error message.
 * @param $filename
292
 *   (optional) The filename that the error was raised in.
293
 * @param $line
294
 *   (optional) The line number the error was raised at.
295
 * @param $context
296
297
 *   (optional) An array that points to the active symbol table at the point the
 *   error occurred.
298
 */
299
function _drupal_error_handler($error_level, $message, $filename = NULL, $line = NULL, $context = NULL) {
300
  require_once __DIR__ . '/errors.inc';
301
302
303
304
  _drupal_error_handler_real($error_level, $message, $filename, $line, $context);
}

/**
305
 * Provides custom PHP exception handling.
306
307
308
309
310
 *
 * Uncaught exceptions are those not enclosed in a try/catch block. They are
 * always fatal: the execution of the script will stop as soon as the exception
 * handler exits.
 *
311
 * @param \Exception|\Throwable $exception
312
313
314
 *   The exception object that was thrown.
 */
function _drupal_exception_handler($exception) {
315
  require_once __DIR__ . '/errors.inc';
316
317
318

  try {
    // Log the message to the watchdog and return an error page to the user.
319
    _drupal_log_error(Error::decodeException($exception), TRUE);
320
  }
321
  // Catch \Throwable, which covers both Error and Exception throwables.
322
323
  catch (\Throwable $error) {
    _drupal_exception_handler_additional($exception, $error);
324
325
326
327
328
329
  }
}

/**
 * Displays any additional errors caught while handling an exception.
 *
330
 * @param \Exception|\Throwable $exception
331
 *   The first exception object that was thrown.
332
 * @param \Exception|\Throwable $exception2
333
334
335
336
337
338
339
340
341
342
 *   The second exception object that was thrown.
 */
function _drupal_exception_handler_additional($exception, $exception2) {
  // Another uncaught exception was thrown while handling the first one.
  // If we are displaying errors, then do so with no possibility of a further
  // uncaught exception being thrown.
  if (error_displayable()) {
    print '<h1>Additional uncaught exception thrown while handling exception.</h1>';
    print '<h2>Original</h2><p>' . Error::renderExceptionSafe($exception) . '</p>';
    print '<h2>Additional</h2><p>' . Error::renderExceptionSafe($exception2) . '</p><hr />';
343
  }
344
345
}

346
/**
347
 * Returns the test prefix if this is an internal request from SimpleTest.
348
 *
349
 * @param string $new_prefix
350
 *   Internal use only. A new prefix to be stored.
351
 *
352
 * @return string|false
353
354
355
 *   Either the simpletest prefix (the string "simpletest" followed by any
 *   number of digits) or FALSE if the user agent does not contain a valid
 *   HMAC and timestamp.
356
 */
357
function drupal_valid_test_ua($new_prefix = NULL) {
358
359
  static $test_prefix;

360
361
362
  if (isset($new_prefix)) {
    $test_prefix = $new_prefix;
  }
363
364
365
  if (isset($test_prefix)) {
    return $test_prefix;
  }
366
367
368
  // Unless the below User-Agent and HMAC validation succeeds, we are not in
  // a test environment.
  $test_prefix = FALSE;
369

370
371
372
373
374
  // A valid Simpletest request will contain a hashed and salted authentication
  // code. Check if this code is present in a cookie or custom user agent
  // string.
  $http_user_agent = isset($_SERVER['HTTP_USER_AGENT']) ? $_SERVER['HTTP_USER_AGENT'] : NULL;
  $user_agent = isset($_COOKIE['SIMPLETEST_USER_AGENT']) ? $_COOKIE['SIMPLETEST_USER_AGENT'] : $http_user_agent;
375
  if (isset($user_agent) && preg_match("/^simple(\w+\d+):(.+):(.+):(.+)$/", $user_agent, $matches)) {
376
    list(, $prefix, $time, $salt, $hmac) = $matches;
377
    $check_string = $prefix . ':' . $time . ':' . $salt;
378
379
380
381
382
    // Read the hash salt prepared by drupal_generate_test_ua().
    // This function is called before settings.php is read and Drupal's error
    // handlers are set up. While Drupal's error handling may be properly
    // configured on production sites, the server's PHP error_reporting may not.
    // Ensure that no information leaks on production sites.
383
384
    $test_db = new TestDatabase($prefix);
    $key_file = DRUPAL_ROOT . '/' . $test_db->getTestSitePath() . '/.htkey';
385
386
387
388
389
390
391
    if (!is_readable($key_file)) {
      header($_SERVER['SERVER_PROTOCOL'] . ' 403 Forbidden');
      exit;
    }
    $private_key = file_get_contents($key_file);
    // The file properties add more entropy not easily accessible to others.
    $key = $private_key . filectime(__FILE__) . fileinode(__FILE__);
392
    $time_diff = REQUEST_TIME - $time;
393
    $test_hmac = Crypt::hmacBase64($check_string, $key);
394
    // Since we are making a local request a 600 second time window is allowed,
395
    // and the HMAC must match.
396
    if ($time_diff >= 0 && $time_diff <= 600 && hash_equals($test_hmac, $hmac)) {
397
398
      $test_prefix = $prefix;
    }
399
400
401
402
    else {
      header($_SERVER['SERVER_PROTOCOL'] . ' 403 Forbidden (SIMPLETEST_USER_AGENT invalid)');
      exit;
    }
403
  }
404
  return $test_prefix;
405
406
407
}

/**
408
 * Generates a user agent string with a HMAC and timestamp for simpletest.
409
410
 */
function drupal_generate_test_ua($prefix) {
411
412
413
414
  static $key, $last_prefix;

  if (!isset($key) || $last_prefix != $prefix) {
    $last_prefix = $prefix;
415
416
    $test_db = new TestDatabase($prefix);
    $key_file = DRUPAL_ROOT . '/' . $test_db->getTestSitePath() . '/.htkey';
417
418
419
420
    // When issuing an outbound HTTP client request from within an inbound test
    // request, then the outbound request has to use the same User-Agent header
    // as the inbound request. A newly generated private key for the same test
    // prefix would invalidate all subsequent inbound requests.
421
    // @see \Drupal\Core\Test\HttpClientMiddleware\TestHttpClientMiddleware
422
423
424
425
426
427
428
429
430
431
    if (DRUPAL_TEST_IN_CHILD_SITE && $parent_prefix = drupal_valid_test_ua()) {
      if ($parent_prefix != $prefix) {
        throw new \RuntimeException("Malformed User-Agent: Expected '$parent_prefix' but got '$prefix'.");
      }
      // If the file is not readable, a PHP warning is expected in this case.
      $private_key = file_get_contents($key_file);
    }
    else {
      // Generate and save a new hash salt for a test run.
      // Consumed by drupal_valid_test_ua() before settings.php is loaded.
432
      $private_key = Crypt::randomBytesBase64(55);
433
434
435
436
      file_put_contents($key_file, $private_key);
    }
    // The file properties add more entropy not easily accessible to others.
    $key = $private_key . filectime(__FILE__) . fileinode(__FILE__);
437
  }
438
439
  // Generate a moderately secure HMAC based on the database credentials.
  $salt = uniqid('', TRUE);
440
  $check_string = $prefix . ':' . time() . ':' . $salt;
441
  return 'simple' . $check_string . ':' . Crypt::hmacBase64($check_string, $key);
442
443
}

444
/**
445
446
447
 * Enables use of the theme system without requiring database access.
 *
 * Loads and initializes the theme system for site installs, updates and when
448
 * the site is in maintenance mode. This also applies when the database fails.
449
450
 *
 * @see _drupal_maintenance_theme()
451
452
 */
function drupal_maintenance_theme() {
453
  require_once __DIR__ . '/theme.maintenance.inc';
454
  _drupal_maintenance_theme();
455
}
456

457
/**
458
 * Provides central static variable storage.
459
 *
460
461
462
463
464
465
466
467
468
 * All functions requiring a static variable to persist or cache data within
 * a single page request are encouraged to use this function unless it is
 * absolutely certain that the static variable will not need to be reset during
 * the page request. By centralizing static variable storage through this
 * function, other functions can rely on a consistent API for resetting any
 * other function's static variables.
 *
 * Example:
 * @code
469
470
471
 * function example_list($field = 'default') {
 *   $examples = &drupal_static(__FUNCTION__);
 *   if (!isset($examples)) {
472
473
 *     // If this function is being called for the first time after a reset,
 *     // query the database and execute any other code needed to retrieve
474
 *     // information.
475
476
 *     ...
 *   }
477
 *   if (!isset($examples[$field])) {
478
479
 *     // If this function is being called for the first time for a particular
 *     // index field, then execute code needed to index the information already
480
 *     // available in $examples by the desired field.
481
482
483
484
485
 *     ...
 *   }
 *   // Subsequent invocations of this function for a particular index field
 *   // skip the above two code blocks and quickly return the already indexed
 *   // information.
486
 *   return $examples[$field];
487
 * }
488
489
490
491
 * function examples_admin_overview() {
 *   // When building the content for the overview page, make sure to get
 *   // completely fresh information.
 *   drupal_static_reset('example_list');
492
493
494
495
496
497
498
499
500
501
502
503
504
505
 *   ...
 * }
 * @endcode
 *
 * In a few cases, a function can have certainty that there is no legitimate
 * use-case for resetting that function's static variable. This is rare,
 * because when writing a function, it's hard to forecast all the situations in
 * which it will be used. A guideline is that if a function's static variable
 * does not depend on any information outside of the function that might change
 * during a single page request, then it's ok to use the "static" keyword
 * instead of the drupal_static() function.
 *
 * Example:
 * @code
506
507
508
509
 * function mymodule_log_stream_handle($new_handle = NULL) {
 *   static $handle;
 *   if (isset($new_handle)) {
 *     $handle = $new_handle;
510
 *   }
511
 *   return $handle;
512
513
514
515
516
517
518
 * }
 * @endcode
 *
 * In a few cases, a function needs a resettable static variable, but the
 * function is called many times (100+) during a single page request, so
 * every microsecond of execution time that can be removed from the function
 * counts. These functions can use a more cumbersome, but faster variant of
519
520
521
522
523
524
525
526
527
528
529
530
531
 * calling drupal_static(). It works by storing the reference returned by
 * drupal_static() in the calling function's own static variable, thereby
 * removing the need to call drupal_static() for each iteration of the function.
 * Conceptually, it replaces:
 * @code
 * $foo = &drupal_static(__FUNCTION__);
 * @endcode
 * with:
 * @code
 * // Unfortunately, this does not work.
 * static $foo = &drupal_static(__FUNCTION__);
 * @endcode
 * However, the above line of code does not work, because PHP only allows static
532
 * variables to be initialized by literal values, and does not allow static
533
 * variables to be assigned to references.
534
535
 * - http://php.net/manual/language.variables.scope.php#language.variables.scope.static
 * - http://php.net/manual/language.variables.scope.php#language.variables.scope.references
536
 * The example below shows the syntax needed to work around both limitations.
537
 * For benchmarks and more information, see https://www.drupal.org/node/619666.
538
539
540
 *
 * Example:
 * @code
541
 * function example_default_format_type() {
542
 *   // Use the advanced drupal_static() pattern, since this is called very often.
543
544
 *   static $drupal_static_fast;
 *   if (!isset($drupal_static_fast)) {
545
 *     $drupal_static_fast['format_type'] = &drupal_static(__FUNCTION__);
546
 *   }
547
 *   $format_type = &$drupal_static_fast['format_type'];
548
549
550
551
 *   ...
 * }
 * @endcode
 *
552
553
554
 * @param $name
 *   Globally unique name for the variable. For a function with only one static,
 *   variable, the function name (e.g. via the PHP magic __FUNCTION__ constant)
555
 *   is recommended. For a function with multiple static variables add a
556
557
558
559
 *   distinguishing suffix to the function name for each one.
 * @param $default_value
 *   Optional default value.
 * @param $reset
560
561
562
 *   TRUE to reset one or all variables(s). This parameter is only used
 *   internally and should not be passed in; use drupal_static_reset() instead.
 *   (This function's return value should not be used when TRUE is passed in.)
563
 *
564
 * @return mixed
565
 *   Returns a variable by reference.
566
567
 *
 * @see drupal_static_reset()
568
569
 */
function &drupal_static($name, $default_value = NULL, $reset = FALSE) {
570
  static $data = [], $default = [];
571
572
573
574
575
  // First check if dealing with a previously defined static variable.
  if (isset($data[$name]) || array_key_exists($name, $data)) {
    // Non-NULL $name and both $data[$name] and $default[$name] statics exist.
    if ($reset) {
      // Reset pre-existing static variable to its default value.
576
      $data[$name] = $default[$name];
577
    }
578
579
580
581
582
    return $data[$name];
  }
  // Neither $data[$name] nor $default[$name] static variables exist.
  if (isset($name)) {
    if ($reset) {
583
584
585
      // Reset was called before a default is set and yet a variable must be
      // returned.
      return $data;
586
    }
587
    // First call with new non-NULL $name. Initialize a new static variable.
588
    $default[$name] = $data[$name] = $default_value;
589
590
591
592
593
594
595
    return $data[$name];
  }
  // Reset all: ($name == NULL). This needs to be done one at a time so that
  // references returned by earlier invocations of drupal_static() also get
  // reset.
  foreach ($default as $name => $value) {
    $data[$name] = $value;
596
  }
597
598
599
  // As the function returns a reference, the return should always be a
  // variable.
  return $data;
600
601
602
}

/**
603
 * Resets one or all centrally stored static variable(s).
604
605
606
 *
 * @param $name
 *   Name of the static variable to reset. Omit to reset all variables.
607
608
 *   Resetting all variables should only be used, for example, for running
 *   unit tests with a clean environment.
609
610
611
612
 */
function drupal_static_reset($name = NULL) {
  drupal_static($name, NULL, TRUE);
}
613

614
/**
615
 * Registers a function for execution on shutdown.
616
 *
617
618
 * Wrapper for register_shutdown_function() that catches thrown exceptions to
 * avoid "Exception thrown without a stack frame in Unknown".
619
 *
620
 * @param callable $callback
621
 *   The shutdown function to register.
622
623
624
 * @param ...
 *   Additional arguments to pass to the shutdown function.
 *
625
 * @return array
626
627
628
 *   Array of shutdown functions to be executed.
 *
 * @see register_shutdown_function()
629
 * @ingroup php_wrappers
630
 */
631
632
633
function &drupal_register_shutdown_function($callback = NULL) {
  // We cannot use drupal_static() here because the static cache is reset during
  // batch processing, which breaks batch handling.
634
  static $callbacks = [];
635
636
637
638
639
640
641

  if (isset($callback)) {
    // Only register the internal shutdown function once.
    if (empty($callbacks)) {
      register_shutdown_function('_drupal_shutdown_function');
    }
    $args = func_get_args();
642
643
    // Remove $callback from the arguments.
    unset($args[0]);
644
    // Save callback and arguments
645
    $callbacks[] = ['callback' => $callback, 'arguments' => $args];
646
647
648
649
650
  }
  return $callbacks;
}

/**
651
 * Executes registered shutdown functions.
652
653
654
655
 */
function _drupal_shutdown_function() {
  $callbacks = &drupal_register_shutdown_function();

656
657
658
659
  // Set the CWD to DRUPAL_ROOT as it is not guaranteed to be the same as it
  // was in the normal context of execution.
  chdir(DRUPAL_ROOT);

660
  try {
661
662
663
664
    reset($callbacks);
    // Do not use foreach() here because it is possible that the callback will
    // add to the $callbacks array via drupal_register_shutdown_function().
    while ($callback = current($callbacks)) {
665
      call_user_func_array($callback['callback'], $callback['arguments']);
666
      next($callbacks);
667
668
    }
  }
669
  // Catch \Throwable, which covers both Error and Exception throwables.
670
671
  catch (\Throwable $error) {
    _drupal_shutdown_function_handle_exception($error);
672
673
674
675
676
677
  }
}

/**
 * Displays and logs any errors that may happen during shutdown.
 *
678
 * @param \Exception|\Throwable $exception
679
680
681
682
683
684
685
686
687
688
689
690
691
692
 *   The exception object that was thrown.
 *
 * @see _drupal_shutdown_function()
 */
function _drupal_shutdown_function_handle_exception($exception) {
  // If using PHP-FPM then fastcgi_finish_request() will have been fired
  // preventing further output to the browser.
  if (!function_exists('fastcgi_finish_request')) {
    // If we are displaying errors, then do so with no possibility of a
    // further uncaught exception being thrown.
    require_once __DIR__ . '/errors.inc';
    if (error_displayable()) {
      print '<h1>Uncaught exception thrown in shutdown function.</h1>';
      print '<p>' . Error::renderExceptionSafe($exception) . '</p><hr />';
693
    }
694
  }
695
  error_log($exception);
696
}