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

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

8
use Drupal\Component\Utility\Crypt;
9
use Drupal\Component\Utility\Html;
10
use Drupal\Component\Render\FormattableMarkup;
11
use Drupal\Component\Utility\Unicode;
12
use Drupal\Core\Config\BootstrapConfigStorageFactory;
13
use Drupal\Core\Extension\Exception\UnknownExtensionException;
14
use Drupal\Core\Logger\RfcLogLevel;
15
use Drupal\Core\Test\TestDatabase;
16
use Drupal\Core\Session\AccountInterface;
17
use Drupal\Core\Utility\Error;
18
use Drupal\Core\StringTranslation\TranslatableMarkup;
19

20 21
/**
 * Minimum supported version of PHP.
22 23
 *
 * Drupal cannot be installed on versions of PHP older than this version.
24 25 26
 *
 * @todo Move this to an appropriate autoloadable class. See
 *   https://www.drupal.org/project/drupal/issues/2908079
27
 */
28
const DRUPAL_MINIMUM_PHP = '5.5.9';
29

30 31 32 33 34 35
/**
 * 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.
36 37 38
 *
 * @todo Move this to an appropriate autoloadable class. See
 *   https://www.drupal.org/project/drupal/issues/2908079
39 40 41
 */
const DRUPAL_RECOMMENDED_PHP = '7.1';

42 43
/**
 * Minimum recommended value of PHP memory_limit.
44
 *
45 46 47
 * 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.
48 49 50
 *
 * @todo Move this to an appropriate autoloadable class. See
 *   https://www.drupal.org/project/drupal/issues/2908079
51
 */
52
const DRUPAL_MINIMUM_PHP_MEMORY_LIMIT = '64M';
53

54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73
/**
 * 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';

74 75
/**
 * Role ID for anonymous users; should match what's in the "role" table.
76 77 78 79
 *
 * @deprecated in Drupal 8.0.0, will be removed before Drupal 9.0.0.
 *   Use Drupal\Core\Session\AccountInterface::ANONYMOUS_ROLE or
 *   \Drupal\user\RoleInterface::ANONYMOUS_ID instead.
80 81
 *
 * @see https://www.drupal.org/node/1619504
82
 */
83
const DRUPAL_ANONYMOUS_RID = AccountInterface::ANONYMOUS_ROLE;
84 85 86

/**
 * Role ID for authenticated users; should match what's in the "role" table.
87 88 89 90
 *
 * @deprecated in Drupal 8.0.0, will be removed before Drupal 9.0.0.
 *   Use Drupal\Core\Session\AccountInterface::AUTHENTICATED_ROLE or
 *   \Drupal\user\RoleInterface::AUTHENTICATED_ID instead.
91 92
 *
 * @see https://www.drupal.org/node/1619504
93
 */
94
const DRUPAL_AUTHENTICATED_RID = AccountInterface::AUTHENTICATED_ROLE;
95

96 97 98 99 100
/**
 * The maximum number of characters in a module or theme name.
 */
const DRUPAL_EXTENSION_NAME_MAX_LENGTH = 50;

101
/**
102
 * Time of the current request in seconds elapsed since the Unix Epoch.
103
 *
104 105 106 107 108 109
 * 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
110 111 112
 *
 * @deprecated in Drupal 8.3.0, will be removed before Drupal 9.0.0.
 *   Use \Drupal::time()->getRequestTime();
113 114
 *
 * @see https://www.drupal.org/node/2785211
115
 */
116
define('REQUEST_TIME', (int) $_SERVER['REQUEST_TIME']);
117

118 119 120
/**
 * Regular expression to match PHP function names.
 *
121
 * @see http://php.net/manual/language.functions.php
122
 */
123
const DRUPAL_PHP_FUNCTION_PATTERN = '[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*';
124

125 126 127
/**
 * $config_directories key for active directory.
 *
128
 * @see config_get_config_directory()
129 130 131
 *
 * @deprecated in Drupal 8.0.x and will be removed before 9.0.0. Drupal core no
 *   longer creates an active directory.
132 133
 *
 * @see https://www.drupal.org/node/2501187
134 135 136
 */
const CONFIG_ACTIVE_DIRECTORY = 'active';

137 138 139 140 141 142 143
/**
 * $config_directories key for sync directory.
 *
 * @see config_get_config_directory()
 */
