bootstrap.inc 35.1 KB
Newer Older
1
<?php
2 3 4 5
/**
 * @file
 * Functions that need to be loaded on every Drupal request.
 */
Dries's avatar
 
Dries committed
6

7
use Drupal\Component\Utility\Crypt;
8
use Drupal\Component\Utility\Html;
9
use Drupal\Component\Utility\SafeMarkup;
10
use Drupal\Component\Utility\Unicode;
11
use Drupal\Core\Logger\RfcLogLevel;
12
use Drupal\Core\Render\Markup;
13
use Drupal\Core\Session\AccountInterface;
14
use Drupal\Core\Site\Settings;
15
use Drupal\Core\Utility\Error;
16

17 18
/**
 * Minimum supported version of PHP.
19
 */
20
const DRUPAL_MINIMUM_PHP = '5.5.9';
21 22 23

/**
 * Minimum recommended value of PHP memory_limit.
24
 *
25 26 27
 * 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.
28
 */
29
const DRUPAL_MINIMUM_PHP_MEMORY_LIMIT = '64M';
30

31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50
/**
 * 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';

51 52
/**
 * Role ID for anonymous users; should match what's in the "role" table.
53 54 55 56
 *
 * @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.
57
 */
58
const DRUPAL_ANONYMOUS_RID = AccountInterface::ANONYMOUS_ROLE;
59 60 61

/**
 * Role ID for authenticated users; should match what's in the "role" table.
62 63 64 65
 *
 * @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.
66
 */
67
const DRUPAL_AUTHENTICATED_RID = AccountInterface::AUTHENTICATED_ROLE;
68

69 70 71 72 73
/**
 * The maximum number of characters in a module or theme name.
 */
const DRUPAL_EXTENSION_NAME_MAX_LENGTH = 50;

74
/**
75
 * Time of the current request in seconds elapsed since the Unix Epoch.
76
 *
77 78 79 80 81 82
 * 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
83
 */
84
define('REQUEST_TIME', (int) $_SERVER['REQUEST_TIME']);
85

86 87 88
/**
 * Regular expression to match PHP function names.
 *
89
 * @see http://php.net/manual/language.functions.php
90
 */
91
const DRUPAL_PHP_FUNCTION_PATTERN = '[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*';
92

93 94 95
/**
 * $config_directories key for active directory.
 *
96
 * @see config_get_config_directory()
97 98 99
 *
 * @deprecated in Drupal 8.0.x and will be removed before 9.0.0. Drupal core no
 *   longer creates an active directory.
100 101 102
 */
const CONFIG_ACTIVE_DIRECTORY = 'active';

103 104 105 106 107 108 109
/**
 * $config_directories key for sync directory.
 *
 * @see config_get_config_directory()
 */
const CONFIG_SYNC_DIRECTORY = 'sync';

110 111 112
/**
 * $config_directories key for staging directory.
 *
113
 * @see config_get_config_directory()
114 115 116 117
 * @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.
118 119 120
 */
const CONFIG_STAGING_DIRECTORY = 'staging';

121 122 123 124 125 126 127
/**
 * Defines the root directory of the Drupal installation.
 *
 * This strips two levels of directories off the current directory.
 */
define('DRUPAL_ROOT', dirname(dirname(__DIR__)));

128
/**
129 130
 * Returns the path of a configuration directory.
 *
131 132 133
 * Configuration directories are configured using $config_directories in
 * settings.php.
 *
134
 * @param string $type
135
 *   The type of config directory to return. Drupal core provides the
136
 *   CONFIG_SYNC_DIRECTORY constant to access the sync directory.
137 138 139
 *
 * @return string
 *   The configuration directory path.
140 141
 *
 * @throws \Exception
142
 */
143
function config_get_config_directory($type) {
144
  global $config_directories;
145

146 147 148 149 150
  // @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;
  }

151
  if (!empty($config_directories[$type])) {
152
    return $config_directories[$type];
153
  }
154
  throw new \Exception("The configuration directory type '$type' does not exist");
155 156
}

