bootstrap.inc 79.7 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\Environment;
9
use Drupal\Component\Utility\NestedArray;
10
use Drupal\Component\Utility\String;
11
use Drupal\Component\Utility\Timer;
12
use Drupal\Component\Utility\Unicode;
13
use Drupal\Component\Utility\UrlHelper;
14
use Drupal\Core\DrupalKernel;
15
16
use Drupal\Core\Database\Database;
use Drupal\Core\DependencyInjection\ContainerBuilder;
17
use Drupal\Core\Extension\ExtensionDiscovery;
18
use Drupal\Core\Site\Settings;
19
use Drupal\Core\Utility\Title;
20
use Drupal\Core\Utility\Error;
21
use Symfony\Component\ClassLoader\ApcClassLoader;
22
23
24
25
use Symfony\Component\DependencyInjection\ContainerInterface;
use Symfony\Component\DependencyInjection\Container;
use Symfony\Component\DependencyInjection\Reference;
use Symfony\Component\DependencyInjection\Exception\RuntimeException as DependencyInjectionRuntimeException;
26
use Symfony\Component\HttpFoundation\Request;
27
use Symfony\Component\HttpFoundation\Response;
28
use Drupal\Core\Language\Language;
29
30
use Drupal\Core\Lock\DatabaseLockBackend;
use Drupal\Core\Lock\LockBackendInterface;
31
use Drupal\Core\Session\AnonymousUserSession;
32

33
34
35
/**
 * Minimum supported version of PHP.
 */
36
const DRUPAL_MINIMUM_PHP = '5.4.2';
37
38
39
40

/**
 * Minimum recommended value of PHP memory_limit.
 */
41
const DRUPAL_MINIMUM_PHP_MEMORY_LIMIT = '32M';
42

43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
/**
 * 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';

63
64
65
66
67
68
/**
 * @defgroup logging_severity_levels Logging severity levels
 * @{
 * Logging severity levels as defined in RFC 3164.
 *
 * The WATCHDOG_* constant definitions correspond to the logging severity levels
69
 * defined in RFC 3164, section 4.1.1. PHP supplies predefined LOG_* constants
70
 * for use in the syslog() function, but their values on Windows builds do not
71
 * correspond to RFC 3164. The associated PHP bug report was closed with the
72
73
74
75
76
77
78
79
80
81
82
83
84
85
 * comment, "And it's also not a bug, as Windows just have less log levels,"
 * and "So the behavior you're seeing is perfectly normal."
 *
 * @see http://www.faqs.org/rfcs/rfc3164.html
 * @see http://bugs.php.net/bug.php?id=18090
 * @see http://php.net/manual/function.syslog.php
 * @see http://php.net/manual/network.constants.php
 * @see watchdog()
 * @see watchdog_severity_levels()
 */

/**
 * Log message severity -- Emergency: system is unusable.
 */
86
const WATCHDOG_EMERGENCY = 0;
87
88
89
90

/**
 * Log message severity -- Alert: action must be taken immediately.
 */
91
const WATCHDOG_ALERT = 1;
92
93

/**
94
 * Log message severity -- Critical conditions.
95
 */
96
const WATCHDOG_CRITICAL = 2;
97
98

/**
99
 * Log message severity -- Error conditions.
100
 */
101
const WATCHDOG_ERROR = 3;
102
103

/**
104
 * Log message severity -- Warning conditions.
105
 */
106
const WATCHDOG_WARNING = 4;
107
108

/**
109
 * Log message severity -- Normal but significant conditions.
110
 */
111
const WATCHDOG_NOTICE = 5;
112
113

/**
114
 * Log message severity -- Informational messages.
115
 */
116
const WATCHDOG_INFO = 6;
117
118

/**
119
 * Log message severity -- Debug-level messages.
120
 */
121
const WATCHDOG_DEBUG = 7;
122
123
124
125
126

/**
 * @} End of "defgroup logging_severity_levels".
 */

127
128
129
/**
 * First bootstrap phase: initialize configuration.
 */
130
const DRUPAL_BOOTSTRAP_CONFIGURATION = 0;
131
132

/**
133
 * Second bootstrap phase, initalize a kernel.
134
 */
135
const DRUPAL_BOOTSTRAP_KERNEL = 1;
136
137

/**
138
 * Third bootstrap phase: try to serve a cached page.
139
 */
140
const DRUPAL_BOOTSTRAP_PAGE_CACHE = 2;
141
142

/**
143
 * Fourth bootstrap phase: load code for subsystems and modules.
144
 */
145
const DRUPAL_BOOTSTRAP_CODE = 3;
146
147

/**
148
 * Final bootstrap phase: initialize language, path, theme, and modules.
149
 */
150
const DRUPAL_BOOTSTRAP_FULL = 4;
151

152
153
154
/**
 * Role ID for anonymous users; should match what's in the "role" table.
 */
155
const DRUPAL_ANONYMOUS_RID = 'anonymous';
156
157
158
159

/**
 * Role ID for authenticated users; should match what's in the "role" table.
 */
160
const DRUPAL_AUTHENTICATED_RID = 'authenticated';
161

162
163
164
165
166
/**
 * The maximum number of characters in a module or theme name.
 */
const DRUPAL_EXTENSION_NAME_MAX_LENGTH = 50;

167
/**
168
 * Time of the current request in seconds elapsed since the Unix Epoch.
169
 *
170
171
172
173
174
175
 * 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
176
 */
177
define('REQUEST_TIME', (int) $_SERVER['REQUEST_TIME']);
178

179
180
181
/**
 * Regular expression to match PHP function names.
 *
182
 * @see http://php.net/manual/language.functions.php
183
 */
184
const DRUPAL_PHP_FUNCTION_PATTERN = '[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*';
185

