Scope API

The scope system is built on Drupal's plugin API using PHP attributes for discovery.

Plugin attribute

use Drupal\ai_context\Attribute\AiContextScope;

#[AiContextScope(
  id: 'my_scope',
  label: new TranslatableMarkup('My Scope'),
  description: new TranslatableMarkup('Description on context item forms.'),
  weight: 0,
)]

Namespace: Drupal\ai_context\Attribute\AiContextScope

Interface: AiContextScopeInterface

Namespace: Drupal\ai_context\Plugin\AiContextScope\AiContextScopeInterface

All scope plugins must implement this interface. Key methods:

Identity and metadata

Method	Return	Description
`getId()`	`string`	Plugin ID
`getLabel()`	`string`	Human-readable label
`getDescription()`	`string`	Description for context item forms
`getSubscriptionDescription()`	`string`	Description for agent subscription forms
`getWeight()`	`int`	Ordering weight

Value management

Method	Return	Description
`getValues()`	`array`	Raw `value_id => label` pairs from the plugin
`getAlteredValues()`	`array`	`getValues()` after `hook_ai_context_scope_values_alter()`; use this when building forms, filters, or resolving labels
`allowsMultiple()`	`bool`	Whether multiple values can be selected
`isDynamic()`	`bool`	Whether values come from external source
`getSelectedValueLabels(array)`	`array`	Labels for selected value IDs
`getValuesFromEntity(AiContextItem)`	`array`	Scope values stored on an item

Contextual detection

Method	Return	Description
`getCurrentValue()`	`?string`	Current value from request context
`matchesCurrentContext(AiContextItem)`	`?bool`	Whether item matches current context

Agent subscriptions

Method	Return	Description
`supportsSubscriptions()`	`bool`	Whether agents can subscribe

Form building

Method	Description
`buildValueForm(...)`	Builds checkboxes/radios for scope values
`extractFormValues(mixed)`	Normalizes submitted form values
`buildSettingsForm(...)`	Builds per-scope settings form
`validateSettingsForm(...)`	Validates settings submission
`submitSettingsForm(...)`	Processes settings submission

Configuration

Method	Return	Description
`getConfigName()`	`string`	Config object name for this scope
`defaultConfiguration()`	`array`	Default settings (must include `enabled`)
`isEnabled()`	`bool`	Whether scope is currently enabled

Management links

Method	Return	Description
`getManageRoute()`	`?array`	Route info array (`route_name`, `route_parameters`) to manage scope values
`getManageLabel()`	`?string`	Link text for the management link

Base class: AiContextScopeBase

Namespace: Drupal\ai_context\Plugin\AiContextScope\AiContextScopeBase

Abstract base class providing default implementations for all interface methods except getValues(). Extend this class for custom scope plugins.

Key defaults:

allowsMultiple() returns TRUE
isDynamic() returns FALSE
supportsSubscriptions() returns TRUE
getCurrentValue() returns NULL (no contextual detection)
matchesCurrentContext() uses getCurrentValue() + getValuesFromEntity()
buildValueForm() renders checkboxes (multiple) or radios (single) from getAlteredValues()
getSelectedValueLabels() resolves labels through getAlteredValues()
getValuesFromEntity() reads from the entity's scope map field

Plugin manager: AiContextScopeManager

Namespace: Drupal\ai_context\AiContextScopeManager

Service ID: plugin.manager.ai_context_scope

Discovers and manages scope plugins. getScopePlugins() returns plugins in display order (core scopes first, then contrib, each group sorted by plugin weight). getScopePluginDisplayWeights() exposes the same order as sequential #weight values for forms and tabs. Plugin weight controls matching/scoring priority, not form layout. Scope plugin definitions can be altered via hook_ai_context_scope_info_alter(); see Hooks.

Scope subscriptions on custom forms

When a module needs scope subscription widgets outside the agent settings form, inject or load the public ai_context.scope_subscription_form service (AiContextScopeSubscriptionFormBuilderInterface). It wraps the internal scope plugin manager and provides buildWidgets(), extractValues(), and buildSummary() with the same behavior as the agent form. See Services — ai_context.scope_subscription_form.