Drupal.php 18.6 KB
Newer Older
1 2 3 4 5 6 7 8
<?php

/**
 * @file
 * Contains Drupal.
 */

use Symfony\Component\DependencyInjection\ContainerInterface;
9
use Drupal\Core\Url;
10 11 12 13 14 15 16 17 18 19 20 21 22

/**
 * Static Service Container wrapper.
 *
 * Generally, code in Drupal should accept its dependencies via either
 * constructor injection or setter method injection. However, there are cases,
 * particularly in legacy procedural code, where that is infeasible. This
 * class acts as a unified global accessor to arbitrary services within the
 * system in order to ease the transition from procedural code to injected OO
 * code.
 *
 * The container is built by the kernel and passed in to this class which stores
 * it statically. The container always contains the services from
23 24
 * \Drupal\Core\CoreServiceProvider, the service providers of enabled modules and any other
 * service providers defined in $GLOBALS['conf']['container_service_providers'].
25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40
 *
 * This class exists only to support legacy code that cannot be dependency
 * injected. If your code needs it, consider refactoring it to be object
 * oriented, if possible. When this is not possible, for instance in the case of
 * hook implementations, and your code is more than a few non-reusable lines, it
 * is recommended to instantiate an object implementing the actual logic.
 *
 * @code
 *   // Legacy procedural code.
 *   function hook_do_stuff() {
 *     $lock = lock()->acquire('stuff_lock');
 *     // ...
 *   }
 *
 *   // Correct procedural code.
 *   function hook_do_stuff() {
41
 *     $lock = \Drupal::lock()->acquire('stuff_lock');
42 43 44 45 46 47
 *     // ...
 *   }
 *
 *   // The preferred way: dependency injected code.
 *   function hook_do_stuff() {
 *     // Move the actual implementation to a class and instantiate it.
48
 *     $instance = new StuffDoingClass(\Drupal::lock());
49 50 51 52 53 54
 *     $instance->doStuff();
 *
 *     // Or, even better, rely on the service container to avoid hard coding a
 *     // specific interface implementation, so that the actual logic can be
 *     // swapped. This might not always make sense, but in general it is a good
 *     // practice.
55
 *     \Drupal::service('stuff.doing')->doStuff();
56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79
 *   }
 *
 *   interface StuffDoingInterface {
 *     public function doStuff();
 *   }
 *
 *   class StuffDoingClass implements StuffDoingInterface {
 *     protected $lockBackend;
 *
 *     public function __construct(LockBackendInterface $lockBackend) {
 *       $this->lockBackend = $lockBackend;
 *     }
 *
 *     public function doStuff() {
 *       $lock = $this->lockBackend->acquire('stuff_lock');
 *       // ...
 *     }
 *   }
 * @endcode
 *
 * @see \Drupal\Core\DrupalKernel
 */
class Drupal {

80 81 82
  /**
   * The current system version.
   */
83
  const VERSION = '8.0.0-dev';
84 85 86 87 88 89

  /**
   * Core API compatibility.
   */
  const CORE_COMPATIBILITY = '8.x';

90 91 92 93 94
  /**
   * Core minimum schema version.
   */
  const CORE_MINIMUM_SCHEMA_VERSION = 8000;

95 96 97 98 99 100 101 102 103 104 105
  /**
   * The currently active container object.
   *
   * @var \Symfony\Component\DependencyInjection\ContainerInterface
   */
  protected static $container;

  /**
   * Sets a new global container.
   *
   * @param \Symfony\Component\DependencyInjection\ContainerInterface $container
106 107 108
   *   A new container instance to replace the current. NULL may be passed by
   *   testing frameworks to ensure that the global state of a previous
   *   environment does not leak into a test.
109
   */
110
  public static function setContainer(ContainerInterface $container = NULL) {
111 112 113 114 115 116
    static::$container = $container;
  }