Dries's avatar
Dries committed
157
/**
158 159 160 161
 * 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
162
 *
Dries's avatar
Dries committed
163 164
 * 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
165
 * configuration. For example, a module 'foo' may legally be located
Dries's avatar
Dries committed
166 167
 * in any of these three places:
 *
168 169 170
 * core/modules/foo/foo.info.yml
 * modules/foo/foo.info.yml
 * sites/example.com/modules/foo/foo.info.yml
Dries's avatar
Dries committed
171 172 173 174
 *
 * 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
175
 * @param $type
176 177
 *   The type of the item; one of 'core', 'profile', 'module', 'theme', or
 *   'theme_engine'.
Dries's avatar
Dries committed
178
 * @param $name
179 180
 *   The name of the item for which the filename is requested. Ignored for
 *   $type 'core'.
Dries's avatar
Dries committed
181 182 183 184 185
 * @param $filename
 *   The filename of the item if it is to be set explicitly rather
 *   than by consulting the database.
 *
 * @return
186
 *   The filename of the requested item or NULL if the item is not found.
Dries's avatar
Dries committed
187
 */
Dries's avatar
Dries committed
188
function drupal_get_filename($type, $name, $filename = NULL) {
189 190
  // The location of files will not change during the request, so do not use
  // drupal_static().
191
  static $files = array();
Dries's avatar
Dries committed
192

193 194 195 196 197 198 199 200
  // 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';
  }

201 202
  // Profiles are converted into modules in system_rebuild_module_data().
  // @todo Remove false-exposure of profiles as modules.
203
  if ($type == 'profile') {
204
    $type = 'module';
205
  }
206
  if (!isset($files[$type])) {
Dries's avatar
Dries committed
207 208 209
    $files[$type] = array();
  }

210
  if (isset($filename)) {
Dries's avatar
Dries committed
211 212
    $files[$type][$name] = $filename;
  }
213 214 215 216 217 218
  elseif (!isset($files[$type][$name])) {
    // If the pathname of the requested extension is not known, try to retrieve
    // the list of extension pathnames from various providers, checking faster
    // providers first.
    // Retrieve the current module list (derived from the service container).
    if ($type == 'module' && \Drupal::hasService('module_handler')) {
219 220 221
      foreach (\Drupal::moduleHandler()->getModuleList() as $module_name => $module) {
        $files[$type][$module_name] = $module->getPathname();
      }
222 223
    }
    // If still unknown, retrieve the file list prepared in state by
224 225
    // system_rebuild_module_data() and
    // \Drupal\Core\Extension\ThemeHandlerInterface::rebuildThemeData().
226 227
    if (!isset($files[$type][$name]) && \Drupal::hasService('state')) {
      $files[$type] += \Drupal::state()->get('system.' . $type . '.files', array());
228
    }
229
    // If still unknown, create a user-level error message.
230
    if (!isset($files[$type][$name])) {
231
      trigger_error(SafeMarkup::format('The following @type is missing from the file system: @name', array('@type' => $type, '@name' => $name)), E_USER_WARNING);
Dries's avatar
Dries committed
232 233 234
    }
  }

235 236 237
  if (isset($files[$type][$name])) {
    return $files[$type][$name];
  }
Dries's avatar
Dries committed
238 239
}

240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256
/**
 * 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'.
 *
 * @return
 *   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));
}

257
/**
258
 * Translates a string to the current language or to a given language.
259
 *
260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281
 * In order for strings to be localized, make them available in one of the ways
 * supported by the
 * @link https://www.drupal.org/node/322729 Localization API @endlink. When
 * possible, use the \Drupal\Core\StringTranslation\StringTranslationTrait
 * $this->t(). Otherwise create a new
 * \Drupal\Core\StringTranslation\TranslatableMarkup object directly.
 *
 * 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
282 283 284
 *     translate to a language other than what is used to display the page.
 *   - 'context' (defaults to the empty context): The context the source string
 *     belongs to.
285
 *
286
 * @return \Drupal\Core\StringTranslation\TranslatableMarkup
287 288 289 290 291
 *   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()
292 293
 *
 * @ingroup sanitization
294 295
 */
function t($string, array $args = array(), array $options = array()) {
296
  return \Drupal::translation()->translate($string, $args, $options);
297 298 299
}