const CONFIG_SYNC_DIRECTORY = 'sync';

144 145 146
/**
 * $config_directories key for staging directory.
 *
147
 * @see config_get_config_directory()
148 149 150 151
 * @see CONFIG_SYNC_DIRECTORY
 *
 * @deprecated in Drupal 8.0.x and will be removed before 9.0.0. The staging
 *   directory was renamed to sync.
152 153
 *
 * @see https://www.drupal.org/node/2574957
154 155 156
 */
const CONFIG_STAGING_DIRECTORY = 'staging';

157 158 159 160 161 162 163
/**
 * Defines the root directory of the Drupal installation.
 *
 * This strips two levels of directories off the current directory.
 */
define('DRUPAL_ROOT', dirname(dirname(__DIR__)));

164
/**
165 166
 * Returns the path of a configuration directory.
 *
167 168 169
 * Configuration directories are configured using $config_directories in
 * settings.php.
 *
170
 * @param string $type
171
 *   The type of config directory to return. Drupal core provides the
172
 *   CONFIG_SYNC_DIRECTORY constant to access the sync directory.
173 174 175
 *
 * @return string
 *   The configuration directory path.
176 177
 *
 * @throws \Exception
178
 */
179
function config_get_config_directory($type) {
180
  global $config_directories;
181

182 183 184 185 186
  // @todo Remove fallback in Drupal 9. https://www.drupal.org/node/2574943
  if ($type == CONFIG_SYNC_DIRECTORY && !isset($config_directories[CONFIG_SYNC_DIRECTORY]) && isset($config_directories[CONFIG_STAGING_DIRECTORY])) {
    $type = CONFIG_STAGING_DIRECTORY;
  }

187
  if (!empty($config_directories[$type])) {
188
    return $config_directories[$type];
189
  }
190
  // @todo https://www.drupal.org/node/2696103 Throw a more specific exception.
191
  throw new \Exception("The configuration directory type '$type' does not exist");
192 193
}

Dries's avatar
Dries committed
194
/**
195 196 197 198
 * 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
199
 *
Dries's avatar
Dries committed
200 201
 * 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
202
 * configuration. For example, a module 'foo' may legally be located
Dries's avatar
Dries committed
203 204
 * in any of these three places:
 *
205 206 207
 * core/modules/foo/foo.info.yml
 * modules/foo/foo.info.yml
 * sites/example.com/modules/foo/foo.info.yml
Dries's avatar
Dries committed
208 209 210 211
 *
 * 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
212
 * @param $type
213 214
 *   The type of the item; one of 'core', 'profile', 'module', 'theme', or
 *   'theme_engine'.
Dries's avatar
Dries committed
215
 * @param $name
216 217
 *   The name of the item for which the filename is requested. Ignored for
 *   $type 'core'.
Dries's avatar
Dries committed
218 219 220 221
 * @param $filename
 *   The filename of the item if it is to be set explicitly rather
 *   than by consulting the database.
 *
222
 * @return string
223
 *   The filename of the requested item or NULL if the item is not found.
Dries's avatar
Dries committed
224
 */
Dries's avatar
Dries committed
225
function drupal_get_filename($type, $name, $filename = NULL) {
226 227
  // The location of files will not change during the request, so do not use
  // drupal_static().
228
  static $files = [];
Dries's avatar
Dries committed
229

230 231 232 233 234 235 236 237
  // 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';
  }

238 239 240 241 242 243 244 245 246 247 248
  if ($type === 'module' || $type === 'profile') {
    $service_id = 'extension.list.' . $type;
    /** @var \Drupal\Core\Extension\ExtensionList $extension_list */
    $extension_list = \Drupal::service($service_id);
    if (isset($filename)) {
      // Manually add the info file path of an extension.
      $extension_list->setPathname($name, $filename);
    }
    try {
      return $extension_list->getPathname($name);
    }
249
    catch (UnknownExtensionException $e) {
250 251
      // Catch the exception. This will result in triggering an error.
    }
Dries's avatar
Dries committed
252
  }