  /**
   * Returns the currently active global container.
   *
117 118
   * @deprecated This method is only useful for the testing environment. It
   * should not be used otherwise.
119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141
   *
   * @return \Symfony\Component\DependencyInjection\ContainerInterface
   */
  public static function getContainer() {
    return static::$container;
  }

  /**
   * Retrieves a service from the container.
   *
   * Use this method if the desired service is not one of those with a dedicated
   * accessor method below. If it is listed below, those methods are preferred
   * as they can return useful type hints.
   *
   * @param string $id
   *   The ID of the service to retrieve.
   * @return mixed
   *   The specified service.
   */
  public static function service($id) {
    return static::$container->get($id);
  }

142 143 144 145 146 147 148 149 150 151 152 153 154
  /**
   * Indicates if a service is defined in the container.
   *
   * @param string $id
   *   The ID of the service to check.
   *
   * @return bool
   *   TRUE if the specified service exists, FALSE otherwise.
   */
  public static function hasService($id) {
    return static::$container && static::$container->has($id);
  }

155 156 157 158 159 160 161
  /**
   * Indicates if there is a currently active request object.
   *
   * @return bool
   *   TRUE if there is a currently active request object, FALSE otherwise.
   */
  public static function hasRequest() {
162
    return static::$container && static::$container->has('request_stack') && static::$container->get('request_stack')->getCurrentRequest() !== NULL;
163 164
  }

165 166 167
  /**
   * Retrieves the currently active request object.
   *
168
   * Note: The use of this wrapper in particular is especially discouraged. Most
169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187
   * code should not need to access the request directly.  Doing so means it
   * will only function when handling an HTTP request, and will require special
   * modification or wrapping when run from a command line tool, from certain
   * queue processors, or from automated tests.
   *
   * If code must access the request, it is considerably better to register
   * an object with the Service Container and give it a setRequest() method
   * that is configured to run when the service is created.  That way, the
   * correct request object can always be provided by the container and the
   * service can still be unit tested.
   *
   * If this method must be used, never save the request object that is
   * returned.  Doing so may lead to inconsistencies as the request object is
   * volatile and may change at various times, such as during a subrequest.
   *
   * @return \Symfony\Component\HttpFoundation\Request
   *   The currently active request object.
   */
  public static function request() {
188
    return static::$container->get('request_stack')->getCurrentRequest();
189 190
  }

191 192 193 194 195 196 197 198 199 200
  /**
   * Retrives the request stack.
   *
   * @return \Symfony\Component\HttpFoundation\RequestStack
   *   The request stack
   */
  public static function requestStack() {
    return static::$container->get('request_stack');
  }

201 202 203 204 205 206 207 208 209 210
  /**
   * Retrieves the currently active route match object.
   *
   * @return \Drupal\Core\Routing\RouteMatchInterface
   *   The currently active route match object.
   */
  public static function routeMatch() {
    return static::$container->get('current_route_match');
  }

211 212 213
  /**
   * Gets the current active user.
   *
214
   * @return \Drupal\Core\Session\AccountProxyInterface
215 216 217 218 219
   */
  public static function currentUser() {
    return static::$container->get('current_user');
  }

220 221 222
  /**
   * Retrieves the entity manager service.
   *
223
   * @return \Drupal\Core\Entity\EntityManagerInterface
224 225 226
   *   The entity manager service.
   */
  public static function entityManager() {
227
    return static::$container->get('entity.manager');
228 229
  }

230 231 232 233 234 235 236 237 238 239
  /**
   * Returns the current primary database.
   *
   * @return \Drupal\Core\Database\Connection
   *   The current active database's master connection.
   */
  public static function database() {
    return static::$container->get('database');
  }

240 241 242 243 244
  /**
   * Returns the requested cache bin.
   *
   * @param string $bin
   *   (optional) The cache bin for which the cache object should be returned,
245
   *   defaults to 'default'.
246
   *
247
   * @return \Drupal\Core\Cache\CacheBackendInterface
248
   *   The cache object associated with the specified bin.
249 250
   *
   * @ingroup cache
251
   */
252
  public static function cache($bin = 'default') {
253 254 255
    return static::$container->get('cache.' . $bin);
  }

256 257 258 259 260 261 262 263 264 265 266 267 268
  /**
   * Returns an expirable key value store collection.
   *
   * @param string $collection
   *   The name of the collection holding key and value pairs.
   *
   * @return \Drupal\Core\KeyValueStore\KeyValueStoreExpirableInterface
   *   An expirable key value store collection.
   */
  public static function keyValueExpirable($collection) {
    return static::$container->get('keyvalue.expirable')->get($collection);
  }

269 270 271 272
  /**
   * Returns the locking layer instance.
   *
   * @return \Drupal\Core\Lock\LockBackendInterface
273 274
   *
   * @ingroup lock
275 276 277 278 279
   */
  public static function lock() {
    return static::$container->get('lock');
  }

280 281 282 283
  /**
   * Retrieves a configuration object.
   *
   * This is the main entry point to the configuration API. Calling
284
   * @code \Drupal::config('book.admin') @endcode will return a configuration
285 286 287 288
   * object in which the book module can store its administrative settings.
   *
   * @param string $name
   *   The name of the configuration object to retrieve. The name corresponds to
289
   *   a configuration file. For @code \Drupal::config('book.admin') @endcode, the config
290 291 292 293 294 295 296 297 298
   *   object returned will contain the contents of book.admin configuration file.
   *
   * @return \Drupal\Core\Config\Config
   *   A configuration object.
   */
  public static function config($name) {
    return static::$container->get('config.factory')->get($name);
  }

299 300 301 302 303 304 305
  /**
   * Retrieves the configuration factory.
   *
   * This is mostly used to change the override settings on the configuration
   * factory. For example, changing the language, or turning all overrides on
   * or off.
   *
306
   * @return \Drupal\Core\Config\ConfigFactoryInterface
307
   *   The configuration factory service.
308 309 310 311 312
   */
  public static function configFactory() {
    return static::$container->get('config.factory');
  }

313 314 315
  /**
   * Returns a queue for the given queue name.
   *
316 317 318 319 320 321 322 323
   * The following values can be set in your settings.php file's $settings
   * array to define which services are used for queues:
   * - queue_reliable_service_$name: The container service to use for the
   *   reliable queue $name.
   * - queue_service_$name: The container service to use for the
   *   queue $name.
   * - queue_default: The container service to use by default for queues
   *   without overrides. This defaults to 'queue.database'.
324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341
   *
   * @param string $name
   *   The name of the queue to work with.
   * @param bool $reliable
   *   (optional) TRUE if the ordering of items and guaranteeing every item
   *   executes at least once is important, FALSE if scalability is the main
   *   concern. Defaults to FALSE.
   *
   * @return \Drupal\Core\Queue\QueueInterface
   *   The queue object for a given name.
   */
  public static function queue($name, $reliable = FALSE) {
    return static::$container->get('queue')->get($name, $reliable);
  }

