diff --git a/core/lib/Drupal/Core/Cache/Context/CacheContextsManager.php b/core/lib/Drupal/Core/Cache/Context/CacheContextsManager.php index 81d6735..67c3b6b 100644 --- a/core/lib/Drupal/Core/Cache/Context/CacheContextsManager.php +++ b/core/lib/Drupal/Core/Cache/Context/CacheContextsManager.php @@ -25,7 +25,7 @@ * @see \Drupal\Core\Cache\Context\CalculatedCacheContextInterface * @see \Drupal\Core\Cache\Context\CacheContextsPass */ -class CacheContextsManager { +class CacheContextsManager implements CacheContextsManagerInterface { /** * The service container. @@ -55,25 +55,14 @@ public function __construct(ContainerInterface $container, array $contexts) { } /** - * Provides an array of available cache contexts. - * - * @return string[] - * An array of available cache context IDs. + * {@inheritdoc} */ public function getAll() { return $this->contexts; } /** - * Provides an array of available cache context labels. - * - * To be used in cache configuration forms. - * - * @param bool $include_calculated_cache_contexts - * Whether to also return calculated cache contexts. Default to FALSE. - * - * @return array - * An array of available cache contexts and corresponding labels. + * {@inheritdoc} */ public function getLabels($include_calculated_cache_contexts = FALSE) { $with_labels = array(); @@ -88,21 +77,7 @@ public function getLabels($include_calculated_cache_contexts = FALSE) { } /** - * Converts cache context tokens to cache keys. - * - * A cache context token is either: - * - a cache context ID (if the service ID is 'cache_context.foo', then 'foo' - * is a cache context ID), e.g. 'foo' - * - a calculated cache context ID, followed by a double colon, followed by - * the parameter for the calculated cache context, e.g. 'bar:some_parameter' - * - * @param string[] $context_tokens - * An array of cache context tokens. - * - * @return \Drupal\Core\Cache\Context\ContextCacheKeys - * The ContextCacheKeys object containing the converted cache keys and - * cacheability metadata. - * + * {@inheritdoc} */ public function convertTokensToKeys(array $context_tokens) { assert('$this->assertValidTokens($context_tokens)'); @@ -129,36 +104,7 @@ public function convertTokensToKeys(array $context_tokens) { } /** - * Optimizes cache context tokens (the minimal representative subset). - * - * A minimal representative subset means that any cache context token in the - * given set of cache context tokens that is a property of another cache - * context cache context token in the set, is removed. - * - * Hence a minimal representative subset is the most compact representation - * possible of a set of cache context tokens, that still captures the entire - * universe of variations. - * - * If a cache context is being optimized away, it is able to set cacheable - * metadata for itself which will be bubbled up. - * - * E.g. when caching per user ('user'), also caching per role ('user.roles') - * is meaningless because "per role" is implied by "per user". - * - * Examples — remember that the period indicates hierarchy and the colon can - * be used to get a specific value of a calculated cache context: - * - ['a', 'a.b'] -> ['a'] - * - ['a', 'a.b.c'] -> ['a'] - * - ['a.b', 'a.b.c'] -> ['a.b'] - * - ['a', 'a.b', 'a.b.c'] -> ['a'] - * - ['x', 'x:foo'] -> ['x'] - * - ['a', 'a.b.c:bar'] -> ['a'] - * - * @param string[] $context_tokens - * A set of cache context tokens. - * - * @return string[] - * A representative subset of the given set of cache context tokens.. + * {@inheritdoc} */ public function optimizeTokens(array $context_tokens) { $optimized_content_tokens = []; @@ -222,17 +168,7 @@ protected function getService($context_id) { } /** - * Parses cache context tokens into context IDs and optional parameters. - * - * @param string[] $context_tokens - * An array of cache context tokens. - * - * @return array - * An array with the parsed results, with each result being an array - * containing: - * - The cache context ID. - * - The associated parameter (for a calculated cache context), or NULL if - * there is no parameter. + * {@inheritdoc} */ public static function parseTokens(array $context_tokens) { $contexts_with_parameters = []; @@ -248,16 +184,7 @@ public static function parseTokens(array $context_tokens) { } /** - * Validates an array of cache context tokens. - * - * Can be called before using cache contexts in operations, to check validity. - * - * @param string[] $context_tokens - * An array of cache context tokens. - * - * @throws \LogicException - * - * @see \Drupal\Core\Cache\Context\CacheContextsManager::parseTokens() + * {@inheritdoc} */ public function validateTokens(array $context_tokens = []) { if (empty($context_tokens)) { @@ -298,18 +225,7 @@ public function validateTokens(array $context_tokens = []) { } /** - * Asserts the context tokens are valid - * - * Similar to ::validateTokens, this method returns boolean TRUE when the - * context tokens are valid, and FALSE when they are not instead of returning - * NULL when they are valid and throwing a \LogicException when they are not. - * This function should be used with the assert() statement. - * - * @param mixed $context_tokens - * Variable to be examined - should be array of context_tokens. - * - * @return bool - * TRUE if context_tokens is an array of valid tokens. + * {@inheritdoc} */ public function assertValidTokens($context_tokens) { if (!is_array($context_tokens)) { diff --git a/core/lib/Drupal/Core/Cache/Context/CacheContextsManagerInterface.php b/core/lib/Drupal/Core/Cache/Context/CacheContextsManagerInterface.php new file mode 100644 index 0000000..80ce7b7 --- /dev/null +++ b/core/lib/Drupal/Core/Cache/Context/CacheContextsManagerInterface.php @@ -0,0 +1,138 @@ + ['a'] + * - ['a', 'a.b.c'] -> ['a'] + * - ['a.b', 'a.b.c'] -> ['a.b'] + * - ['a', 'a.b', 'a.b.c'] -> ['a'] + * - ['x', 'x:foo'] -> ['x'] + * - ['a', 'a.b.c:bar'] -> ['a'] + * + * @param string[] $context_tokens + * A set of cache context tokens. + * + * @return string[] + * A representative subset of the given set of cache context tokens.. + */ + public function optimizeTokens(array $context_tokens); + + /** + * Parses cache context tokens into context IDs and optional parameters. + * + * @param string[] $context_tokens + * An array of cache context tokens. + * + * @return array + * An array with the parsed results, with each result being an array + * containing: + * - The cache context ID. + * - The associated parameter (for a calculated cache context), or NULL if + * there is no parameter. + */ + public static function parseTokens(array $context_tokens); + + /** + * Validates an array of cache context tokens. + * + * Can be called before using cache contexts in operations, to check validity. + * + * @param string[] $context_tokens + * An array of cache context tokens. + * + * @throws \LogicException + * + * @see \Drupal\Core\Cache\Context\CacheContextsManagerInterface::parseTokens() + */ + public function validateTokens(array $context_tokens = []); + + /** + * Asserts the context tokens are valid + * + * Similar to ::validateTokens, this method returns boolean TRUE when the + * context tokens are valid, and FALSE when they are not instead of returning + * NULL when they are valid and throwing a \LogicException when they are not. + * This function should be used with the assert() statement. + * + * @param mixed $context_tokens + * Variable to be examined - should be array of context_tokens. + * + * @return bool + * TRUE if context_tokens is an array of valid tokens. + */ + public function assertValidTokens($context_tokens); + +}