253
  else {
Dries's avatar
Dries committed
254

255 256
    if (!isset($files[$type])) {
      $files[$type] = [];
257
    }
258 259 260

    if (isset($filename)) {
      $files[$type][$name] = $filename;
261
    }
262 263 264 265 266 267 268
    elseif (!isset($files[$type][$name])) {
      // If still unknown, retrieve the file list prepared in state by
      // \Drupal\Core\Extension\ExtensionList() and
      // \Drupal\Core\Extension\ThemeHandlerInterface::rebuildThemeData().
      if (!isset($files[$type][$name]) && \Drupal::hasService('state')) {
        $files[$type] += \Drupal::state()->get('system.' . $type . '.files', []);
      }
Dries's avatar
Dries committed
269 270
    }

271 272 273
    if (isset($files[$type][$name])) {
      return $files[$type][$name];
    }
274
  }
275
  // If the filename is still unknown, create a user-level error message.
276
  trigger_error(new FormattableMarkup('The following @type is missing from the file system: @name', ['@type' => $type, '@name' => $name]), E_USER_WARNING);
Dries's avatar
Dries committed
277 278
}

279 280 281 282 283 284 285 286 287 288
/**
 * 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'.
 *
289
 * @return string
290 291 292 293 294 295
 *   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));
}

296
/**
297
 * Translates a string to the current language or to a given language.
298
 *
299
 * In order for strings to be localized, make them available in one of the ways
300 301 302 303
 * 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.
304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319
 *
 * 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
320 321
 *     translate to a language other than what is used to display the page.
 *   - 'context' (defaults to the empty context): The context the source string
322 323
 *     belongs to. See the @link i18n Internationalization topic @endlink for
 *     more information about string contexts.
324
 *
325
 * @return \Drupal\Core\StringTranslation\TranslatableMarkup
326 327 328 329 330
 *   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()
331 332
 *
 * @ingroup sanitization
333
 */
334
function t($string, array $args = [], array $options = []) {
335
  return new TranslatableMarkup($string, $args, $options);
336 337 338
}

/**
339 340
 * Formats a string for HTML display by replacing variable placeholders.
 *
341 342
 * @see \Drupal\Component\Render\FormattableMarkup::placeholderFormat()
 * @see \Drupal\Component\Render\FormattableMarkup
343 344
 * @see t()
 * @ingroup sanitization
345 346
 *
 * @deprecated in Drupal 8.0.0, will be removed before Drupal 9.0.0.
347
 *   Use \Drupal\Component\Render\FormattableMarkup.
348 349
 *
 * @see https://www.drupal.org/node/2302363
350
 */
351
function format_string($string, array $args) {
352
  return new FormattableMarkup($string, $args);
353 354
}

Gábor Hojtsy's avatar
Gábor Hojtsy committed
355 356 357 358 359 360 361 362 363 364 365 366 367 368 369
/**
 * Checks whether a string is valid UTF-8.
 *
 * All functions designed to filter input should use drupal_validate_utf8
 * to ensure they operate on valid UTF-8 strings to prevent bypass of the
 * filter.
 *
 * When text containing an invalid UTF-8 lead byte (0xC0 - 0xFF) is presented
 * as UTF-8 to Internet Explorer 6, the program may misinterpret subsequent
 * bytes. When these subsequent bytes are HTML control characters such as
 * quotes or angle brackets, parts of the text that were deemed safe by filters
 * end up in locations that are potentially unsafe; An onerror attribute that
 * is outside of a tag, and thus deemed safe by a filter, can be interpreted
 * by the browser as if it were inside the tag.
 *
370 371
 * The function does not return FALSE for strings containing character codes
 * above U+10FFFF, even though these are prohibited by RFC 3629.
Gábor Hojtsy's avatar
Gábor Hojtsy committed
372 373 374
 *
 * @param $text
 *   The text to check.
375
 *
376
 * @return bool
Gábor Hojtsy's avatar
Gábor Hojtsy committed
377
 *   TRUE if the text is valid UTF-8, FALSE if not.
378 379
 *
 * @see \Drupal\Component\Utility\Unicode::validateUtf8()
380 381 382
 *
 * @deprecated in Drupal 8.0.0, will be removed before Drupal 9.0.0.
 *   Use \Drupal\Component\Utility\Unicode::validateUtf8().
383 384
 *
 * @see https://www.drupal.org/node/1992584
Gábor Hojtsy's avatar
Gábor Hojtsy committed
385 386
 */
function drupal_validate_utf8($text) {
387
  return Unicode::validateUtf8($text);
Dries's avatar
Dries committed
388 389
}