/**
300 301
 * Formats a string for HTML display by replacing variable placeholders.
 *
302
 * @see \Drupal\Component\Utility\SafeMarkup::format()
303 304
 * @see t()
 * @ingroup sanitization
305 306 307
 *
 * @deprecated in Drupal 8.0.0, will be removed before Drupal 9.0.0.
 *   Use \Drupal\Component\Utility\SafeMarkup::format().
308
 */
309
function format_string($string, array $args) {
310
  return SafeMarkup::format($string, $args);
311 312
}

Gábor Hojtsy's avatar
Gábor Hojtsy committed
313 314 315 316 317 318 319 320 321 322 323 324 325 326 327
/**
 * 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.
 *
328 329
 * 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
330 331 332
 *
 * @param $text
 *   The text to check.
333
 *
334
 * @return bool
Gábor Hojtsy's avatar
Gábor Hojtsy committed
335
 *   TRUE if the text is valid UTF-8, FALSE if not.
336 337
 *
 * @see \Drupal\Component\Utility\Unicode::validateUtf8()
338 339 340
 *
 * @deprecated in Drupal 8.0.0, will be removed before Drupal 9.0.0.
 *   Use \Drupal\Component\Utility\Unicode::validateUtf8().
Gábor Hojtsy's avatar
Gábor Hojtsy committed
341 342
 */
function drupal_validate_utf8($text) {
343
  return Unicode::validateUtf8($text);
Dries's avatar
Dries committed
344 345
}

346
/**
347
 * Logs an exception.
348
 *
349
 * This is a wrapper logging function which automatically decodes an exception.
350 351 352 353 354 355 356
 *
 * @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
357
 *   information about the passed-in exception is used.
358
 * @param $variables
359 360 361
 *   Array of variables to replace in the message on display or
 *   NULL if message is already translated or not possible to
 *   translate.
362 363 364 365 366
 * @param $severity
 *   The severity of the message, as per RFC 3164.
 * @param $link
 *   A link to associate with the message.
 *
367
 * @see \Drupal\Core\Utility\Error::decodeException()
368
 */
