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 shown 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`	Available `value_id => label` pairs
`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
`getManageUrl()`	`?string`	URL to manage scope values
`getManageLabel()`	`?string`	Link text for management URL

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)
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. Provides weight-based sorting and value aggregation across all enabled scopes.