390
/**
391
 * Logs an exception.
392
 *
393
 * This is a wrapper logging function which automatically decodes an exception.
394 395 396 397 398 399 400
 *
 * @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
401
 *   information about the passed-in exception is used.
402
 * @param $variables
403 404 405
 *   Array of variables to replace in the message on display or
 *   NULL if message is already translated or not possible to
 *   translate.
406 407 408 409 410
 * @param $severity
 *   The severity of the message, as per RFC 3164.
 * @param $link
 *   A link to associate with the message.
 *
411
 * @see \Drupal\Core\Utility\Error::decodeException()
412
 */
413
function watchdog_exception($type, Exception $exception, $message = NULL, $variables = [], $severity = RfcLogLevel::ERROR, $link = NULL) {
414

415 416
  // Use a default value if $message is not set.
  if (empty($message)) {
417
    $message = '%type: @message in %function (line %line of %file).';
418 419 420 421 422 423 424 425 426
  }

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

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

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

429
/**
430
 * Sets a message to display to the user.
431
 *
432 433
 * Messages are stored in a session variable and displayed in the page template
 * via the $messages theme variable.
434
 *
435 436 437 438 439
 * Example usage:
 * @code
 * drupal_set_message(t('An error occurred and processing did not complete.'), 'error');
 * @endcode
 *
440
 * @param string|\Drupal\Component\Render\MarkupInterface $message
441 442 443 444 445 446
 *   (optional) The translated message to be displayed to the user. For
 *   consistency with other messages, it should begin with a capital letter and
 *   end with a period.
 * @param string $type
 *   (optional) The message's type. Defaults to 'status'. These values are
 *   supported:
447
 *   - 'status'
448
 *   - 'warning'
449
 *   - 'error'
450 451
 * @param bool $repeat
 *   (optional) If this is FALSE and the message is already set, then the
452
 *   message won't be repeated. Defaults to FALSE.
453 454 455
 *
 * @return array|null
 *   A multidimensional array with keys corresponding to the set message types.
456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476
 *   The indexed array values of each contain the set messages for that type,
 *   and each message is an associative array with the following format:
 *   - safe: Boolean indicating whether the message string has been marked as
 *     safe. Non-safe strings will be escaped automatically.
 *   - message: The message string.
 *   So, the following is an example of the full return array structure:
 *   @code
 *     array(
 *       'status' => array(
 *         array(
 *           'safe' => TRUE,
 *           'message' => 'A <em>safe</em> markup string.',
 *         ),
 *         array(
 *           'safe' => FALSE,
 *           'message' => "$arbitrary_user_input to escape.",
 *         ),
 *       ),
 *     );
 *   @endcode
 *   If there are no messages set, the function returns NULL.
477 478
 *
 * @see drupal_get_messages()
479
 * @see status-messages.html.twig
480 481 482 483
 * @see https://www.drupal.org/node/2774931
 *
 * @deprecated in Drupal 8.5.0 and will be removed before Drupal 9.0.0.
 *   Use \Drupal\Core\Messenger\MessengerInterface::addMessage() instead.
484
 */
485
function drupal_set_message($message = NULL, $type = 'status', $repeat = FALSE) {
486 487 488 489 490
  @trigger_error('drupal_set_message() is deprecated in Drupal 8.5.0 and will be removed before Drupal 9.0.0. Use \Drupal\Core\Messenger\MessengerInterface::addMessage() instead. See https://www.drupal.org/node/2774931', E_USER_DEPRECATED);
  $messenger = \Drupal::messenger();
  if (isset($message)) {
    $messenger->addMessage($message, $type, $repeat);
  }
491
  return $messenger->all();
492 493
}

494
/**
495
 * Returns all messages that have been set with drupal_set_message().
496
 *
497 498 499 500 501 502 503 504 505 506 507
 * @param string $type
 *   (optional) Limit the messages returned by type. Defaults to NULL, meaning
 *   all types. These values are supported:
 *   - NULL
 *   - 'status'
 *   - 'warning'
 *   - 'error'
 * @param bool $clear_queue
 *   (optional) If this is TRUE, the queue will be cleared of messages of the
 *   type specified in the $type parameter. Otherwise the queue will be left
 *   intact. Defaults to TRUE.
508
 *
509
 * @return array
510 511 512 513
 *   An associative, nested array of messages grouped by message type, with
 *   the top-level keys as the message type. The messages returned are
 *   limited to the type specified in the $type parameter, if any. If there
 *   are no messages of the specified type, an empty array is returned. See
514
 *   drupal_set_message() for the array structure of individual messages.
515 516
 *
 * @see drupal_set_message()
517
 * @see status-messages.html.twig
518 519 520 521 522
 * @see https://www.drupal.org/node/2774931
 *
 * @deprecated in Drupal 8.5.0 and will be removed before Drupal 9.0.0.
 *   Use \Drupal\Core\Messenger\MessengerInterface::all() or
 *   \Drupal\Core\Messenger\MessengerInterface::messagesByType() instead.
523
 */
524
function drupal_get_messages($type = NULL, $clear_queue = TRUE) {
525 526 527
  @trigger_error('drupal_get_message() is deprecated in Drupal 8.5.0 and will be removed before Drupal 9.0.0. Use \Drupal\Core\Messenger\MessengerInterface::all() or \Drupal\Core\Messenger\MessengerInterface::messagesByType() instead. See https://www.drupal.org/node/2774931', E_USER_DEPRECATED);
  $messenger = \Drupal::messenger();
  if ($messages = $messenger->all()) {
528
    if ($type) {
529
      if ($clear_queue) {
530
        $messenger->deleteByType($type);
531
      }
532
      if (isset($messages[$type])) {
533
        return [$type => $messages[$type]];
534
      }
535 536
    }
    else {
537
      if ($clear_queue) {
538
        $messenger->deleteAll();
539
      }
540 541
      return $messages;
    }
542
  }
543
  return [];
544 545
}

546
/**
547
 * Returns the time zone of the current user.
548 549 550
 *
 * @return string
 *   The name of the current user's timezone or the name of the default timezone.
551 552
 */
function drupal_get_user_timezone() {
553
  $user = \Drupal::currentUser();
554
  $config = \Drupal::config('system.date');
555

556
  if ($user && $config->get('timezone.user.configurable') && $user->isAuthenticated() && $user->getTimezone()) {
557
    return $user->getTimezone();
558 559
  }
  else {
560 561
    // Ignore PHP strict notice if time zone has not yet been set in the php.ini
    // configuration.
562
    $config_data_default_timezone = $config->get('timezone.default');
563
    return !empty($config_data_default_timezone) ? $config_data_default_timezone : @date_default_timezone_get();
564 565 566
  }
}

567
/**
568
 * Provides custom PHP error handling.
569 570 571 572 573 574 575 576 577 578
 *
 * @param $error_level
 *   The level of the error raised.
 * @param $message
 *   The error message.
 * @param $filename
 *   The filename that the error was raised in.
 * @param $line
 *   The line number the error was raised at.
 * @param $context
579 580
 *   An array that points to the active symbol table at the point the error
 *   occurred.
581 582
 */
function _drupal_error_handler($error_level, $message, $filename, $line, $context) {
583
  require_once __DIR__ . '/errors.inc';
584 585 586 587
  _drupal_error_handler_real($error_level, $message, $filename, $line, $context);
}

/**
588
 * Provides custom PHP exception handling.
589 590 591 592 593
 *
 * 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.
 *
594
 * @param \Exception|\Throwable $exception
595 596 597
 *   The exception object that was thrown.
 */
function _drupal_exception_handler($exception) {
598
  require_once __DIR__ . '/errors.inc';
599 600 601

  try {
    // Log the message to the watchdog and return an error page to the user.
602
    _drupal_log_error(Error::decodeException($exception), TRUE);
603
  }
604 605 606 607
  // PHP 7 introduces Throwable, which covers both Error and
  // Exception throwables.
  catch (\Throwable $error) {
    _drupal_exception_handler_additional($exception, $error);
608
  }
609
  // In order to be compatible with PHP 5 we also catch regular Exceptions.
610
  catch (\Exception $exception2) {
611 612 613 614 615 616 617
    _drupal_exception_handler_additional($exception, $exception2);
  }
}

/**
 * Displays any additional errors caught while handling an exception.
 *
618
 * @param \Exception|\Throwable $exception
619
 *   The first exception object that was thrown.
620
 * @param \Exception|\Throwable $exception2
621 622 623 624 625 626 627 628 629 630
 *   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 />';
631
  }
632 633
}

634
/**
635
 * Returns the test prefix if this is an internal request from SimpleTest.
636
 *
637
 * @param string $new_prefix
638
 *   Internal use only. A new prefix to be stored.
639
 *
640
 * @return string|false
641 642 643
 *   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.
644
 */
645
function drupal_valid_test_ua($new_prefix = NULL) {
646 647
  static $test_prefix;

648 649 650
  if (isset($new_prefix)) {
    $test_prefix = $new_prefix;
  }
651 652 653
  if (isset($test_prefix)) {
    return $test_prefix;
  }
654 655 656
  // Unless the below User-Agent and HMAC validation succeeds, we are not in
  // a test environment.
  $test_prefix = FALSE;
657

658 659 660 661 662
  // 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;
663
  if (isset($user_agent) && preg_match("/^simple(\w+\d+):(.+):(.+):(.+)$/", $user_agent, $matches)) {
664
    list(, $prefix, $time, $salt, $hmac) = $matches;
665
    $check_string = $prefix . ':' . $time . ':' . $salt;
666 667 668 669 670
    // 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.
671 672
    $test_db = new TestDatabase($prefix);
    $key_file = DRUPAL_ROOT . '/' . $test_db->getTestSitePath() . '/.htkey';
673 674 675 676 677 678 679
    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__);
680
    $time_diff = REQUEST_TIME - $time;
681
    $test_hmac = Crypt::hmacBase64($check_string, $key);
682
    // Since we are making a local request a 600 second time window is allowed,
683
    // and the HMAC must match.
684
    if ($time_diff >= 0 && $time_diff <= 600 && $hmac === $test_hmac) {
685 686
      $test_prefix = $prefix;
    }
687 688 689 690
    else {
      header($_SERVER['SERVER_PROTOCOL'] . ' 403 Forbidden (SIMPLETEST_USER_AGENT invalid)');
      exit;
    }
691
  }
692
  return $test_prefix;
693 694 695
}