369
function watchdog_exception($type, Exception $exception, $message = NULL, $variables = array(), $severity = RfcLogLevel::ERROR, $link = NULL) {
370

371 372
  // Use a default value if $message is not set.
  if (empty($message)) {
373
    $message = '%type: @message in %function (line %line of %file).';
374 375 376 377 378 379 380 381 382
  }

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

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

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

Dries's avatar
 
Dries committed
385
/**
386
 * Sets a message to display to the user.
Dries's avatar
 
Dries committed
387
 *
388 389
 * Messages are stored in a session variable and displayed in the page template
 * via the $messages theme variable.
Dries's avatar
 
Dries committed
390
 *
391 392 393 394 395
 * Example usage:
 * @code
 * drupal_set_message(t('An error occurred and processing did not complete.'), 'error');
 * @endcode
 *
396
 * @param string|\Drupal\Component\Render\MarkupInterface $message
397 398 399 400 401 402
 *   (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:
403
 *   - 'status'
404
 *   - 'warning'
405
 *   - 'error'
406 407
 * @param bool $repeat
 *   (optional) If this is FALSE and the message is already set, then the
408
 *   message won't be repeated. Defaults to FALSE.
409 410 411
 *
 * @return array|null
 *   A multidimensional array with keys corresponding to the set message types.
412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432
 *   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.
433 434
 *
 * @see drupal_get_messages()
435
 * @see status-messages.html.twig
Dries's avatar
 
Dries committed
436
 */
437
function drupal_set_message($message = NULL, $type = 'status', $repeat = FALSE) {
438
  if (isset($message)) {
Dries's avatar
 
Dries committed
439 440 441 442
    if (!isset($_SESSION['messages'][$type])) {
      $_SESSION['messages'][$type] = array();
    }

443 444 445
    // Convert strings which are safe to the simplest Markup objects.
    if (!($message instanceof Markup) && SafeMarkup::isSafe($message)) {
      $message = Markup::create((string) $message);
446 447 448
    }

    // Do not use strict type checking so that equivalent string and
449
    // MarkupInterface objects are detected.
450 451
    if ($repeat || !in_array($message, $_SESSION['messages'][$type])) {
      $_SESSION['messages'][$type][] = $message;
452
    }
453

454
    // Mark this page as being uncacheable.
455
    \Drupal::service('page_cache_kill_switch')->trigger();
456 457
  }

458
  // Messages not set when DB connection fails.
459
  return isset($_SESSION['messages']) ? $_SESSION['messages'] : NULL;
460 461
}

Dries's avatar
 
Dries committed
462
/**
463
 * Returns all messages that have been set with drupal_set_message().
Dries's avatar
 
Dries committed
464
 *
465 466 467 468 469 470 471 472 473 474 475
 * @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.
476
 *
477
 * @return array
478 479 480 481
 *   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
482
 *   drupal_set_message() for the array structure of individual messages.
483 484
 *
 * @see drupal_set_message()
485
 * @see status-messages.html.twig
Dries's avatar
 
Dries committed
486
 */
487
function drupal_get_messages($type = NULL, $clear_queue = TRUE) {
488
  if ($messages = drupal_set_message()) {
489
    if ($type) {
490
      if ($clear_queue) {
491
        unset($_SESSION['messages'][$type]);
492
      }
493 494 495
      if (isset($messages[$type])) {
        return array($type => $messages[$type]);
      }
496 497
    }
    else {
498
      if ($clear_queue) {
499
        unset($_SESSION['messages']);
500
      }
501 502
      return $messages;
    }
503
  }
504
  return array();
505 506
}

507
/**
508
 * Returns the time zone of the current user.
509 510
 */
function drupal_get_user_timezone() {
511
  $user = \Drupal::currentUser();
512
  $config = \Drupal::config('system.date');
513

514
  if ($user && $config->get('timezone.user.configurable') && $user->isAuthenticated() && $user->getTimezone()) {
515
    return $user->getTimezone();
516 517
  }
  else {
518 519
    // Ignore PHP strict notice if time zone has not yet been set in the php.ini
    // configuration.
520
    $config_data_default_timezone = $config->get('timezone.default');
521
    return !empty($config_data_default_timezone) ? $config_data_default_timezone : @date_default_timezone_get();
522 523 524
  }
}

525
/**
526
 * Provides custom PHP error handling.
527 528 529 530 531 532 533 534 535 536
 *
 * @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
537 538
 *   An array that points to the active symbol table at the point the error
 *   occurred.
539 540
 */
function _drupal_error_handler($error_level, $message, $filename, $line, $context) {
541
  require_once __DIR__ . '/errors.inc';
542 543 544 545
  _drupal_error_handler_real($error_level, $message, $filename, $line, $context);
}

/**
546
 * Provides custom PHP exception handling.
547 548 549 550 551
 *
 * 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.
 *
552
 * @param \Exception|\Throwable $exception
553 554 555
 *   The exception object that was thrown.
 */
function _drupal_exception_handler($exception) {
556
  require_once __DIR__ . '/errors.inc';
557 558 559

  try {
    // Log the message to the watchdog and return an error page to the user.
560
    _drupal_log_error(Error::decodeException($exception), TRUE);
561
  }
562 563 564 565
  // PHP 7 introduces Throwable, which covers both Error and
  // Exception throwables.
  catch (\Throwable $error) {
    _drupal_exception_handler_additional($exception, $error);
566
  }
567
  // In order to be compatible with PHP 5 we also catch regular Exceptions.
568
  catch (\Exception $exception2) {
569 570 571 572 573 574 575
    _drupal_exception_handler_additional($exception, $exception2);
  }
}

/**
 * Displays any additional errors caught while handling an exception.
 *
576
 * @param \Exception|\Throwable $exception
577
 *   The first exception object that was thrown.
578
 * @param \Exception|\Throwable $exception2
579 580 581 582 583 584 585 586 587 588
 *   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 />';
589
  }
590 591
}

592
/**
593
 * Returns the test prefix if this is an internal request from SimpleTest.
594
 *
595
 * @param string $new_prefix
596
 *   Internal use only. A new prefix to be stored.
597
 *
598
 * @return string|FALSE
599 600 601
 *   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.
602
 */
603
function drupal_valid_test_ua($new_prefix = NULL) {
604 605
  static $test_prefix;

606 607 608
  if (isset($new_prefix)) {
    $test_prefix = $new_prefix;
  }
609 610 611
  if (isset($test_prefix)) {
    return $test_prefix;
  }
612 613 614
  // Unless the below User-Agent and HMAC validation succeeds, we are not in
  // a test environment.
  $test_prefix = FALSE;
615

616 617 618 619 620 621
  // 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;
  if (isset($user_agent) && preg_match("/^(simpletest\d+);(.+);(.+);(.+)$/", $user_agent, $matches)) {
622 623
    list(, $prefix, $time, $salt, $hmac) = $matches;
    $check_string =  $prefix . ';' . $time . ';' . $salt;
624 625 626 627 628 629 630 631 632 633 634 635 636
    // 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.
    $key_file = DRUPAL_ROOT . '/sites/simpletest/' . substr($prefix, 10) . '/.htkey';
    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__);
637
    $time_diff = REQUEST_TIME - $time;
638
    $test_hmac = Crypt::hmacBase64($check_string, $key);
639 640
    // Since we are making a local request a 5 second time window is allowed,
    // and the HMAC must match.
641
    if ($time_diff >= 0 && $time_diff <= 5 && $hmac === $test_hmac) {
642 643 644
      $test_prefix = $prefix;
    }
  }
645
  return $test_prefix;
646 647 648
}