  /**
   * Returns a key/value storage collection.
   *
342
   * @param string $collection
343 344 345 346 347 348 349 350 351 352 353 354 355 356 357
   *   Name of the key/value collection to return.
   *
   * @return \Drupal\Core\KeyValueStore\KeyValueStoreInterface
   */
  public static function keyValue($collection) {
    return static::$container->get('keyvalue')->get($collection);
  }

  /**
   * Returns the state storage service.
   *
   * Use this to store machine-generated data, local to a specific environment
   * that does not need deploying and does not need human editing; for example,
   * the last time cron was run. Data which needs to be edited by humans and
   * needs to be the same across development, production, etc. environments
358
   * (for example, the system maintenance message) should use \Drupal::config() instead.
359
   *
360
   * @return \Drupal\Core\State\StateInterface
361 362 363 364 365 366 367 368
   */
  public static function state() {
    return static::$container->get('state');
  }

  /**
   * Returns the default http client.
   *
369
   * @return \GuzzleHttp\ClientInterface
370 371 372
   *   A guzzle http client instance.
   */
  public static function httpClient() {
373
    return static::$container->get('http_client');
374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392
  }

  /**
   * Returns the entity query object for this entity type.
   *
   * @param string $entity_type
   *   The entity type, e.g. node, for which the query object should be
   *   returned.
   * @param string $conjunction
   *   AND if all conditions in the query need to apply, OR if any of them is
   *   enough. Optional, defaults to AND.
   *
   * @return \Drupal\Core\Entity\Query\QueryInterface
   *   The query object that can query the given entity type.
   */
  public static function entityQuery($entity_type, $conjunction = 'AND') {
    return static::$container->get('entity.query')->get($entity_type, $conjunction);
  }

393 394 395
  /**
   * Returns the entity query aggregate object for this entity type.
   *
396
   * @param string $entity_type
397 398
   *   The entity type, e.g. node, for which the query object should be
   *   returned.
399
   * @param string $conjunction
400 401 402
   *   AND if all conditions in the query need to apply, OR if any of them is
   *   enough. Optional, defaults to AND.
   *
403
   * @return \Drupal\Core\Entity\Query\QueryAggregateInterface
404 405 406 407 408 409
   *   The query object that can query the given entity type.
   */
  public static function entityQueryAggregate($entity_type, $conjunction = 'AND') {
    return static::$container->get('entity.query')->getAggregate($entity_type, $conjunction);
  }

410 411 412 413 414 415 416 417 418 419 420 421
  /**
   * Returns the flood instance.
   *
   * @return \Drupal\Core\Flood\FloodInterface
   */
  public static function flood() {
    return static::$container->get('flood');
  }

