Problem/Motivation
The runtime vs. available contexts methods from
#2354889: Make block context faster by removing onBlock event and replace it with loading from a ContextManager →
were a very confusing part of that issue.
I think the docs still need work:
**
+ * Gets runtime context values for the given context IDs.
+ *
+ * For context-aware plugins to function correctly, all of the contexts that
+ * they require must be populated with values. So this method should set a
+ * value for each context that it adds. For example:
+ *
+ * @code
+ * // Determine a specific node to pass as context to a block.
+ * $node = ...
+ *
+ * // Set that specific node as the value of the 'node' context.
+ * $context = new Context(new ContextDefinition('entity:node'));
+ * $context->setContextValue($node);
+ * return ['node' => $context];
+ * @endcode
+ *
+ * On the other hand, there are cases, on which providers no longer are
+ * possible to provide context objects, even without the value, so the caller
+ * should not expect it.
+ *
+ * @param string[] $unqualified_context_ids
+ * The requested context IDs. The context provider must only return contexts
+ * for those IDs.
+ *
+ * @return \Drupal\Core\Plugin\Context\ContextInterface[]
+ * The determined available contexts, keyed by the unqualified context_id.
+ *
+ * @see \Drupal\Core\Plugin\Context\ContextProviderInterface:getAvailableContexts()
+ */
+ public function getRuntimeContexts(array $unqualified_context_ids);
+
It looks like there are at least two possible outcomes from this function, which probably have the same effect in practice:
1. Method is unable to get a value for a context object, so returns the object with no value set.
2. Method is unable to get a value for a context object, so doesn't return the object at all (i..e only returns objects with values set and none others).
If both of these have the same implications for calling code, then why not only return context objects with values set, and just don't return anything for ones that don't. You can create a context object with no value yourself anyway.
This also brings up another question, which is why do we both having context objects with no value at all? There are context definition objects. What does a context object with no value provide that the definition object doesn't? And if so why not a different interface?
Proposed resolution
Remaining tasks
User interface changes
API changes
Data model changes