186
187
188
/**
 * $config_directories key for active directory.
 *
189
 * @see config_get_config_directory()
190
191
192
193
194
195
 */
const CONFIG_ACTIVE_DIRECTORY = 'active';

/**
 * $config_directories key for staging directory.
 *
196
 * @see config_get_config_directory()
197
198
199
 */
const CONFIG_STAGING_DIRECTORY = 'staging';

200
201
202
203
204
205
206
/**
 * 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
207
/**
208
 * Returns the appropriate configuration directory.
Dries's avatar
   
Dries committed
209
 *
210
211
212
213
214
 * Returns the configuration path based on the site's hostname, port, and
 * pathname. Uses find_conf_path() to find the current configuration directory.
 * See default.settings.php for examples on how the URL is converted to a
 * directory.
 *
215
 * @param bool $require_settings
216
217
218
219
 *   Only configuration directories with an existing settings.php file
 *   will be recognized. Defaults to TRUE. During initial installation,
 *   this is set to FALSE so that Drupal can detect a matching directory,
 *   then create a new settings.php file in it.
220
 * @param bool $reset
221
 *   Force a full search for matching directories even if one had been
222
223
 *   found previously. Defaults to FALSE.
 *
224
225
 * @return
 *   The path of the matching directory.
226
 *
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
 * @see default.settings.php
 */
function conf_path($require_settings = TRUE, $reset = FALSE) {
  static $conf_path;

  if (isset($conf_path) && !$reset) {
    return $conf_path;
  }

  // Check for a simpletest override.
  if ($test_prefix = drupal_valid_test_ua()) {
    $conf_path = 'sites/simpletest/' . substr($test_prefix, 10);
    return $conf_path;
  }

  // Otherwise, use the normal $conf_path.
  $script_name = $_SERVER['SCRIPT_NAME'];
  if (!$script_name) {
    $script_name = $_SERVER['SCRIPT_FILENAME'];
246
  }
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
  $http_host = $_SERVER['HTTP_HOST'];
  $conf_path = find_conf_path($http_host, $script_name, $require_settings);
  return $conf_path;
}

/**
 * Finds the appropriate configuration directory for a given host and path.
 *
 * Finds a matching configuration directory file by stripping the website's
 * hostname from left to right and pathname from right to left. By default,
 * the directory must contain a 'settings.php' file for it to match. If the
 * parameter $require_settings is set to FALSE, then a directory without a
 * 'settings.php' file will match as well. The first configuration
 * file found will be used and the remaining ones will be ignored. If no
 * configuration file is found, returns a default value '$confdir/default'. See
 * default.settings.php for examples on how the URL is converted to a directory.
 *
 * If a file named sites.php is present in the $confdir, it will be loaded
 * prior to scanning for directories. That file can define aliases in an
 * associative array named $sites. The array is written in the format
 * '<port>.<domain>.<path>' => 'directory'. As an example, to create a
 * directory alias for http://www.drupal.org:8080/mysite/test whose configuration
 * file is in sites/example.com, the array should be defined as:
 * @code
 * $sites = array(
 *   '8080.www.drupal.org.mysite.test' => 'example.com',
 * );
 * @endcode
 *
 * @param $http_host
 *   The hostname and optional port number, e.g. "www.example.com" or
 *   "www.example.com:8080".
 * @param $script_name
 *   The part of the URL following the hostname, including the leading slash.
 * @param $require_settings
 *   Defaults to TRUE. If TRUE, then only match directories with a
 *   'settings.php' file. Otherwise match any directory.
 *
 * @return
 *   The path of the matching configuration directory.
 *
 * @see default.settings.php
 * @see example.sites.php
 * @see conf_path()
 */
function find_conf_path($http_host, $script_name, $require_settings = TRUE) {
  // Determine whether multi-site functionality is enabled.
  if (!file_exists(DRUPAL_ROOT . '/sites/sites.php')) {
    return 'sites/default';
296
  }
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312

  $sites = array();
  include DRUPAL_ROOT . '/sites/sites.php';

  $uri = explode('/', $script_name);
  $server = explode('.', implode('.', array_reverse(explode(':', rtrim($http_host, '.')))));
  for ($i = count($uri) - 1; $i > 0; $i--) {
    for ($j = count($server); $j > 0; $j--) {
      $dir = implode('.', array_slice($server, -$j)) . implode('.', array_slice($uri, 0, $i));
      if (isset($sites[$dir]) && file_exists(DRUPAL_ROOT . '/sites/' . $sites[$dir])) {
        $dir = $sites[$dir];
      }
      if (file_exists(DRUPAL_ROOT . '/sites/' . $dir . '/settings.php') || (!$require_settings && file_exists(DRUPAL_ROOT . '/sites/' . $dir))) {
        return "sites/$dir";
      }
    }
Dries's avatar
 
Dries committed
313
  }
314
  return 'sites/default';
Dries's avatar
 
Dries committed
315
}
316

317
/**
318
319
320
321
322
 * Returns the path of a configuration directory.
 *
 * @param string $type
 *   (optional) The type of config directory to return. Drupal core provides
 *   'active' and 'staging'. Defaults to CONFIG_ACTIVE_DIRECTORY.
323
324
325
326
 *
 * @return string
 *   The configuration directory path.
 */
327
328
function config_get_config_directory($type = CONFIG_ACTIVE_DIRECTORY) {
  global $config_directories;
329

330
  if (!empty($config_directories[$type])) {
331
    return $config_directories[$type];
332
  }
333
  throw new \Exception(format_string('The configuration directory type %type does not exist.', array('%type' => $type)));
334
335
}

336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
/**
 * Initializes the PHP environment.
 */