/**
696
 * Generates a user agent string with a HMAC and timestamp for simpletest.
697 698
 */
function drupal_generate_test_ua($prefix) {
699 700 701 702
  static $key, $last_prefix;

  if (!isset($key) || $last_prefix != $prefix) {
    $last_prefix = $prefix;
703 704
    $test_db = new TestDatabase($prefix);
    $key_file = DRUPAL_ROOT . '/' . $test_db->getTestSitePath() . '/.htkey';
705 706 707 708 709 710 711 712 713 714 715 716 717 718 719
    // 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.
    // @see \Drupal\Core\Http\Plugin\SimpletestHttpRequestSubscriber
    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.
720
      $private_key = Crypt::randomBytesBase64(55);
721 722 723 724
      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__);
725
  }
726 727
  // Generate a moderately secure HMAC based on the database credentials.
  $salt = uniqid('', TRUE);
728
  $check_string = $prefix . ':' . time() . ':' . $salt;
729
  return 'simple' . $check_string . ':' . Crypt::hmacBase64($check_string, $key);
730 731
}

732
/**
733 734 735
 * Enables use of the theme system without requiring database access.
 *
 * Loads and initializes the theme system for site installs, updates and when
736
 * the site is in maintenance mode. This also applies when the database fails.
737 738
 *
 * @see _drupal_maintenance_theme()
739 740
 */
