annotate core/modules/language/src/LanguageNegotiatorInterface.php @ 19:fa3358dc1485 tip

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents 4c8ae668cc8c
children
rev   line source
Chris@0 1 <?php
Chris@0 2
Chris@0 3 namespace Drupal\language;
Chris@0 4
Chris@0 5 use Drupal\Core\Session\AccountInterface;
Chris@0 6
Chris@0 7 /**
Chris@0 8 * Common interface for language negotiation services.
Chris@0 9 *
Chris@0 10 * The language negotiation API is based on two major concepts:
Chris@0 11 * - Language types: types of translatable data (the types of data that a user
Chris@0 12 * can view or request).
Chris@0 13 * - Language negotiation methods: responsible for determining which language to
Chris@0 14 * use to present a particular piece of data to the user.
Chris@0 15 * Both language types and language negotiation methods are customizable.
Chris@0 16 *
Chris@0 17 * Drupal defines three built-in language types:
Chris@0 18 * - Interface language: The page's main language, used to present translated
Chris@0 19 * user interface elements such as titles, labels, help text, and messages.
Chris@0 20 * - Content language: The language used to present content that is available
Chris@0 21 * in more than one language.
Chris@0 22 * - URL language: The language associated with URLs. When generating a URL,
Chris@0 23 * this value will be used for URL's as a default if no explicit preference is
Chris@0 24 * provided.
Chris@0 25 * Modules can define additional language types through
Chris@0 26 * hook_language_types_info(), and alter existing language type definitions
Chris@0 27 * through hook_language_types_info_alter().
Chris@0 28 *
Chris@0 29 * Language types may be configurable or fixed. The language negotiation
Chris@0 30 * methods associated with a configurable language type can be explicitly
Chris@0 31 * set through the user interface. A fixed language type has predetermined
Chris@0 32 * (module-defined) language negotiation settings and, thus, does not appear in
Chris@0 33 * the configuration page. Here is a code snippet that makes the content
Chris@0 34 * language (which by default inherits the interface language's values)
Chris@0 35 * configurable:
Chris@0 36 * @code
Chris@0 37 * function mymodule_language_types_info_alter(&$language_types) {
Chris@0 38 * unset($language_types[LanguageInterface::TYPE_CONTENT]['fixed']);
Chris@0 39 * }
Chris@0 40 * @endcode
Chris@0 41 *
Chris@0 42 * The locked configuration property prevents one language type from being
Chris@0 43 * switched from customized to not customized, and vice versa.
Chris@0 44 * @see \Drupal\language\LanguageNegotiator::updateConfiguration()
Chris@0 45 *
Chris@0 46 * Every language type can have a different set of language negotiation methods
Chris@0 47 * assigned to it. Different language types often share the same language
Chris@0 48 * negotiation settings, but they can have independent settings if needed. If
Chris@0 49 * two language types are configured the same way, their language switcher
Chris@0 50 * configuration will be functionally identical and the same settings will act
Chris@0 51 * on both language types.
Chris@0 52 *
Chris@0 53 * Drupal defines the following built-in language negotiation methods:
Chris@0 54 * - URL: Determine the language from the URL (path prefix or domain).
Chris@0 55 * - Session: Determine the language from a request/session parameter.
Chris@0 56 * - User: Follow the user's language preference.
Chris@0 57 * - User admin language: Identify admin language from the user preferences.
Chris@0 58 * - Browser: Determine the language from the browser's language settings.
Chris@0 59 * - Selected language: Use the default site language.
Chris@0 60 * Language negotiation methods are simple plugin classes that implement a
Chris@0 61 * particular logic to return a language code. For instance, the URL method
Chris@0 62 * searches for a valid path prefix or domain name in the current request URL.
Chris@0 63 * If a language negotiation method does not return a valid language code, the
Chris@0 64 * next method associated with the language type (based on method weight) is
Chris@0 65 * invoked.
Chris@0 66 *
Chris@0 67 * Modules can define additional language negotiation methods by simply provide
Chris@0 68 * the related plugins, and alter existing methods through
Chris@0 69 * hook_language_negotiation_info_alter(). Here is an example snippet that lets
Chris@0 70 * path prefixes be ignored for administrative paths:
Chris@0 71 * @code
Chris@0 72 * function mymodule_language_negotiation_info_alter(&$negotiation_info) {
Chris@0 73 * // Replace the original plugin with our own implementation.
Chris@0 74 * $method_id = \Drupal\language\Plugin\LanguageNegotiation\LanguageNegotiationUrl::METHOD_ID;
Chris@0 75 * $negotiation_info[$method_id]['class'] = 'Drupal\my_module\Plugin\LanguageNegotiation\MyLanguageNegotiationUrl';
Chris@0 76 * }
Chris@0 77 *
Chris@0 78 * class MyLanguageNegotiationUrl extends LanguageNegotiationUrl {
Chris@0 79 * public function getCurrentLanguage(Request $request = NULL) {
Chris@0 80 * if ($request) {
Chris@0 81 * // Use the original URL language negotiation method to get a valid
Chris@0 82 * // language code.
Chris@0 83 * $langcode = parent::getCurrentLanguage($request);
Chris@0 84 *
Chris@0 85 * // If we are on an administrative path, override with the default
Chris@0 86 * language.
Chris@0 87 * if ($request->query->has('q') && strtok($request->query->get('q'), '/') == 'admin') {
Chris@0 88 * return $this->languageManager->getDefaultLanguage()->getId();
Chris@0 89 * }
Chris@0 90 * return $langcode;
Chris@0 91 * }
Chris@0 92 * }
Chris@0 93 * }
Chris@0 94 * @endcode
Chris@0 95 *
Chris@0 96 * For more information, see
Chris@0 97 * @link https://www.drupal.org/node/1497272 Language Negotiation API @endlink
Chris@0 98 */
Chris@0 99 interface LanguageNegotiatorInterface {
Chris@0 100
Chris@0 101 /**
Chris@0 102 * The language negotiation method id for the language negotiator itself.
Chris@0 103 */
Chris@0 104 const METHOD_ID = 'language-default';
Chris@0 105
Chris@0 106 /**
Chris@0 107 * Resets the negotiated languages and the method instances.
Chris@0 108 */
Chris@0 109 public function reset();
Chris@0 110
Chris@0 111 /**
Chris@0 112 * Sets the current active user and resets all language types.
Chris@0 113 *
Chris@0 114 * @param \Drupal\Core\Session\AccountInterface $current_user
Chris@0 115 * The current active user.
Chris@0 116 */
Chris@0 117 public function setCurrentUser(AccountInterface $current_user);
Chris@0 118
Chris@0 119 /**
Chris@0 120 * Initializes the specified language type.
Chris@0 121 *
Chris@0 122 * @param string $type
Chris@0 123 * The language type to be initialized.
Chris@0 124 *
Chris@0 125 * @return \Drupal\Core\Language\LanguageInterface[]
Chris@0 126 * Returns an array containing a single language keyed by the language
Chris@0 127 * negotiation method ID used to determine the language of the specified
Chris@0 128 * type. If negotiation is not possible the default language is returned.
Chris@0 129 */
Chris@0 130 public function initializeType($type);
Chris@0 131
Chris@0 132 /**
Chris@0 133 * Returns the language negotiation methods enabled for a language type.
Chris@0 134 *
Chris@0 135 * @param string $type
Chris@0 136 * (optional) The language type. If no type is specified all the method
Chris@0 137 * definitions are returned.
Chris@0 138 *
Chris@0 139 * @return array[]
Chris@0 140 * An array of language negotiation method definitions keyed by method id.
Chris@0 141 */
Chris@0 142 public function getNegotiationMethods($type = NULL);
Chris@0 143
Chris@0 144 /**
Chris@0 145 * Returns an instance of the specified language negotiation method.
Chris@0 146 *
Chris@0 147 * @param string $method_id
Chris@0 148 * The method identifier.
Chris@0 149 *
Chris@0 150 * @return \Drupal\language\LanguageNegotiationMethodInterface
Chris@0 151 */
Chris@0 152 public function getNegotiationMethodInstance($method_id);
Chris@0 153
Chris@0 154 /**
Chris@0 155 * Returns the ID of the language type's primary language negotiation method.
Chris@0 156 *
Chris@0 157 * @param string $type
Chris@0 158 * The language type.
Chris@0 159 *
Chris@0 160 * @return string
Chris@0 161 * The identifier of the primary language negotiation method for the given
Chris@0 162 * language type, or the default method if none exists.
Chris@0 163 */
Chris@0 164 public function getPrimaryNegotiationMethod($type);
Chris@0 165
Chris@0 166 /**
Chris@0 167 * Checks whether a language negotiation method is enabled for a language type.
Chris@0 168 *
Chris@0 169 * @param string $method_id
Chris@0 170 * The language negotiation method ID.
Chris@0 171 * @param string $type
Chris@0 172 * (optional) The language type. If none is passed, all the configurable
Chris@0 173 * language types will be inspected.
Chris@0 174 *
Chris@0 175 * @return bool
Chris@0 176 * TRUE if the method is enabled for at least one of the given language
Chris@0 177 * types, or FALSE otherwise.
Chris@0 178 */
Chris@0 179 public function isNegotiationMethodEnabled($method_id, $type = NULL);
Chris@0 180
Chris@0 181 /**
Chris@0 182 * Saves a list of language negotiation methods for a language type.
Chris@0 183 *
Chris@0 184 * @param string $type
Chris@0 185 * The language type.
Chris@0 186 * @param int[] $enabled_methods
Chris@0 187 * An array of language negotiation method weights keyed by method ID.
Chris@0 188 */
Chris@0 189 public function saveConfiguration($type, $enabled_methods);
Chris@0 190
Chris@0 191 /**
Chris@0 192 * Resave the configuration to purge missing negotiation methods.
Chris@0 193 */
Chris@0 194 public function purgeConfiguration();
Chris@0 195
Chris@0 196 /**
Chris@0 197 * Updates the configuration based on the given language types.
Chris@0 198 *
Chris@0 199 * Stores the list of the language types along with information about their
Chris@0 200 * configurable state. Stores the default settings if the language type is
Chris@0 201 * not configurable.
Chris@0 202 *
Chris@0 203 * @param string[] $types
Chris@0 204 * An array of configurable language types.
Chris@0 205 */
Chris@0 206 public function updateConfiguration(array $types);
Chris@0 207
Chris@0 208 }