function drupal_environment_initialize() {
  if (!isset($_SERVER['SERVER_PROTOCOL']) || ($_SERVER['SERVER_PROTOCOL'] != 'HTTP/1.0' && $_SERVER['SERVER_PROTOCOL'] != 'HTTP/1.1')) {
    $_SERVER['SERVER_PROTOCOL'] = 'HTTP/1.0';
  }

  if (isset($_SERVER['HTTP_HOST'])) {
    // As HTTP_HOST is user input, ensure it only contains characters allowed
    // in hostnames. See RFC 952 (and RFC 2181).
    // $_SERVER['HTTP_HOST'] is lowercased here per specifications.
    $_SERVER['HTTP_HOST'] = strtolower($_SERVER['HTTP_HOST']);
    if (!drupal_valid_http_host($_SERVER['HTTP_HOST'])) {
      // HTTP_HOST is invalid, e.g. if containing slashes it may be an attack.
      header($_SERVER['SERVER_PROTOCOL'] . ' 400 Bad Request');
      exit;
    }
  }
  else {
    // Some pre-HTTP/1.1 clients will not send a Host header. Ensure the key is
    // defined for E_ALL compliance.
    $_SERVER['HTTP_HOST'] = '';
  }

  // @todo Refactor with the Symfony Request object.
  _current_path(request_path());

  // Enforce E_STRICT, but allow users to set levels not part of E_STRICT.
  error_reporting(E_STRICT | E_ALL | error_reporting());

  // Override PHP settings required for Drupal to work properly.
  // sites/default/default.settings.php contains more runtime settings.
  // The .htaccess file contains settings that cannot be changed at runtime.

  // Use session cookies, not transparent sessions that puts the session id in
  // the query string.
  ini_set('session.use_cookies', '1');
  ini_set('session.use_only_cookies', '1');
  ini_set('session.use_trans_sid', '0');
  // Don't send HTTP headers using PHP's session handler.
  // Send an empty string to disable the cache limiter.
  ini_set('session.cache_limiter', '');
  // Use httponly session cookies.
  ini_set('session.cookie_httponly', '1');

  // Set sane locale settings, to ensure consistent string, dates, times and
  // numbers handling.
  setlocale(LC_ALL, 'C');
}

/**
 * Validates that a hostname (for example $_SERVER['HTTP_HOST']) is safe.
 *
 * @return
 *  TRUE if only containing valid characters, or FALSE otherwise.
 */
function drupal_valid_http_host($host) {
  return preg_match('/^\[?(?:[a-zA-Z0-9-:\]_]+\.?)+$/', $host);
}

/**
 * Sets the base URL, cookie domain, and session name from configuration.
 */
function drupal_settings_initialize() {
  // Export these settings.php variables to the global namespace.
  global $base_url, $cookie_domain, $config_directories, $config;
  $databases = array();
  $settings = array();
  $config = array();

  // Make conf_path() available as local variable in settings.php.
  $conf_path = conf_path();
  if (is_readable(DRUPAL_ROOT . '/' . $conf_path . '/settings.php')) {
    require DRUPAL_ROOT . '/' . $conf_path . '/settings.php';
  }
  // Initialize Database.
  Database::setMultipleConnectionInfo($databases);
  // Initialize Settings.
  new Settings($settings);
}

/**
 * Initializes global request variables.
 *
 * @todo D8: Eliminate this entirely in favor of Request object.
 */
function _drupal_request_initialize() {
  // Provided by settings.php.
  // @see drupal_settings_initialize()
  global $base_url, $cookie_domain;
  // Set and derived from $base_url by this function.
  global $base_path, $base_root, $script_path;
  global $base_secure_url, $base_insecure_url;

  $is_https = isset($_SERVER['HTTPS']) && strtolower($_SERVER['HTTPS']) == 'on';

  if (isset($base_url)) {
    // Parse fixed base URL from settings.php.
    $parts = parse_url($base_url);
    if (!isset($parts['path'])) {
      $parts['path'] = '';
    }
    $base_path = $parts['path'] . '/';
    // Build $base_root (everything until first slash after "scheme://").
    $base_root = substr($base_url, 0, strlen($base_url) - strlen($parts['path']));
  }
  else {
    // Create base URL
    $http_protocol = $is_https ? 'https' : 'http';
    $base_root = $http_protocol . '://' . $_SERVER['HTTP_HOST'];

    $base_url = $base_root;

    // For a request URI of '/index.php/foo', $_SERVER['SCRIPT_NAME'] is
    // '/index.php', whereas $_SERVER['PHP_SELF'] is '/index.php/foo'.
    if ($dir = rtrim(dirname($_SERVER['SCRIPT_NAME']), '\/')) {
      // Remove "core" directory if present, allowing install.php, update.php,
      // and others to auto-detect a base path.
      $core_position = strrpos($dir, '/core');
      if ($core_position !== FALSE && strlen($dir) - 5 == $core_position) {
        $base_path = substr($dir, 0, $core_position);
      }
      else {
        $base_path = $dir;
      }
      $base_url .= $base_path;
      $base_path .= '/';
    }
    else {
      $base_path = '/';
    }
  }
  $base_secure_url = str_replace('http://', 'https://', $base_url);
  $base_insecure_url = str_replace('https://', 'http://', $base_url);

  // Determine the path of the script relative to the base path, and add a
  // trailing slash. This is needed for creating URLs to Drupal pages.
  if (!isset($script_path)) {
    $script_path = '';
    // We don't expect scripts outside of the base path, but sanity check
    // anyway.
    if (strpos($_SERVER['SCRIPT_NAME'], $base_path) === 0) {
      $script_path = substr($_SERVER['SCRIPT_NAME'], strlen($base_path)) . '/';
      // If the request URI does not contain the script name, then clean URLs
      // are in effect and the script path can be similarly dropped from URL
      // generation. For servers that don't provide $_SERVER['REQUEST_URI'], we
      // do not know the actual URI requested by the client, and request_uri()
      // returns a URI with the script name, resulting in non-clean URLs unless
      // there's other code that intervenes.
      if (strpos(request_uri(TRUE) . '/', $base_path . $script_path) !== 0) {
        $script_path = '';
      }
      // @todo Temporary BC for install.php, update.php, and other scripts.
      //   - http://drupal.org/node/1547184
      //   - http://drupal.org/node/1546082
      if ($script_path !== 'index.php/') {
        $script_path = '';
      }
    }
  }

  if ($cookie_domain) {
    // If the user specifies the cookie domain, also use it for session name.
    $session_name = $cookie_domain;
  }
  else {
    // Otherwise use $base_url as session name, without the protocol
    // to use the same session identifiers across HTTP and HTTPS.
    list( , $session_name) = explode('://', $base_url, 2);
    // HTTP_HOST can be modified by a visitor, but we already sanitized it
    // in drupal_settings_initialize().
    if (!empty($_SERVER['HTTP_HOST'])) {
      $cookie_domain = $_SERVER['HTTP_HOST'];
      // Strip leading periods, www., and port numbers from cookie domain.
      $cookie_domain = ltrim($cookie_domain, '.');
      if (strpos($cookie_domain, 'www.') === 0) {
        $cookie_domain = substr($cookie_domain, 4);
      }
      $cookie_domain = explode(':', $cookie_domain);
      $cookie_domain = '.' . $cookie_domain[0];
    }
  }
  // Per RFC 2109, cookie domains must contain at least one dot other than the
  // first. For hosts such as 'localhost' or IP Addresses we don't set a cookie domain.
  if (count(explode('.', $cookie_domain)) > 2 && !is_numeric(str_replace('.', '', $cookie_domain))) {
    ini_set('session.cookie_domain', $cookie_domain);
  }
  // To prevent session cookies from being hijacked, a user can configure the
  // SSL version of their website to only transfer session cookies via SSL by
  // using PHP's session.cookie_secure setting. The browser will then use two
  // separate session cookies for the HTTPS and HTTP versions of the site. So we
  // must use different session identifiers for HTTPS and HTTP to prevent a
  // cookie collision.
  if ($is_https) {
    ini_set('session.cookie_secure', TRUE);
  }
  $prefix = ini_get('session.cookie_secure') ? 'SSESS' : 'SESS';
  session_name($prefix . substr(hash('sha256', $session_name), 0, 32));
}