function drupal_maintenance_theme() {
741
  require_once __DIR__ . '/theme.maintenance.inc';
742
  _drupal_maintenance_theme();
743
}
744

745
/**
746
 * Returns TRUE if a Drupal installation is currently being attempted.
747 748
 */
function drupal_installation_attempted() {
749 750 751 752 753 754
  // This cannot rely on the MAINTENANCE_MODE constant, since that would prevent
  // tests from using the non-interactive installer, in which case Drupal
  // only happens to be installed within the same request, but subsequently
  // executed code does not involve the installer at all.
  // @see install_drupal()
  return isset($GLOBALS['install_state']) && empty($GLOBALS['install_state']['installation_finished']);
755 756
}

757 758 759 760 761 762
/**
 * Gets the name of the currently active installation profile.
 *
 * When this function is called during Drupal's initial installation process,
 * the name of the profile that's about to be installed is stored in the global
 * installation state. At all other times, the "install_profile" setting will be
763
 * available in container as a parameter.
764
 *
765
 * @return string|null
766 767 768
 *   The name of the installation profile or NULL if no installation profile is
 *   currently active. This is the case for example during the first steps of
 *   the installer or during unit tests.
769 770 771 772 773 774 775 776
 *
 * @deprecated in Drupal 8.3.0, will be removed before Drupal 9.0.0.
 *   Use the install_profile container parameter or \Drupal::installProfile()
 *   instead. If you are accessing the value before it is written to
 *   configuration during the installer use the $install_state global. If you
 *   need to access the value before container is available you can use
 *   BootstrapConfigStorageFactory to load the value directly from
 *   configuration.
777 778
 *
 * @see https://www.drupal.org/node/2538996
779 780 781 782 783 784 785 786 787 788 789 790 791 792
 */