/**
649
 * Generates a user agent string with a HMAC and timestamp for simpletest.
650 651
 */
function drupal_generate_test_ua($prefix) {
652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671
  static $key, $last_prefix;

  if (!isset($key) || $last_prefix != $prefix) {
    $last_prefix = $prefix;
    $key_file = DRUPAL_ROOT . '/sites/simpletest/' . substr($prefix, 10) . '/.htkey';
    // 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.
672
      $private_key = Crypt::randomBytesBase64(55);
673 674 675 676
      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__);
677
  }
678 679 680
  // Generate a moderately secure HMAC based on the database credentials.
  $salt = uniqid('', TRUE);
  $check_string = $prefix . ';' . time() . ';' . $salt;
681
  return $check_string . ';' . Crypt::hmacBase64($check_string, $key);
682 683
}

684
/**
685 686 687
 * Enables use of the theme system without requiring database access.
 *
 * Loads and initializes the theme system for site installs, updates and when
688
 * the site is in maintenance mode. This also applies when the database fails.
689 690
 *
 * @see _drupal_maintenance_theme()
691 692
 */
function drupal_maintenance_theme() {
693
  require_once __DIR__ . '/theme.maintenance.inc';
694
  _drupal_maintenance_theme();
695
}
696

697
/**
698
 * Returns TRUE if a Drupal installation is currently being attempted.
699 700
 */
function drupal_installation_attempted() {
701 702 703 704 705 706
  // 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']);
707 708
}

709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741
/**
 * 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
 * available in settings.php.
 *
 * @return string|null $profile
 *   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.
 */
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 {
    // Fall back to NULL, if there is no 'install_profile' setting.
    $profile = Settings::get('install_profile');
  }

  return $profile;
}