Dries's avatar
Dries committed
537
/**
538
539
540
541
 * 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
542
 *
Dries's avatar
Dries committed
543
544
 * 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
545
 * configuration. For example, a module 'foo' may legally be located
Dries's avatar
Dries committed
546
547
 * in any of these three places:
 *
548
549
550
 * core/modules/foo/foo.info.yml
 * modules/foo/foo.info.yml
 * sites/example.com/modules/foo/foo.info.yml
Dries's avatar
Dries committed
551
552
553
554
 *
 * 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
555
 * @param $type
556
557
 *   The type of the item; one of 'core', 'profile', 'module', 'theme', or
 *   'theme_engine'.
Dries's avatar
Dries committed
558
 * @param $name
559
560
 *   The name of the item for which the filename is requested. Ignored for
 *   $type 'core'.
Dries's avatar
Dries committed
561
562
563
564
565
 * @param $filename
 *   The filename of the item if it is to be set explicitly rather
 *   than by consulting the database.
 *
 * @return
566
 *   The filename of the requested item or NULL if the item is not found.
Dries's avatar
Dries committed
567
 */
Dries's avatar
Dries committed
568
function drupal_get_filename($type, $name, $filename = NULL) {
569
570
  // The location of files will not change during the request, so do not use
  // drupal_static().
571
  static $files = array();
Dries's avatar
Dries committed
572

573
574
575
576
577
578
579
580
  // 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';
  }

581
582
583
  // Profiles are converted into modules in system_rebuild_module_data().
  // @todo Remove false-exposure of profiles as modules.
  $original_type = $type;
584
  if ($type == 'profile') {
585
    $type = 'module';
586
  }
587
  if (!isset($files[$type])) {
Dries's avatar
Dries committed
588
589
590
    $files[$type] = array();
  }

591
  if (isset($filename)) {
Dries's avatar
Dries committed
592
593
    $files[$type][$name] = $filename;
  }
594
595
596
597
598
599
  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')) {
600
601
602
      foreach (\Drupal::moduleHandler()->getModuleList() as $module_name => $module) {
        $files[$type][$module_name] = $module->getPathname();
      }
603
604
605
606
607
    }
    // If still unknown, retrieve the file list prepared in state by
    // system_rebuild_module_data() and system_rebuild_theme_data().
    if (!isset($files[$type][$name]) && \Drupal::hasService('state')) {
      $files[$type] += \Drupal::state()->get('system.' . $type . '.files', array());
608
    }
609
    // If still unknown, perform a filesystem scan.
610
    if (!isset($files[$type][$name])) {
611
612
613
614
      $listing = new ExtensionDiscovery();
      // Prevent an infinite recursion by this legacy function.
      if ($original_type == 'profile') {
        $listing->setProfileDirectories(array());
615
      }
616
      foreach ($listing->scan($original_type) as $extension_name => $file) {
617
        $files[$type][$extension_name] = $file->getPathname();
Dries's avatar
Dries committed
618
619
620
621
      }
    }
  }

622
623
624
  if (isset($files[$type][$name])) {
    return $files[$type][$name];
  }
Dries's avatar
Dries committed
625
626
}

627
628
629
630
631
632
633
634
635
636
637
638
/**
 * Gets the page cache cid for this request.
 *
 * @param \Symfony\Component\HttpFoundation\Request $request
 *   The request for this page.
 *
 * @return string
 *   The cid for this request.
 */