  /**
   * Returns the module handler.
   *
422
   * @return \Drupal\Core\Extension\ModuleHandlerInterface
423 424 425 426 427 428 429 430 431 432 433 434 435 436 437
   */
  public static function moduleHandler() {
    return static::$container->get('module_handler');
  }

  /**
   * Returns the typed data manager service.
   *
   * Use the typed data manager service for creating typed data objects.
   *
   * @return \Drupal\Core\TypedData\TypedDataManager
   *   The typed data manager.
   *
   * @see \Drupal\Core\TypedData\TypedDataManager::create()
   */
438 439
  public static function typedDataManager() {
    return static::$container->get('typed_data_manager');
440 441
  }

442 443 444 445 446 447 448 449 450 451
  /**
   * Returns the token service.
   *
   * @return \Drupal\Core\Utility\Token
   *   The token service.
   */
  public static function token() {
    return static::$container->get('token');
  }

452 453 454
  /**
   * Returns the url generator service.
   *
455
   * @return \Drupal\Core\Routing\UrlGeneratorInterface
456 457 458 459
   *   The url generator service.
   */
  public static function urlGenerator() {
    return static::$container->get('url_generator');
460 461
  }

462
  /**
463 464 465 466 467 468 469 470 471 472 473 474
   * Generates a URL string for a specific route based on the given parameters.
   *
   * This method is a convenience wrapper for generating URL strings for URLs
   * that have Drupal routes (that is, most pages generated by Drupal) using
   * the \Drupal\Core\Url object. See \Drupal\Core\Url::fromRoute() for
   * detailed documentation. For non-routed local URIs relative to
   * the base path (like robots.txt) use Url::fromUri()->toString() with the
   * base:// scheme.
   *
   * @see \Drupal\Core\Url
   * @see \Drupal\Core\Url::fromRoute()
   * @see \Drupal\Core\Url::fromUri()
475
   */
476
  public static function url($route_name, $route_parameters = array(), $options = array()) {
477 478 479
    return static::$container->get('url_generator')->generateFromRoute($route_name, $route_parameters, $options);
  }

480 481 482 483 484 485 486
  /**
   * Returns the link generator service.
   *
   * @return \Drupal\Core\Utility\LinkGeneratorInterface
   */
  public static function linkGenerator() {
    return static::$container->get('link_generator');
487 488 489
  }

