annotate core/lib/Drupal.php @ 19:fa3358dc1485 tip

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents af1871eacc83
children
rev   line source
Chris@0 1 <?php
Chris@0 2
Chris@0 3 /**
Chris@0 4 * @file
Chris@0 5 * Contains \Drupal.
Chris@0 6 */
Chris@0 7
Chris@0 8 use Drupal\Core\DependencyInjection\ContainerNotInitializedException;
Chris@14 9 use Drupal\Core\Messenger\LegacyMessenger;
Chris@14 10 use Drupal\Core\Url;
Chris@0 11 use Symfony\Component\DependencyInjection\ContainerInterface;
Chris@0 12
Chris@0 13 /**
Chris@0 14 * Static Service Container wrapper.
Chris@0 15 *
Chris@0 16 * Generally, code in Drupal should accept its dependencies via either
Chris@0 17 * constructor injection or setter method injection. However, there are cases,
Chris@0 18 * particularly in legacy procedural code, where that is infeasible. This
Chris@0 19 * class acts as a unified global accessor to arbitrary services within the
Chris@0 20 * system in order to ease the transition from procedural code to injected OO
Chris@0 21 * code.
Chris@0 22 *
Chris@0 23 * The container is built by the kernel and passed in to this class which stores
Chris@0 24 * it statically. The container always contains the services from
Chris@0 25 * \Drupal\Core\CoreServiceProvider, the service providers of enabled modules and any other
Chris@0 26 * service providers defined in $GLOBALS['conf']['container_service_providers'].
Chris@0 27 *
Chris@0 28 * This class exists only to support legacy code that cannot be dependency
Chris@0 29 * injected. If your code needs it, consider refactoring it to be object
Chris@0 30 * oriented, if possible. When this is not possible, for instance in the case of
Chris@0 31 * hook implementations, and your code is more than a few non-reusable lines, it
Chris@0 32 * is recommended to instantiate an object implementing the actual logic.
Chris@0 33 *
Chris@0 34 * @code
Chris@0 35 * // Legacy procedural code.
Chris@0 36 * function hook_do_stuff() {
Chris@0 37 * $lock = lock()->acquire('stuff_lock');
Chris@0 38 * // ...
Chris@0 39 * }
Chris@0 40 *
Chris@0 41 * // Correct procedural code.
Chris@0 42 * function hook_do_stuff() {
Chris@0 43 * $lock = \Drupal::lock()->acquire('stuff_lock');
Chris@0 44 * // ...
Chris@0 45 * }
Chris@0 46 *
Chris@0 47 * // The preferred way: dependency injected code.
Chris@0 48 * function hook_do_stuff() {
Chris@0 49 * // Move the actual implementation to a class and instantiate it.
Chris@0 50 * $instance = new StuffDoingClass(\Drupal::lock());
Chris@0 51 * $instance->doStuff();
Chris@0 52 *
Chris@0 53 * // Or, even better, rely on the service container to avoid hard coding a
Chris@0 54 * // specific interface implementation, so that the actual logic can be
Chris@0 55 * // swapped. This might not always make sense, but in general it is a good
Chris@0 56 * // practice.
Chris@0 57 * \Drupal::service('stuff.doing')->doStuff();
Chris@0 58 * }
Chris@0 59 *
Chris@0 60 * interface StuffDoingInterface {
Chris@0 61 * public function doStuff();
Chris@0 62 * }
Chris@0 63 *
Chris@0 64 * class StuffDoingClass implements StuffDoingInterface {
Chris@0 65 * protected $lockBackend;
Chris@0 66 *
Chris@0 67 * public function __construct(LockBackendInterface $lock_backend) {
Chris@0 68 * $this->lockBackend = $lock_backend;
Chris@0 69 * }
Chris@0 70 *
Chris@0 71 * public function doStuff() {
Chris@0 72 * $lock = $this->lockBackend->acquire('stuff_lock');
Chris@0 73 * // ...
Chris@0 74 * }
Chris@0 75 * }
Chris@0 76 * @endcode
Chris@0 77 *
Chris@0 78 * @see \Drupal\Core\DrupalKernel
Chris@0 79 */
Chris@0 80 class Drupal {
Chris@0 81
Chris@0 82 /**
Chris@0 83 * The current system version.
Chris@0 84 */
Chris@18 85 const VERSION = '8.7.1';
Chris@0 86
Chris@0 87 /**
Chris@0 88 * Core API compatibility.
Chris@0 89 */
Chris@0 90 const CORE_COMPATIBILITY = '8.x';
Chris@0 91
Chris@0 92 /**
Chris@0 93 * Core minimum schema version.
Chris@0 94 */
Chris@0 95 const CORE_MINIMUM_SCHEMA_VERSION = 8000;
Chris@0 96
Chris@0 97 /**
Chris@0 98 * The currently active container object, or NULL if not initialized yet.
Chris@0 99 *
Chris@0 100 * @var \Symfony\Component\DependencyInjection\ContainerInterface|null
Chris@0 101 */
Chris@0 102 protected static $container;
Chris@0 103
Chris@0 104 /**
Chris@0 105 * Sets a new global container.
Chris@0 106 *
Chris@0 107 * @param \Symfony\Component\DependencyInjection\ContainerInterface $container
Chris@0 108 * A new container instance to replace the current.
Chris@0 109 */
Chris@0 110 public static function setContainer(ContainerInterface $container) {
Chris@0 111 static::$container = $container;
Chris@0 112 }
Chris@0 113
Chris@0 114 /**
Chris@0 115 * Unsets the global container.
Chris@0 116 */
Chris@0 117 public static function unsetContainer() {
Chris@0 118 static::$container = NULL;
Chris@0 119 }
Chris@0 120
Chris@0 121 /**
Chris@0 122 * Returns the currently active global container.
Chris@0 123 *
Chris@0 124 * @return \Symfony\Component\DependencyInjection\ContainerInterface|null
Chris@0 125 *
Chris@0 126 * @throws \Drupal\Core\DependencyInjection\ContainerNotInitializedException
Chris@0 127 */
Chris@0 128 public static function getContainer() {
Chris@0 129 if (static::$container === NULL) {
Chris@0 130 throw new ContainerNotInitializedException('\Drupal::$container is not initialized yet. \Drupal::setContainer() must be called with a real container.');
Chris@0 131 }
Chris@0 132 return static::$container;
Chris@0 133 }
Chris@0 134
Chris@0 135 /**
Chris@0 136 * Returns TRUE if the container has been initialized, FALSE otherwise.
Chris@0 137 *
Chris@0 138 * @return bool
Chris@0 139 */
Chris@0 140 public static function hasContainer() {
Chris@0 141 return static::$container !== NULL;
Chris@0 142 }
Chris@0 143
Chris@0 144 /**
Chris@0 145 * Retrieves a service from the container.
Chris@0 146 *
Chris@0 147 * Use this method if the desired service is not one of those with a dedicated
Chris@0 148 * accessor method below. If it is listed below, those methods are preferred
Chris@0 149 * as they can return useful type hints.
Chris@0 150 *
Chris@0 151 * @param string $id
Chris@0 152 * The ID of the service to retrieve.
Chris@0 153 *
Chris@0 154 * @return mixed
Chris@0 155 * The specified service.
Chris@0 156 */
Chris@0 157 public static function service($id) {
Chris@0 158 return static::getContainer()->get($id);
Chris@0 159 }
Chris@0 160
Chris@0 161 /**
Chris@0 162 * Indicates if a service is defined in the container.
Chris@0 163 *
Chris@0 164 * @param string $id
Chris@0 165 * The ID of the service to check.
Chris@0 166 *
Chris@0 167 * @return bool
Chris@0 168 * TRUE if the specified service exists, FALSE otherwise.
Chris@0 169 */
Chris@0 170 public static function hasService($id) {
Chris@0 171 // Check hasContainer() first in order to always return a Boolean.
Chris@0 172 return static::hasContainer() && static::getContainer()->has($id);
Chris@0 173 }
Chris@0 174
Chris@0 175 /**
Chris@0 176 * Gets the app root.
Chris@0 177 *
Chris@0 178 * @return string
Chris@0 179 */
Chris@0 180 public static function root() {
Chris@0 181 return static::getContainer()->get('app.root');
Chris@0 182 }
Chris@0 183
Chris@0 184 /**
Chris@0 185 * Gets the active install profile.
Chris@0 186 *
Chris@0 187 * @return string|null
Chris@0 188 * The name of the active install profile.
Chris@0 189 */
Chris@0 190 public static function installProfile() {
Chris@0 191 return static::getContainer()->getParameter('install_profile');
Chris@0 192 }
Chris@0 193
Chris@0 194 /**
Chris@0 195 * Indicates if there is a currently active request object.
Chris@0 196 *
Chris@0 197 * @return bool
Chris@0 198 * TRUE if there is a currently active request object, FALSE otherwise.
Chris@0 199 */
Chris@0 200 public static function hasRequest() {
Chris@0 201 // Check hasContainer() first in order to always return a Boolean.
Chris@0 202 return static::hasContainer() && static::getContainer()->has('request_stack') && static::getContainer()->get('request_stack')->getCurrentRequest() !== NULL;
Chris@0 203 }
Chris@0 204
Chris@0 205 /**
Chris@0 206 * Retrieves the currently active request object.
Chris@0 207 *
Chris@0 208 * Note: The use of this wrapper in particular is especially discouraged. Most
Chris@0 209 * code should not need to access the request directly. Doing so means it
Chris@0 210 * will only function when handling an HTTP request, and will require special
Chris@0 211 * modification or wrapping when run from a command line tool, from certain
Chris@0 212 * queue processors, or from automated tests.
Chris@0 213 *
Chris@0 214 * If code must access the request, it is considerably better to register
Chris@0 215 * an object with the Service Container and give it a setRequest() method
Chris@0 216 * that is configured to run when the service is created. That way, the
Chris@0 217 * correct request object can always be provided by the container and the
Chris@0 218 * service can still be unit tested.
Chris@0 219 *
Chris@0 220 * If this method must be used, never save the request object that is
Chris@0 221 * returned. Doing so may lead to inconsistencies as the request object is
Chris@0 222 * volatile and may change at various times, such as during a subrequest.
Chris@0 223 *
Chris@0 224 * @return \Symfony\Component\HttpFoundation\Request
Chris@0 225 * The currently active request object.
Chris@0 226 */
Chris@0 227 public static function request() {
Chris@0 228 return static::getContainer()->get('request_stack')->getCurrentRequest();
Chris@0 229 }
Chris@0 230
Chris@0 231 /**
Chris@17 232 * Retrieves the request stack.
Chris@0 233 *
Chris@0 234 * @return \Symfony\Component\HttpFoundation\RequestStack
Chris@0 235 * The request stack
Chris@0 236 */
Chris@0 237 public static function requestStack() {
Chris@0 238 return static::getContainer()->get('request_stack');
Chris@0 239 }
Chris@0 240
Chris@0 241 /**
Chris@0 242 * Retrieves the currently active route match object.
Chris@0 243 *
Chris@0 244 * @return \Drupal\Core\Routing\RouteMatchInterface
Chris@0 245 * The currently active route match object.
Chris@0 246 */
Chris@0 247 public static function routeMatch() {
Chris@0 248 return static::getContainer()->get('current_route_match');
Chris@0 249 }
Chris@0 250
Chris@0 251 /**
Chris@0 252 * Gets the current active user.
Chris@0 253 *
Chris@0 254 * @return \Drupal\Core\Session\AccountProxyInterface
Chris@0 255 */
Chris@0 256 public static function currentUser() {
Chris@0 257 return static::getContainer()->get('current_user');
Chris@0 258 }
Chris@0 259
Chris@0 260 /**
Chris@0 261 * Retrieves the entity manager service.
Chris@0 262 *
Chris@0 263 * @return \Drupal\Core\Entity\EntityManagerInterface
Chris@0 264 * The entity manager service.
Chris@0 265 *
Chris@0 266 * @deprecated in Drupal 8.0.0 and will be removed before Drupal 9.0.0.
Chris@0 267 * Use \Drupal::entityTypeManager() instead in most cases. If the needed
Chris@0 268 * method is not on \Drupal\Core\Entity\EntityTypeManagerInterface, see the
Chris@0 269 * deprecated \Drupal\Core\Entity\EntityManager to find the
Chris@0 270 * correct interface or service.
Chris@0 271 */
Chris@0 272 public static function entityManager() {
Chris@0 273 return static::getContainer()->get('entity.manager');
Chris@0 274 }
Chris@0 275
Chris@0 276 /**
Chris@0 277 * Retrieves the entity type manager.
Chris@0 278 *
Chris@0 279 * @return \Drupal\Core\Entity\EntityTypeManagerInterface
Chris@0 280 * The entity type manager.
Chris@0 281 */
Chris@0 282 public static function entityTypeManager() {
Chris@0 283 return static::getContainer()->get('entity_type.manager');
Chris@0 284 }
Chris@0 285
Chris@0 286 /**
Chris@0 287 * Returns the current primary database.
Chris@0 288 *
Chris@0 289 * @return \Drupal\Core\Database\Connection
Chris@0 290 * The current active database's master connection.
Chris@0 291 */
Chris@0 292 public static function database() {
Chris@0 293 return static::getContainer()->get('database');
Chris@0 294 }
Chris@0 295
Chris@0 296 /**
Chris@0 297 * Returns the requested cache bin.
Chris@0 298 *
Chris@0 299 * @param string $bin
Chris@0 300 * (optional) The cache bin for which the cache object should be returned,
Chris@0 301 * defaults to 'default'.
Chris@0 302 *
Chris@0 303 * @return \Drupal\Core\Cache\CacheBackendInterface
Chris@0 304 * The cache object associated with the specified bin.
Chris@0 305 *
Chris@0 306 * @ingroup cache
Chris@0 307 */
Chris@0 308 public static function cache($bin = 'default') {
Chris@0 309 return static::getContainer()->get('cache.' . $bin);
Chris@0 310 }
Chris@0 311
Chris@0 312 /**
Chris@0 313 * Retrieves the class resolver.
Chris@0 314 *
Chris@0 315 * This is to be used in procedural code such as module files to instantiate
Chris@0 316 * an object of a class that implements
Chris@0 317 * \Drupal\Core\DependencyInjection\ContainerInjectionInterface.
Chris@0 318 *
Chris@0 319 * One common usecase is to provide a class which contains the actual code
Chris@0 320 * of a hook implementation, without having to create a service.
Chris@0 321 *
Chris@17 322 * @param string $class
Chris@17 323 * (optional) A class name to instantiate.
Chris@17 324 *
Chris@17 325 * @return \Drupal\Core\DependencyInjection\ClassResolverInterface|object
Chris@17 326 * The class resolver or if $class is provided, a class instance with a
Chris@17 327 * given class definition.
Chris@17 328 *
Chris@17 329 * @throws \InvalidArgumentException
Chris@17 330 * If $class does not exist.
Chris@0 331 */
Chris@17 332 public static function classResolver($class = NULL) {
Chris@17 333 if ($class) {
Chris@17 334 return static::getContainer()->get('class_resolver')->getInstanceFromDefinition($class);
Chris@17 335 }
Chris@0 336 return static::getContainer()->get('class_resolver');
Chris@0 337 }
Chris@0 338
Chris@0 339 /**
Chris@0 340 * Returns an expirable key value store collection.
Chris@0 341 *
Chris@0 342 * @param string $collection
Chris@0 343 * The name of the collection holding key and value pairs.
Chris@0 344 *
Chris@0 345 * @return \Drupal\Core\KeyValueStore\KeyValueStoreExpirableInterface
Chris@0 346 * An expirable key value store collection.
Chris@0 347 */
Chris@0 348 public static function keyValueExpirable($collection) {
Chris@0 349 return static::getContainer()->get('keyvalue.expirable')->get($collection);
Chris@0 350 }
Chris@0 351
Chris@0 352 /**
Chris@0 353 * Returns the locking layer instance.
Chris@0 354 *
Chris@0 355 * @return \Drupal\Core\Lock\LockBackendInterface
Chris@0 356 *
Chris@0 357 * @ingroup lock
Chris@0 358 */
Chris@0 359 public static function lock() {
Chris@0 360 return static::getContainer()->get('lock');
Chris@0 361 }
Chris@0 362
Chris@0 363 /**
Chris@0 364 * Retrieves a configuration object.
Chris@0 365 *
Chris@0 366 * This is the main entry point to the configuration API. Calling
Chris@0 367 * @code \Drupal::config('book.admin') @endcode will return a configuration
Chris@0 368 * object in which the book module can store its administrative settings.
Chris@0 369 *
Chris@0 370 * @param string $name
Chris@0 371 * The name of the configuration object to retrieve. The name corresponds to
Chris@0 372 * a configuration file. For @code \Drupal::config('book.admin') @endcode, the config
Chris@0 373 * object returned will contain the contents of book.admin configuration file.
Chris@0 374 *
Chris@0 375 * @return \Drupal\Core\Config\ImmutableConfig
Chris@0 376 * An immutable configuration object.
Chris@0 377 */
Chris@0 378 public static function config($name) {
Chris@0 379 return static::getContainer()->get('config.factory')->get($name);
Chris@0 380 }
Chris@0 381
Chris@0 382 /**
Chris@0 383 * Retrieves the configuration factory.
Chris@0 384 *
Chris@0 385 * This is mostly used to change the override settings on the configuration
Chris@0 386 * factory. For example, changing the language, or turning all overrides on
Chris@0 387 * or off.
Chris@0 388 *
Chris@0 389 * @return \Drupal\Core\Config\ConfigFactoryInterface
Chris@0 390 * The configuration factory service.
Chris@0 391 */
Chris@0 392 public static function configFactory() {
Chris@0 393 return static::getContainer()->get('config.factory');
Chris@0 394 }
Chris@0 395
Chris@0 396 /**
Chris@0 397 * Returns a queue for the given queue name.
Chris@0 398 *
Chris@0 399 * The following values can be set in your settings.php file's $settings
Chris@0 400 * array to define which services are used for queues:
Chris@0 401 * - queue_reliable_service_$name: The container service to use for the
Chris@0 402 * reliable queue $name.
Chris@0 403 * - queue_service_$name: The container service to use for the
Chris@0 404 * queue $name.
Chris@0 405 * - queue_default: The container service to use by default for queues
Chris@0 406 * without overrides. This defaults to 'queue.database'.
Chris@0 407 *
Chris@0 408 * @param string $name
Chris@0 409 * The name of the queue to work with.
Chris@0 410 * @param bool $reliable
Chris@0 411 * (optional) TRUE if the ordering of items and guaranteeing every item
Chris@0 412 * executes at least once is important, FALSE if scalability is the main
Chris@0 413 * concern. Defaults to FALSE.
Chris@0 414 *
Chris@0 415 * @return \Drupal\Core\Queue\QueueInterface
Chris@0 416 * The queue object for a given name.
Chris@0 417 */
Chris@0 418 public static function queue($name, $reliable = FALSE) {
Chris@0 419 return static::getContainer()->get('queue')->get($name, $reliable);
Chris@0 420 }
Chris@0 421
Chris@0 422 /**
Chris@0 423 * Returns a key/value storage collection.
Chris@0 424 *
Chris@0 425 * @param string $collection
Chris@0 426 * Name of the key/value collection to return.
Chris@0 427 *
Chris@0 428 * @return \Drupal\Core\KeyValueStore\KeyValueStoreInterface
Chris@0 429 */
Chris@0 430 public static function keyValue($collection) {
Chris@0 431 return static::getContainer()->get('keyvalue')->get($collection);
Chris@0 432 }
Chris@0 433
Chris@0 434 /**
Chris@0 435 * Returns the state storage service.
Chris@0 436 *
Chris@0 437 * Use this to store machine-generated data, local to a specific environment
Chris@0 438 * that does not need deploying and does not need human editing; for example,
Chris@0 439 * the last time cron was run. Data which needs to be edited by humans and
Chris@0 440 * needs to be the same across development, production, etc. environments
Chris@0 441 * (for example, the system maintenance message) should use \Drupal::config() instead.
Chris@0 442 *
Chris@0 443 * @return \Drupal\Core\State\StateInterface
Chris@0 444 */
Chris@0 445 public static function state() {
Chris@0 446 return static::getContainer()->get('state');
Chris@0 447 }
Chris@0 448
Chris@0 449 /**
Chris@0 450 * Returns the default http client.
Chris@0 451 *
Chris@0 452 * @return \GuzzleHttp\Client
Chris@0 453 * A guzzle http client instance.
Chris@0 454 */
Chris@0 455 public static function httpClient() {
Chris@0 456 return static::getContainer()->get('http_client');
Chris@0 457 }
Chris@0 458
Chris@0 459 /**
Chris@0 460 * Returns the entity query object for this entity type.
Chris@0 461 *
Chris@0 462 * @param string $entity_type
Chris@0 463 * The entity type (for example, node) for which the query object should be
Chris@0 464 * returned.
Chris@0 465 * @param string $conjunction
Chris@0 466 * (optional) Either 'AND' if all conditions in the query need to apply, or
Chris@0 467 * 'OR' if any of them is sufficient. Defaults to 'AND'.
Chris@0 468 *
Chris@0 469 * @return \Drupal\Core\Entity\Query\QueryInterface
Chris@0 470 * The query object that can query the given entity type.
Chris@0 471 */
Chris@0 472 public static function entityQuery($entity_type, $conjunction = 'AND') {
Chris@0 473 return static::entityTypeManager()->getStorage($entity_type)->getQuery($conjunction);
Chris@0 474 }
Chris@0 475
Chris@0 476 /**
Chris@0 477 * Returns the entity query aggregate object for this entity type.
Chris@0 478 *
Chris@0 479 * @param string $entity_type
Chris@0 480 * The entity type (for example, node) for which the query object should be
Chris@0 481 * returned.
Chris@0 482 * @param string $conjunction
Chris@0 483 * (optional) Either 'AND' if all conditions in the query need to apply, or
Chris@0 484 * 'OR' if any of them is sufficient. Defaults to 'AND'.
Chris@0 485 *
Chris@0 486 * @return \Drupal\Core\Entity\Query\QueryAggregateInterface
Chris@0 487 * The query object that can query the given entity type.
Chris@0 488 */
Chris@0 489 public static function entityQueryAggregate($entity_type, $conjunction = 'AND') {
Chris@0 490 return static::entityTypeManager()->getStorage($entity_type)->getAggregateQuery($conjunction);
Chris@0 491 }
Chris@0 492
Chris@0 493 /**
Chris@0 494 * Returns the flood instance.
Chris@0 495 *
Chris@0 496 * @return \Drupal\Core\Flood\FloodInterface
Chris@0 497 */
Chris@0 498 public static function flood() {
Chris@0 499 return static::getContainer()->get('flood');
Chris@0 500 }
Chris@0 501
Chris@0 502 /**
Chris@0 503 * Returns the module handler.
Chris@0 504 *
Chris@0 505 * @return \Drupal\Core\Extension\ModuleHandlerInterface
Chris@0 506 */
Chris@0 507 public static function moduleHandler() {
Chris@0 508 return static::getContainer()->get('module_handler');
Chris@0 509 }
Chris@0 510
Chris@0 511 /**
Chris@0 512 * Returns the typed data manager service.
Chris@0 513 *
Chris@0 514 * Use the typed data manager service for creating typed data objects.
Chris@0 515 *
Chris@0 516 * @return \Drupal\Core\TypedData\TypedDataManagerInterface
Chris@0 517 * The typed data manager.
Chris@0 518 *
Chris@0 519 * @see \Drupal\Core\TypedData\TypedDataManager::create()
Chris@0 520 */
Chris@0 521 public static function typedDataManager() {
Chris@0 522 return static::getContainer()->get('typed_data_manager');
Chris@0 523 }
Chris@0 524
Chris@0 525 /**
Chris@0 526 * Returns the token service.
Chris@0 527 *
Chris@0 528 * @return \Drupal\Core\Utility\Token
Chris@0 529 * The token service.
Chris@0 530 */
Chris@0 531 public static function token() {
Chris@0 532 return static::getContainer()->get('token');
Chris@0 533 }
Chris@0 534
Chris@0 535 /**
Chris@0 536 * Returns the url generator service.
Chris@0 537 *
Chris@0 538 * @return \Drupal\Core\Routing\UrlGeneratorInterface
Chris@0 539 * The url generator service.
Chris@0 540 */
Chris@0 541 public static function urlGenerator() {
Chris@0 542 return static::getContainer()->get('url_generator');
Chris@0 543 }
Chris@0 544
Chris@0 545 /**
Chris@0 546 * Generates a URL string for a specific route based on the given parameters.
Chris@0 547 *
Chris@0 548 * This method is a convenience wrapper for generating URL strings for URLs
Chris@0 549 * that have Drupal routes (that is, most pages generated by Drupal) using
Chris@0 550 * the \Drupal\Core\Url object. See \Drupal\Core\Url::fromRoute() for
Chris@0 551 * detailed documentation. For non-routed local URIs relative to
Chris@0 552 * the base path (like robots.txt) use Url::fromUri()->toString() with the
Chris@0 553 * base: scheme.
Chris@0 554 *
Chris@0 555 * @param string $route_name
Chris@0 556 * The name of the route.
Chris@0 557 * @param array $route_parameters
Chris@0 558 * (optional) An associative array of parameter names and values.
Chris@0 559 * @param array $options
Chris@0 560 * (optional) An associative array of additional options.
Chris@0 561 * @param bool $collect_bubbleable_metadata
Chris@0 562 * (optional) Defaults to FALSE. When TRUE, both the generated URL and its
Chris@0 563 * associated bubbleable metadata are returned.
Chris@0 564 *
Chris@0 565 * @return string|\Drupal\Core\GeneratedUrl
Chris@0 566 * A string containing a URL to the given path.
Chris@0 567 * When $collect_bubbleable_metadata is TRUE, a GeneratedUrl object is
Chris@0 568 * returned, containing the generated URL plus bubbleable metadata.
Chris@0 569 *
Chris@0 570 * @see \Drupal\Core\Routing\UrlGeneratorInterface::generateFromRoute()
Chris@0 571 * @see \Drupal\Core\Url
Chris@0 572 * @see \Drupal\Core\Url::fromRoute()
Chris@0 573 * @see \Drupal\Core\Url::fromUri()
Chris@0 574 *
Chris@0 575 * @deprecated as of Drupal 8.0.x, will be removed before Drupal 9.0.0.
Chris@0 576 * Instead create a \Drupal\Core\Url object directly, for example using
Chris@0 577 * Url::fromRoute().
Chris@0 578 */
Chris@0 579 public static function url($route_name, $route_parameters = [], $options = [], $collect_bubbleable_metadata = FALSE) {
Chris@18 580 @trigger_error('Drupal::url() is deprecated as of Drupal 8.0.x, will be removed before Drupal 9.0.0. Instead create a \Drupal\Core\Url object directly, for example using Url::fromRoute()', E_USER_DEPRECATED);
Chris@0 581 return static::getContainer()->get('url_generator')->generateFromRoute($route_name, $route_parameters, $options, $collect_bubbleable_metadata);
Chris@0 582 }
Chris@0 583
Chris@0 584 /**
Chris@0 585 * Returns the link generator service.
Chris@0 586 *
Chris@0 587 * @return \Drupal\Core\Utility\LinkGeneratorInterface
Chris@0 588 */
Chris@0 589 public static function linkGenerator() {
Chris@0 590 return static::getContainer()->get('link_generator');
Chris@0 591 }
Chris@0 592
Chris@0 593 /**
Chris@0 594 * Renders a link with a given link text and Url object.
Chris@0 595 *
Chris@0 596 * This method is a convenience wrapper for the link generator service's
Chris@0 597 * generate() method.
Chris@0 598 *
Chris@0 599 * @param string $text
Chris@0 600 * The link text for the anchor tag.
Chris@0 601 * @param \Drupal\Core\Url $url
Chris@0 602 * The URL object used for the link.
Chris@0 603 *
Chris@0 604 * @return \Drupal\Core\GeneratedLink
Chris@0 605 * A GeneratedLink object containing a link to the given route and
Chris@0 606 * parameters and bubbleable metadata.
Chris@0 607 *
Chris@0 608 * @see \Drupal\Core\Utility\LinkGeneratorInterface::generate()
Chris@0 609 * @see \Drupal\Core\Url
Chris@0 610 *
Chris@0 611 * @deprecated in Drupal 8.0.0 and will be removed before Drupal 9.0.0.
Chris@0 612 * Use \Drupal\Core\Link instead.
Chris@0 613 * Example:
Chris@0 614 * @code
Chris@0 615 * $link = Link::fromTextAndUrl($text, $url);
Chris@0 616 * @endcode
Chris@0 617 */
Chris@0 618 public static function l($text, Url $url) {
Chris@0 619 return static::getContainer()->get('link_generator')->generate($text, $url);
Chris@0 620 }
Chris@0 621
Chris@0 622 /**
Chris@0 623 * Returns the string translation service.
Chris@0 624 *
Chris@0 625 * @return \Drupal\Core\StringTranslation\TranslationManager
Chris@0 626 * The string translation manager.
Chris@0 627 */
Chris@0 628 public static function translation() {
Chris@0 629 return static::getContainer()->get('string_translation');
Chris@0 630 }
Chris@0 631
Chris@0 632 /**
Chris@0 633 * Returns the language manager service.
Chris@0 634 *
Chris@0 635 * @return \Drupal\Core\Language\LanguageManagerInterface
Chris@0 636 * The language manager.
Chris@0 637 */
Chris@0 638 public static function languageManager() {
Chris@0 639 return static::getContainer()->get('language_manager');
Chris@0 640 }
Chris@0 641
Chris@0 642 /**
Chris@0 643 * Returns the CSRF token manager service.
Chris@0 644 *
Chris@0 645 * The generated token is based on the session ID of the current user. Normally,
Chris@0 646 * anonymous users do not have a session, so the generated token will be
Chris@0 647 * different on every page request. To generate a token for users without a
Chris@0 648 * session, manually start a session prior to calling this function.
Chris@0 649 *
Chris@0 650 * @return \Drupal\Core\Access\CsrfTokenGenerator
Chris@0 651 * The CSRF token manager.
Chris@0 652 *
Chris@0 653 * @see \Drupal\Core\Session\SessionManager::start()
Chris@0 654 */
Chris@0 655 public static function csrfToken() {
Chris@0 656 return static::getContainer()->get('csrf_token');
Chris@0 657 }
Chris@0 658
Chris@0 659 /**
Chris@0 660 * Returns the transliteration service.
Chris@0 661 *
Chris@0 662 * @return \Drupal\Core\Transliteration\PhpTransliteration
Chris@0 663 * The transliteration manager.
Chris@0 664 */
Chris@0 665 public static function transliteration() {
Chris@0 666 return static::getContainer()->get('transliteration');
Chris@0 667 }
Chris@0 668
Chris@0 669 /**
Chris@0 670 * Returns the form builder service.
Chris@0 671 *
Chris@0 672 * @return \Drupal\Core\Form\FormBuilderInterface
Chris@0 673 * The form builder.
Chris@0 674 */
Chris@0 675 public static function formBuilder() {
Chris@0 676 return static::getContainer()->get('form_builder');
Chris@0 677 }
Chris@0 678
Chris@0 679 /**
Chris@0 680 * Gets the theme service.
Chris@0 681 *
Chris@0 682 * @return \Drupal\Core\Theme\ThemeManagerInterface
Chris@0 683 */
Chris@0 684 public static function theme() {
Chris@0 685 return static::getContainer()->get('theme.manager');
Chris@0 686 }
Chris@0 687
Chris@0 688 /**
Chris@0 689 * Gets the syncing state.
Chris@0 690 *
Chris@0 691 * @return bool
Chris@0 692 * Returns TRUE is syncing flag set.
Chris@0 693 */
Chris@0 694 public static function isConfigSyncing() {
Chris@0 695 return static::getContainer()->get('config.installer')->isSyncing();
Chris@0 696 }
Chris@0 697
Chris@0 698 /**
Chris@0 699 * Returns a channel logger object.
Chris@0 700 *
Chris@0 701 * @param string $channel
Chris@0 702 * The name of the channel. Can be any string, but the general practice is
Chris@0 703 * to use the name of the subsystem calling this.
Chris@0 704 *
Chris@0 705 * @return \Psr\Log\LoggerInterface
Chris@0 706 * The logger for this channel.
Chris@0 707 */
Chris@0 708 public static function logger($channel) {
Chris@0 709 return static::getContainer()->get('logger.factory')->get($channel);
Chris@0 710 }
Chris@0 711
Chris@0 712 /**
Chris@0 713 * Returns the menu tree.
Chris@0 714 *
Chris@0 715 * @return \Drupal\Core\Menu\MenuLinkTreeInterface
Chris@0 716 * The menu tree.
Chris@0 717 */
Chris@0 718 public static function menuTree() {
Chris@0 719 return static::getContainer()->get('menu.link_tree');
Chris@0 720 }
Chris@0 721
Chris@0 722 /**
Chris@0 723 * Returns the path validator.
Chris@0 724 *
Chris@0 725 * @return \Drupal\Core\Path\PathValidatorInterface
Chris@0 726 */
Chris@0 727 public static function pathValidator() {
Chris@0 728 return static::getContainer()->get('path.validator');
Chris@0 729 }
Chris@0 730
Chris@0 731 /**
Chris@0 732 * Returns the access manager service.
Chris@0 733 *
Chris@0 734 * @return \Drupal\Core\Access\AccessManagerInterface
Chris@0 735 * The access manager service.
Chris@0 736 */
Chris@0 737 public static function accessManager() {
Chris@0 738 return static::getContainer()->get('access_manager');
Chris@0 739 }
Chris@0 740
Chris@0 741 /**
Chris@0 742 * Returns the redirect destination helper.
Chris@0 743 *
Chris@0 744 * @return \Drupal\Core\Routing\RedirectDestinationInterface
Chris@0 745 * The redirect destination helper.
Chris@0 746 */
Chris@0 747 public static function destination() {
Chris@0 748 return static::getContainer()->get('redirect.destination');
Chris@0 749 }
Chris@0 750
Chris@0 751 /**
Chris@0 752 * Returns the entity definition update manager.
Chris@0 753 *
Chris@0 754 * @return \Drupal\Core\Entity\EntityDefinitionUpdateManagerInterface
Chris@0 755 * The entity definition update manager.
Chris@0 756 */
Chris@0 757 public static function entityDefinitionUpdateManager() {
Chris@0 758 return static::getContainer()->get('entity.definition_update_manager');
Chris@0 759 }
Chris@0 760
Chris@0 761 /**
Chris@0 762 * Returns the time service.
Chris@0 763 *
Chris@0 764 * @return \Drupal\Component\Datetime\TimeInterface
Chris@0 765 * The time service.
Chris@0 766 */
Chris@0 767 public static function time() {
Chris@0 768 return static::getContainer()->get('datetime.time');
Chris@0 769 }
Chris@0 770
Chris@14 771 /**
Chris@14 772 * Returns the messenger.
Chris@14 773 *
Chris@14 774 * @return \Drupal\Core\Messenger\MessengerInterface
Chris@14 775 * The messenger.
Chris@14 776 */
Chris@14 777 public static function messenger() {
Chris@14 778 // @todo Replace with service once LegacyMessenger is removed in 9.0.0.
Chris@14 779 // @see https://www.drupal.org/node/2928994
Chris@14 780 return new LegacyMessenger();
Chris@14 781 }
Chris@14 782
Chris@0 783 }