function drupal_page_cache_get_cid(Request $request) {
  $cid_parts = array(
    $request->getUri(),
639
    \Drupal::service('content_negotiation')->getContentType($request),
640
641
642
643
  );
  return sha1(implode(':', $cid_parts));
}

Dries's avatar
   
Dries committed
644
/**
645
 * Retrieves the current page from the cache.
Dries's avatar
   
Dries committed
646
 *
647
648
 * @param \Symfony\Component\HttpFoundation\Request $request
 *   The request for this page.
649
 *
650
651
 * @return \Symfony\Component\HttpFoundation\Response
 *   The response, if the page was found in the cache, NULL otherwise.
Dries's avatar
   
Dries committed
652
 */
653
function drupal_page_get_cache(Request $request) {
654
655
656
  $cache = \Drupal::cache('render')->get(drupal_page_cache_get_cid($request));
  if ($cache) {
    return $cache->data;
657
  }
658
659
660
}

/**
661
 * Determines the cacheability of the current page.
662
 *
663
664
665
666
667
 * Note: we do not serve cached pages to authenticated users, or to anonymous
 * users when $_SESSION is non-empty. $_SESSION may contain status messages
 * from a form submission, the contents of a shopping cart, or other user-
 * specific content that should not be cached and displayed to other users.
 *
668
 * @param $allow_caching
669
670
 *   Set to FALSE if you want to prevent this page to get cached.
 *
671
 * @return
672
 *   TRUE if the current page can be cached, FALSE otherwise.
673
674
675
676
677
 */
function drupal_page_is_cacheable($allow_caching = NULL) {
  $allow_caching_static = &drupal_static(__FUNCTION__, TRUE);
  if (isset($allow_caching)) {
    $allow_caching_static = $allow_caching;
Dries's avatar
 
Dries committed
678
  }
679
680

  return $allow_caching_static && ($_SERVER['REQUEST_METHOD'] == 'GET' || $_SERVER['REQUEST_METHOD'] == 'HEAD')
681
    && !drupal_is_cli();
Dries's avatar
 
Dries committed
682
683
}

684
/**
685
 * Sets an HTTP response header for the current page.
686
687
688
689
690
 *
 * Note: When sending a Content-Type header, always include a 'charset' type,
 * too. This is necessary to avoid security bugs (e.g. UTF-7 XSS).
 *
 * @param $name
691
 *   The HTTP header name, or the special 'Status' header name.
692
 * @param $value
693
694
695
 *   The HTTP header value; if equal to FALSE, the specified header is unset.
 *   If $name is 'Status', this is expected to be a status code followed by a
 *   reason phrase, e.g. "404 Not Found".
696
697
 * @param $append
 *   Whether to append the value to an existing header or to replace it.
698
 *
699
700
701
 * @deprecated in Drupal 8.x-dev, will be removed before Drupal 8.0.
 *   Use \Symfony\Component\HttpFoundation\Response->headers->set().
 *   See https://drupal.org/node/2181523.
702
 */
703
function drupal_add_http_header($name, $value, $append = FALSE) {
704
  // The headers as name/value pairs.
705
  $headers = &drupal_static('drupal_http_headers', array());
706

707
  $name_lower = strtolower($name);
708
  _drupal_set_preferred_header_name($name);
709

710
  if ($value === FALSE) {
711
    $headers[$name_lower] = FALSE;
712
  }
713
  elseif (isset($headers[$name_lower]) && $append) {
714
715
    // Multiple headers with identical names may be combined using comma (RFC
    // 2616, section 4.2).
716
    $headers[$name_lower] .= ',' . $value;
717
718
  }
  else {
719
    $headers[$name_lower] = $value;
720
721
722
723
  }
}

/**
724
 * Gets the HTTP response headers for the current page.
725
726
727
728
 *
 * @param $name
 *   An HTTP header name. If omitted, all headers are returned as name/value
 *   pairs. If an array value is FALSE, the header has been unset.
729
 *
730
731
732
 * @return
 *   A string containing the header value, or FALSE if the header has been set,
 *   or NULL if the header has not been set.
733
 *
734
735
736
 * @deprecated in Drupal 8.x-dev, will be removed before Drupal 8.0.
 *   Use \Symfony\Component\HttpFoundation\Response->headers->get().
 *   See https://drupal.org/node/2181523.
737
 */
738
function drupal_get_http_header($name = NULL) {
739
  $headers = &drupal_static('drupal_http_headers', array());
740
741
742
743
744
745
746
747
748
749
  if (isset($name)) {
    $name = strtolower($name);
    return isset($headers[$name]) ? $headers[$name] : NULL;
  }
  else {
    return $headers;
  }
}

/**
750
751
 * Sets the preferred name for the HTTP header.
 *
752
 * Header names are case-insensitive, but for maximum compatibility they should
753
754
 * follow "common form" (see RFC 2616, section 4.2).
 *
755
756
 * @deprecated in Drupal 8.x-dev, will be removed before Drupal 8.0.
 *   See https://drupal.org/node/2181523.
757
758
759
760
761
762
763
764
765
766
767
 */
function _drupal_set_preferred_header_name($name = NULL) {
  static $header_names = array();

  if (!isset($name)) {
    return $header_names;
  }
  $header_names[strtolower($name)] = $name;
}

/**
768
769
770
771
 * Sends the HTTP response headers that were previously set, adding defaults.
 *
 * Headers are set in drupal_add_http_header(). Default headers are not set
 * if they have been replaced or unset using drupal_add_http_header().
772
 *
773
774
775
776
777
 * @param array $default_headers
 *   (optional) An array of headers as name/value pairs.
 * @param bool $only_default
 *   (optional) If TRUE and headers have already been sent, send only the
 *   specified headers.
778
 *
779
780
 * @deprecated in Drupal 8.x-dev, will be removed before Drupal 8.0.
 *   See https://drupal.org/node/2181523.
781
782
783
 */