function drupal_get_profile() {
  global $install_state;

  if (drupal_installation_attempted()) {
    // If the profile has been selected return it.
    if (isset($install_state['parameters']['profile'])) {
      $profile = $install_state['parameters']['profile'];
    }
    else {
      $profile = NULL;
    }
  }
  else {
793 794 795 796 797 798
    if (\Drupal::hasContainer()) {
      $profile = \Drupal::installProfile();
    }
    else {
      $profile = BootstrapConfigStorageFactory::getDatabaseStorage()->read('core.extension')['profile'];
    }
799 800 801 802 803
  }

  return $profile;
}

804 805 806 807 808 809 810 811 812
/**
 * Registers an additional namespace.
 *
 * @param string $name
 *   The namespace component to register; e.g., 'node'.
 * @param string $path
 *   The relative path to the Drupal component in the filesystem.
 */
function drupal_classloader_register($name, $path) {
813
  $loader = \Drupal::service('class_loader');
814
  $loader->addPsr4('Drupal\\' . $name . '\\', \Drupal::root() . '/' . $path . '/src');
815 816
}

817
/**
818
 * Provides central static variable storage.
819
 *
820 821 822 823 824 825 826 827 828
 * 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
829 830 831
 * function example_list($field = 'default') {
 *   $examples = &drupal_static(__FUNCTION__);
 *   if (!isset($examples)) {
832 833
 *     // If this function is being called for the first time after a reset,
 *     // query the database and execute any other code needed to retrieve
834
 *     // information.
835 836
 *     ...
 *   }
837
 *   if (!isset($examples[$field])) {
838 839
 *     // If this function is being called for the first time for a particular
 *     // index field, then execute code needed to index the information already
840
 *     // available in $examples by the desired field.
841 842 843 844 845
 *     ...
 *   }
 *   // Subsequent invocations of this function for a particular index field
 *   // skip the above two code blocks and quickly return the already indexed
 *   // information.
846
 *   return $examples[$field];
847
 * }
848 849 850 851
 * function examples_admin_overview() {
 *   // When building the content for the overview page, make sure to get
 *   // completely fresh information.
 *   drupal_static_reset('example_list');
852 853 854 855 856 857 858 859 860 861 862 863 864 865
 *   ...
 * }
 * @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
866 867 868 869
 * function mymodule_log_stream_handle($new_handle = NULL) {
 *   static $handle;
 *   if (isset($new_handle)) {
 *     $handle = $new_handle;
870
 *   }
871
 *   return $handle;
872 873 874 875 876 877 878
 * }
 * @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
879 880 881 882 883 884 885 886 887 888 889 890 891
 * 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
892
 * variables to be initialized by literal values, and does not allow static
893
 * variables to be assigned to references.
894 895
 * - http://php.net/manual/language.variables.scope.php#language.variables.scope.static
 * - http://php.net/manual/language.variables.scope.php#language.variables.scope.references
896
 * The example below shows the syntax needed to work around both limitations.
897
 * For benchmarks and more information, see https://www.drupal.org/node/619666.
898 899 900
 *
 * Example:
 * @code
901
 * function example_default_format_type() {
902
 *   // Use the advanced drupal_static() pattern, since this is called very often.
903 904
 *   static $drupal_static_fast;
 *   if (!isset($drupal_static_fast)) {
905
 *     $drupal_static_fast['format_type'] = &drupal_static(__FUNCTION__);
906
 *   }
907
 *   $format_type = &$drupal_static_fast['format_type'];
908 909 910 911
 *   ...
 * }
 * @endcode
 *
912 913 914
 * @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)
915
 *   is recommended. For a function with multiple static variables add a
916 917 918 919
 *   distinguishing suffix to the function name for each one.
 * @param $default_value
 *   Optional default value.
 * @param $reset
920 921 922
 *   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.)
923
 *
924
 * @return array
925
 *   Returns a variable by reference.
926 927
 *
 * @see drupal_static_reset()
928 929
 */