742 743 744 745 746 747 748 749 750
/**
 * 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) {
751
  $loader = \Drupal::service('class_loader');
752
  $loader->addPsr4('Drupal\\' . $name . '\\', \Drupal::root() . '/' . $path . '/src');
753 754
}

755
/**
756
 * Provides central static variable storage.
757
 *
758 759 760 761 762 763 764 765 766
 * 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
767 768 769
 * function example_list($field = 'default') {
 *   $examples = &drupal_static(__FUNCTION__);
 *   if (!isset($examples)) {
770 771
 *     // If this function is being called for the first time after a reset,
 *     // query the database and execute any other code needed to retrieve
772
 *     // information.
773 774
 *     ...
 *   }
775
 *   if (!isset($examples[$field])) {
776 777
 *     // If this function is being called for the first time for a particular
 *     // index field, then execute code needed to index the information already
778
 *     // available in $examples by the desired field.
779 780 781 782 783
 *     ...
 *   }
 *   // Subsequent invocations of this function for a particular index field
 *   // skip the above two code blocks and quickly return the already indexed
 *   // information.
784
 *   return $examples[$field];
785
 * }
786 787 788 789
 * function examples_admin_overview() {
 *   // When building the content for the overview page, make sure to get
 *   // completely fresh information.
 *   drupal_static_reset('example_list');
790 791 792 793 794 795 796 797 798 799 800 801 802 803
 *   ...
 * }
 * @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
804 805 806 807
 * function mymodule_log_stream_handle($new_handle = NULL) {
 *   static $handle;
 *   if (isset($new_handle)) {
 *     $handle = $new_handle;
808
 *   }
809
 *   return $handle;
810 811 812 813 814 815 816
 * }
 * @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
817 818 819 820 821 822 823 824 825 826 827 828 829
 * 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
830
 * variables to be initialized by literal values, and does not allow static
831
 * variables to be assigned to references.
832 833
 * - http://php.net/manual/language.variables.scope.php#language.variables.scope.static
 * - http://php.net/manual/language.variables.scope.php#language.variables.scope.references
834
 * The example below shows the syntax needed to work around both limitations.
835
 * For benchmarks and more information, see https://www.drupal.org/node/619666.
836 837 838
 *
 * Example:
 * @code
839
 * function example_default_format_type() {
840
 *   // Use the advanced drupal_static() pattern, since this is called very often.
841 842
 *   static $drupal_static_fast;
 *   if (!isset($drupal_static_fast)) {
843
 *     $drupal_static_fast['format_type'] = &drupal_static(__FUNCTION__);
844
 *   }
845
 *   $format_type = &$drupal_static_fast['format_type'];
846 847 848 849
 *   ...
 * }
 * @endcode
 *
850 851 852
 * @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)
853
 *   is recommended. For a function with multiple static variables add a
854 855 856 857
 *   distinguishing suffix to the function name for each one.
 * @param $default_value
 *   Optional default value.
 * @param $reset
858 859 860
 *   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.)
861 862
 *
 * @return
863
 *   Returns a variable by reference.
864 865
 *
 * @see drupal_static_reset()
866 867
 */
function &drupal_static($name, $default_value = NULL, $reset = FALSE) {
868
  static $data = array(), $default = array();
869 870 871 872 873
  // 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.
874
      $data[$name] = $default[$name];
875
    }
876 877 878 879 880
    return $data[$name];
  }
  // Neither $data[$name] nor $default[$name] static variables exist.
  if (isset($name)) {
    if ($reset) {
881 882 883
      // Reset was called before a default is set and yet a variable must be
      // returned.
      return $data;
884
    }
885
    // First call with new non-NULL $name. Initialize a new static variable.
886
    $default[$name] = $data[$name] = $default_value;
887 888 889 890 891 892 893
    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;
894
  }
895 896 897
  // As the function returns a reference, the return should always be a
  // variable.
  return $data;
898 899 900
}

/**
901
 * Resets one or all centrally stored static variable(s).
902 903 904
 *
 * @param $name
 *   Name of the static variable to reset. Omit to reset all variables.
905 906
 *   Resetting all variables should only be used, for example, for running
 *   unit tests with a clean environment.
907 908 909 910
 */
function drupal_static_reset($name = NULL) {
  drupal_static($name, NULL, TRUE);
}
911

912 913
/**
 * Formats text for emphasized display in a placeholder inside a sentence.
914
 *
915 916 917 918 919 920 921
 * @deprecated in Drupal 8.0.0, will be removed before Drupal 9.0.0. Use
 *   \Drupal\Component\Utility\SafeMarkup::format() 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.
 *
 * @see \Drupal\Component\Utility\SafeMarkup::format()
922
 */
923
function drupal_placeholder($text) {
924
  return '<em class="placeholder">' . Html::escape($text) . '</em>';
925
}
926 927

/**
928
 * Registers a function for execution on shutdown.
929
 *
930 931
 * Wrapper for register_shutdown_function() that catches thrown exceptions to
 * avoid "Exception thrown without a stack frame in Unknown".
932 933