function drupal_send_headers($default_headers = array(), $only_default = FALSE) {
  $headers_sent = &drupal_static(__FUNCTION__, FALSE);
784
  $headers = drupal_get_http_header();
785
786
787
788
789
790
791
792
793
794
795
796
797
798
  if ($only_default && $headers_sent) {
    $headers = array();
  }
  $headers_sent = TRUE;

  $header_names = _drupal_set_preferred_header_name();
  foreach ($default_headers as $name => $value) {
    $name_lower = strtolower($name);
    if (!isset($headers[$name_lower])) {
      $headers[$name_lower] = $value;
      $header_names[$name_lower] = $name;
    }
  }
  foreach ($headers as $name_lower => $value) {
799
    if ($name_lower == 'status') {
800
801
802
      header($_SERVER['SERVER_PROTOCOL'] . ' ' . $value);
    }
    // Skip headers that have been unset.
803
    elseif ($value !== FALSE) {
804
805
806
807
808
      header($header_names[$name_lower] . ': ' . $value);
    }
  }
}

Dries's avatar
   
Dries committed
809
/**
810
 * Sets HTTP headers in preparation for a page response.
811
 *
812
813
814
815
 * Authenticated users are always given a 'no-cache' header, and will fetch a
 * fresh page on every request. This prevents authenticated users from seeing
 * locally cached pages.
 *
816
 * Also give each page a unique ETag. This should force clients to include both
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
 * an If-Modified-Since header and an If-None-Match header when doing
 * conditional requests for the page (required by RFC 2616, section 13.3.4),
 * making the validation more robust. This is a workaround for a bug in Mozilla
 * Firefox that is triggered when Drupal's caching is enabled and the user
 * accesses Drupal via an HTTP proxy (see
 * https://bugzilla.mozilla.org/show_bug.cgi?id=269303): When an authenticated
 * user requests a page, and then logs out and requests the same page again,
 * Firefox may send a conditional request based on the page that was cached
 * locally when the user was logged in. If this page did not have an ETag
 * header, the request only contains an If-Modified-Since header. The date will
 * be recent, because with authenticated users the Last-Modified header always
 * refers to the time of the request. If the user accesses Drupal via a proxy
 * server, and the proxy already has a cached copy of the anonymous page with an
 * older Last-Modified date, the proxy may respond with 304 Not Modified, making
 * the client think that the anonymous and authenticated pageviews are
 * identical.
833
 *
834
 * @see drupal_page_set_cache()
835
 *
836
837
 * @deprecated in Drupal 8.x-dev, will be removed before Drupal 8.0.
 *   See https://drupal.org/node/2181523.
Dries's avatar
   
Dries committed
838
 */
Dries's avatar
 
Dries committed
839
function drupal_page_header() {
840
841
842
843
844
845
846
847
848
849
850
851
852
  $headers_sent = &drupal_static(__FUNCTION__, FALSE);
  if ($headers_sent) {
    return TRUE;
  }
  $headers_sent = TRUE;

  $default_headers = array(
    'Expires' => 'Sun, 19 Nov 1978 05:00:00 GMT',
    'Last-Modified' => gmdate(DATE_RFC1123, REQUEST_TIME),
    'Cache-Control' => 'no-cache, must-revalidate, post-check=0, pre-check=0',
    'ETag' => '"' . REQUEST_TIME . '"',
  );
  drupal_send_headers($default_headers);
853
}
Dries's avatar
   
Dries committed
854

855
/**
856
 * Sets HTTP headers in preparation for a cached page response.
857
 *
858
859
 * The headers allow as much as possible in proxies and browsers without any
 * particular knowledge about the pages. Modules can override these headers
860
 * using drupal_add_http_header().
861
 *
862
863
864
865
 * If the request is conditional (using If-Modified-Since and If-None-Match),
 * and the conditions match those currently in the cache, a 304 Not Modified
 * response is sent.
 */
866
867
868
869
870
871
872
873
874
875
876
function drupal_serve_page_from_cache(Response $response, Request $request) {
  // Only allow caching in the browser and prevent that the response is stored
  // by an external proxy server when the following conditions apply:
  // 1. There is a session cookie on the request.
  // 2. The Vary: Cookie header is on the response.
  // 3. The Cache-Control header does not contain the no-cache directive.
  if ($request->cookies->has(session_name()) &&
    in_array('Cookie', $response->getVary()) &&
    !$response->headers->hasCacheControlDirective('no-cache')) {

    $response->setPrivate();
877
878
  }

879
880
881
882
  // Negotiate whether to use compression.
  if ($response->headers->get('Content-Encoding') == 'gzip' && extension_loaded('zlib')) {
    if (strpos($request->headers->get('Accept-Encoding'), 'gzip') !== FALSE) {
      // The response content is already gzip'ed, so make sure
883
      // zlib.output_compression does not compress it once more.
884
      ini_set('zlib.output_compression', '0');
885
886
    }
    else {
887
888
889
890
891
892
      // The client does not support compression. Decompress the content and
      // remove the Content-Encoding header.
      $content = $response->getContent();
      $content = gzinflate(substr(substr($content, 10), 0, -8));
      $response->setContent($content);
      $response->headers->remove('Content-Encoding');
893
    }
894
895
  }

896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
  // Perform HTTP revalidation.
  // @todo Use Response::isNotModified() as per https://drupal.org/node/2259489
  $last_modified = $response->getLastModified();
  if ($last_modified) {
    // See if the client has provided the required HTTP headers.
    $if_modified_since = $request->server->has('HTTP_IF_MODIFIED_SINCE') ? strtotime($request->server->get('HTTP_IF_MODIFIED_SINCE')) : FALSE;
    $if_none_match = $request->server->has('HTTP_IF_NONE_MATCH') ? stripslashes($request->server->get('HTTP_IF_NONE_MATCH')) : FALSE;

    if ($if_modified_since && $if_none_match
      && $if_none_match == $response->getEtag() // etag must match
      && $if_modified_since == $last_modified->getTimestamp()) {  // if-modified-since must match
      $response->setStatusCode(304);
      $response->setContent(NULL);

      // In the case of a 304 response, certain headers must be sent, and the
      // remaining may not (see RFC 2616, section 10.3.5).
      foreach (array_keys($response->headers->all()) as $name) {
        if (!in_array($name, array('content-location', 'expires', 'cache-control', 'vary'))) {
          $response->headers->remove($name);
        }
      }
    }
  }
Dries's avatar
 
Dries committed
919
920
}