  /**
490 491 492 493 494 495
   * Renders a link with a given link text and Url object.
   *
   * This method is a convenience wrapper for the link generator service's
   * generate() method. For detailed documentation, see
   * \Drupal\Core\Routing\LinkGeneratorInterface::generate().
   *
496
   * @see \Drupal\Core\Utility\LinkGeneratorInterface::generate()
497
   * @see \Drupal\Core\Url
498
   */
499 500
  public static function l($text, Url $url) {
    return static::$container->get('link_generator')->generate($text, $url);
501 502
  }

503 504 505
  /**
   * Returns the string translation service.
   *
506
   * @return \Drupal\Core\StringTranslation\TranslationManager
507 508 509 510 511 512
   *   The string translation manager.
   */
  public static function translation() {
    return static::$container->get('string_translation');
  }

513 514 515
  /**
   * Returns the language manager service.
   *
516
   * @return \Drupal\Core\Language\LanguageManagerInterface
517 518 519 520 521 522
   *   The language manager.
   */
  public static function languageManager() {
    return static::$container->get('language_manager');
  }

523 524 525
  /**
   * Returns the CSRF token manager service.
   *
526 527 528 529 530
   * The generated token is based on the session ID of the current user. Normally,
   * anonymous users do not have a session, so the generated token will be
   * different on every page request. To generate a token for users without a
   * session, manually start a session prior to calling this function.
   *
531 532
   * @return \Drupal\Core\Access\CsrfTokenGenerator
   *   The CSRF token manager.
533
   *
534
   * @see \Drupal\Core\Session\SessionManager::start()
535 536 537 538 539
   */
  public static function csrfToken() {
    return static::$container->get('csrf_token');
  }

540 541 542 543 544 545 546 547 548 549
  /**
   * Returns the transliteration service.
   *
   * @return \Drupal\Core\Transliteration\PHPTransliteration
   *   The transliteration manager.
   */
  public static function transliteration() {
    return static::$container->get('transliteration');
  }

550 551 552 553 554 555 556 557 558 559
  /**
   * Returns the form builder service.
   *
   * @return \Drupal\Core\Form\FormBuilderInterface
   *   The form builder.
   */
  public static function formBuilder() {
    return static::$container->get('form_builder');
  }

560 561 562 563 564 565 566 567 568
  /**
   * Gets the theme service.
   *
   * @return \Drupal\Core\Theme\ThemeManagerInterface
   */
  public static function theme() {
    return static::$container->get('theme.manager');
  }

569 570 571 572 573 574
  /**
   * Gets the syncing state.
   *
   * @return bool
   *   Returns TRUE is syncing flag set.
   */
575
  public static function isConfigSyncing() {
576 577 578
    return static::$container->get('config.installer')->isSyncing();
  }

579 580 581 582 583 584 585
  /**
   * Returns a channel logger object.
   *
   * @param string $channel
   *   The name of the channel. Can be any string, but the general practice is
   *   to use the name of the subsystem calling this.
   *
586
   * @return \Psr\Log\LoggerInterface
587 588 589 590 591 592
   *   The logger for this channel.
   */
  public static function logger($channel) {
    return static::$container->get('logger.factory')->get($channel);
  }

593 594 595 596 597 598 599 600 601 602
  /**
   * Returns the menu tree.
   *
   * @return \Drupal\Core\Menu\MenuLinkTreeInterface
   *   The menu tree.
   */
  public static function menuTree() {
    return static::$container->get('menu.link_tree');
  }

603 604 605 606 607 608 609 610 611
  /**
   * Returns the path validator.
   *
   * @return \Drupal\Core\Path\PathValidatorInterface
   */
  public static function pathValidator() {
    return static::$container->get('path.validator');
  }

612 613 614 615 616 617 618 619 620 621
  /**
   * Returns the access manager service.
   *
   * @return \Drupal\Core\Access\AccessManagerInterface
   *   The access manager service.
   */
  public static function accessManager() {
    return static::$container->get('access_manager');
  }

622
}