function &drupal_static($name, $default_value = NULL, $reset = FALSE) {
930
  static $data = [], $default = [];
931 932 933 934 935
  // 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.
936
      $data[$name] = $default[$name];
937
    }
938 939 940 941 942
    return $data[$name];
  }
  // Neither $data[$name] nor $default[$name] static variables exist.
  if (isset($name)) {
    if ($reset) {
943 944 945
      // Reset was called before a default is set and yet a variable must be
      // returned.
      return $data;
946
    }
947
    // First call with new non-NULL $name. Initialize a new static variable.
948
    $default[$name] = $data[$name] = $default_value;
949 950 951 952 953 954 955
    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;
956
  }
957 958 959
  // As the function returns a reference, the return should always be a
  // variable.
  return $data;
960 961 962
}

/**
963
 * Resets one or all centrally stored static variable(s).
964 965 966
 *
 * @param $name
 *   Name of the static variable to reset. Omit to reset all variables.
967 968
 *   Resetting all variables should only be used, for example, for running
 *   unit tests with a clean environment.
969 970 971 972
 */
function drupal_static_reset($name = NULL) {
  drupal_static($name, NULL, TRUE);
}
973

974 975
/**
 * Formats text for emphasized display in a placeholder inside a sentence.
976
 *
977
 * @deprecated in Drupal 8.0.0, will be removed before Drupal 9.0.0. Use
978 979 980 981
 *   \Drupal\Component\Render\FormattableMarkup or Twig's "placeholder" filter
 *   instead. Note this method should not be used to simply emphasize a string
 *   and therefore has few valid use-cases. Note also, that this method does not
 *   mark the string as safe.
982
 *
983
 * @see https://www.drupal.org/node/2302363
984
 */
985
function drupal_placeholder($text) {
986
  return '<em class="placeholder">' . Html::escape($text) . '</em>';
987
}
988 989

/**
990
 * Registers a function for execution on shutdown.
991
 *
992 993
 * Wrapper for register_shutdown_function() that catches thrown exceptions to
 * avoid "Exception thrown without a stack frame in Unknown".
994
 *
995
 * @param callable $callback
996
 *   The shutdown function to register.
997 998 999
 * @param ...
 *   Additional arguments to pass to the shutdown function.
 *
1000
 * @return array
1001 1002 1003
 *   Array of shutdown functions to be executed.
 *
 * @see register_shutdown_function()
1004
 * @ingroup php_wrappers
1005
 */
1006 1007 1008
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.
1009
  static $callbacks = [];
1010 1011 1012 1013 1014 1015 1016

  if (isset($callback)) {
    // Only register the internal shutdown function once.
    if (empty($callbacks)) {
      register_shutdown_function('_drupal_shutdown_function');
    }
    $args = func_get_args();
1017 1018
    // Remove $callback from the arguments.
    unset($args[0]);
1019
    // Save callback and arguments
1020
    $callbacks[] = ['callback' => $callback, 'arguments' => $args];
1021 1022 1023 1024 1025
  }
  return $callbacks;
}

/**
1026
 * Executes registered shutdown functions.
1027 1028 1029 1030
 */
function _drupal_shutdown_function() {
  $callbacks = &drupal_register_shutdown_function();

1031 1032 1033 1034
  // 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);

1035
  try {
1036
    foreach ($callbacks as &$callback) {
1037 1038 1039
      call_user_func_array($callback['callback'], $callback['arguments']);
    }
  }
1040 1041 1042 1043
  // PHP 7 introduces Throwable, which covers both Error and
  // Exception throwables.
  catch (\Throwable $error) {
    _drupal_shutdown_function_handle_exception($error);
1044
  }
1045
  // In order to be compatible with PHP 5 we also catch regular Exceptions.
1046
  catch (\Exception $exception) {
1047 1048 1049 1050 1051 1052 1053
    _drupal_shutdown_function_handle_exception($exception);
  }
}

/**
 * Displays and logs any errors that may happen during shutdown.
 *
1054
 * @param \Exception|\Throwable $exception
1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068
 *   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 />';
1069
    }
1070
  }
1071
  error_log($exception);
1072
}