921
/**
922
 * Translates a string to the current language or to a given language.
923
 *
924
925
926
 * The t() function serves two purposes. First, at run-time it translates
 * user-visible text into the appropriate language. Second, various mechanisms
 * that figure out what text needs to be translated work off t() -- the text
927
928
929
930
931
 * inside t() calls is added to the database of strings to be translated.
 * These strings are expected to be in English, so the first argument should
 * always be in English. To enable a fully-translatable site, it is important
 * that all human-readable text that will be displayed on the site or sent to
 * a user is passed through the t() function, or a related function. See the
932
933
934
935
 * @link http://drupal.org/node/322729 Localization API @endlink pages for
 * more information, including recommendations on how to break up or not
 * break up strings for translation.
 *
936
 * @section sec_translating_vars Translating Variables
937
938
939
940
941
942
943
944
945
 * You should never use t() to translate variables, such as calling
 * @code t($text); @endcode, unless the text that the variable holds has been
 * passed through t() elsewhere (e.g., $text is one of several translated
 * literal strings in an array). It is especially important never to call
 * @code t($user_text); @endcode, where $user_text is some text that a user
 * entered - doing that can lead to cross-site scripting and other security
 * problems. However, you can use variable substitution in your string, to put
 * variable text such as user names or link URLs into translated text. Variable
 * substitution looks like this:
946
 * @code
947
 * $text = t("@name's blog", array('@name' => user_format_name($account)));
948
 * @endcode
949
 * Basically, you can put variables like @name into your string, and t() will
950
951
 * substitute their sanitized values at translation time. (See the
 * Localization API pages referenced above and the documentation of
952
953
954
 * format_string() for details about how to define variables in your string.)
 * Translators can then rearrange the string as necessary for the language
 * (e.g., in Spanish, it might be "blog de @name").
955
956
957
958
 *
 * @param $string
 *   A string containing the English string to translate.
 * @param $args
959
960
961
 *   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 format_string() for details.
962
 * @param $options
963
964
965
966
967
 *   An associative array of additional options, with the following elements:
 *   - 'langcode' (defaults to the current language): The language code to
 *     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.
968
 *
969
970
 * @return
 *   The translated string.
971
 *
972
 * @see format_string()
973
 * @ingroup sanitization
974
975
 */
function t($string, array $args = array(), array $options = array()) {
976
  return \Drupal::translation()->translate($string, $args, $options);
977
978
979
}

/**
980
981
 * Formats a string for HTML display by replacing variable placeholders.
 *
982
 * @see \Drupal\Component\Utility\String::format()
983
984
985
986
 * @see t()
 * @ingroup sanitization
 */
function format_string($string, array $args = array()) {
987
  return String::format($string, $args);
988
989
}

Dries's avatar
Dries committed
990
/**
991
 * Encodes special characters in a plain-text string for display as HTML.
Gábor Hojtsy's avatar
Gábor Hojtsy committed
992
 *
993
 * @see drupal_validate_utf8()
994
 * @ingroup sanitization
995
 *
996
997
 * @deprecated in Drupal 8.x-dev, will be removed before Drupal 8.0.
 *   Use \Drupal\Component\Utility\String::checkPlain().
Dries's avatar
Dries committed
998
999
 */
function check_plain($text) {
1000
  return String::checkPlain($text);
Gábor Hojtsy's avatar
Gábor Hojtsy committed
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
}

/**
 * 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.
 *
1018
1019
 * 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
1020
1021
1022
 *
 * @param $text
 *   The text to check.
1023
 *
Gábor Hojtsy's avatar
Gábor Hojtsy committed
1024
1025
 * @return
 *   TRUE if the text is valid UTF-8, FALSE if not.
1026
1027
 *
 * @see \Drupal\Component\Utility\Unicode::validateUtf8()
Gábor Hojtsy's avatar
Gábor Hojtsy committed
1028
1029
 */
function drupal_validate_utf8($text) {
1030
  return Unicode::validateUtf8($text);
Dries's avatar
Dries committed
1031
1032
}

Dries's avatar
   
Dries committed
1033
/**
1034
1035
1036
1037
 * Returns the equivalent of Apache's $_SERVER['REQUEST_URI'] variable.
 *
 * Because $_SERVER['REQUEST_URI'] is only available on Apache, we generate an
 * equivalent using other environment variables.
1038
1039
 *
 * @todo The above comment is incorrect: http://drupal.org/node/1547294.
Dries's avatar
   
Dries committed
1040
 */
1041
function request_uri($omit_query_string = FALSE) {
1042
1043
1044
1045
  if (isset($_SERVER['REQUEST_URI'])) {
    $uri = $_SERVER['REQUEST_URI'];
  }
  else {
1046
    if (isset($_SERVER['argv'][0])) {
1047
      $uri = $_SERVER['SCRIPT_NAME'] . '?' . $_SERVER['argv'][0];
1048
    }
1049
    elseif (isset($_SERVER['QUERY_STRING'])) {
1050
      $uri = $_SERVER['SCRIPT_NAME'] . '?' . $_SERVER['QUERY_STRING'];
1051
    }
1052
1053
1054
    else {
      $uri = $_SERVER['SCRIPT_NAME'];
    }
Dries's avatar
 
Dries committed
1055
  }
1056
1057
  // Prevent multiple slashes to avoid cross site requests via the Form API.
  $uri = '/' . ltrim($uri, '/');
1058

1059
  return $omit_query_string ? strtok($uri, '?') : $uri;
Dries's avatar
 
Dries committed
1060
}
Dries's avatar
Dries committed
1061

1062
/**
1063
 * Logs an exception.
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
 *
 * This is a wrapper function for watchdog() which automatically decodes an
 * exception.
 *
 * @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
1074
 *   information about the passed-in exception is used.
1075
 * @param $variables
1076
1077
1078
 *   Array of variables to replace in the message on display or
 *   NULL if message is already translated or not possible to
 *   translate.
1079
1080
1081
1082
1083
1084
 * @param $severity
 *   The severity of the message, as per RFC 3164.
 * @param $link
 *   A link to associate with the message.
 *
 * @see watchdog()
1085
 * @see \Drupal\Core\Utility\Error::decodeException()
1086
 */
1087
function watchdog_exception($type, Exception $exception, $message = NULL, $variables = array(), $severity = WATCHDOG_ERROR, $link = NULL) {
1088
1089
1090

   // Use a default value if $message is not set.
   if (empty($message)) {
1091
1092
     // The exception message is run through
     // \Drupal\Component\Utility\String::checkPlain() by
1093
     // \Drupal\Core\Utility\Error:decodeException().
1094
     $message = '%type: !message in %function (line %line of %file).';
1095
1096
1097
1098
1099
1100
   }
   // $variables must be an array so that we can add the exception information.
   if (!is_array($variables)) {
     $variables = array();
   }

1101
   $variables += Error::decodeException($exception);
1102
1103
1104
   watchdog($type, $message, $variables, $severity, $link);
}

Dries's avatar
   
Dries committed
1105
/**
1106
 * Logs a system message.
Dries's avatar
   
Dries committed
1107
1108
 *
 * @param $type
1109
1110
 *   The category to which this message belongs. Can be any string, but the
 *   general practice is to use the name of the module calling watchdog().
Dries's avatar
   
Dries committed
1111
 * @param $message
1112
1113
1114
1115
1116
 *   The message to store in the log. Keep $message translatable
 *   by not concatenating dynamic values into it! Variables in the
 *   message should be added by using placeholder strings alongside
 *   the variables argument to declare the value of the placeholders.
 *   See t() for documentation on how $message and $variables interact.
1117
 * @param $variables
1118
1119
 *   Array of variables to replace in the message on display or array() if
 *   message is already translated or not possible to translate.
1120
 * @param $severity
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
 *   The severity of the message; one of the following values as defined in
 *   @link http://www.faqs.org/rfcs/rfc3164.html RFC 3164: @endlink
 *   - WATCHDOG_EMERGENCY: Emergency, system is unusable.
 *   - WATCHDOG_ALERT: Alert, action must be taken immediately.
 *   - WATCHDOG_CRITICAL: Critical conditions.
 *   - WATCHDOG_ERROR: Error conditions.
 *   - WATCHDOG_WARNING: Warning conditions.
 *   - WATCHDOG_NOTICE: (default) Normal but significant conditions.
 *   - WATCHDOG_INFO: Informational messages.
 *   - WATCHDOG_DEBUG: Debug-level messages.
Dries's avatar
   
Dries committed
1131
1132
 * @param $link
 *   A link to associate with the message.
1133
 *
1134
1135
1136
1137
 * @deprecated in Drupal 8.x-dev, will be removed before Drupal 8.0.
 *   Use \Drupal::logger($channel)->log($severity, $message, $context), or any
 *   of the shortcut methods of \Psr\Log\LoggerTrait.
 *
1138
 * @see watchdog_severity_levels()
1139
 * @see hook_watchdog()
Dries's avatar
   
Dries committed
1140
 */
1141
1142
1143
function watchdog($type, $message, array $variables = array(), $severity = WATCHDOG_NOTICE, $link = NULL) {
  if ($link) {
    $variables['link'] = $link;
1144
  }
1145
  \Drupal::service('logger.factory')->get($type)->log($severity, $message, $variables);
Dries's avatar
   
Dries committed
1146
1147
}

Dries's avatar
   
Dries committed
1148
/**
1149
 * Sets a message to display to the user.
Dries's avatar
   
Dries committed
1150
 *
1151
1152
 * Messages are stored in a session variable and displayed in the page template
 * via the $messages theme variable.
Dries's avatar
   
Dries committed
1153
 *
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
 * Example usage:
 * @code
 * drupal_set_message(t('An error occurred and processing did not complete.'), 'error');
 * @endcode
 *
 * @param string $message
 *   (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:
1166
 *   - 'status'
1167
 *   - 'warning'
1168
 *   - 'error'
1169
1170
 * @param bool $repeat
 *   (optional) If this is FALSE and the message is already set, then the
1171
 *   message won't be repeated. Defaults to FALSE.
1172
1173
1174
1175
1176
1177
1178
1179
 *
 * @return array|null
 *   A multidimensional array with keys corresponding to the set message types.
 *   The indexed array values of each contain the set messages for that type.
 *   Or, if there are no messages set, the function returns NULL.
 *
 * @see drupal_get_messages()
 * @see theme_status_messages()
Dries's avatar
   
Dries committed
1180
 */
1181
function drupal_set_message($message = NULL, $type = 'status', $repeat = FALSE) {
1182
  if ($message) {
Dries's avatar
   
Dries committed
1183
1184
1185
1186
    if (!isset($_SESSION['messages'][$type])) {
      $_SESSION['messages'][$type] = array();
    }