Skip to content

Configuration Architecture

When to Use

Store plugin configuration in entities for Foundation pattern. Use config objects for Provider pattern. Use constraint-driven ServiceConfig for Service Collector pattern.

Decision

Situation Choose Why
Entity-based plugin instances Foundation Pattern Entity Configuration Plugin ID stored as entity field
Provider-specific settings Provider Pattern Config Objects Multiple named configs per provider
REST API-exposed configuration Service Collector ServiceConfig Constraint-driven metadata auto-generation
Admin UI configuration forms Foundation or Provider Pattern Entity forms or config forms
External system configuration Service Collector Pattern JSON-serializable configuration metadata

Pattern

Foundation Pattern Configuration:

Reference: /web/modules/contrib/commerce/modules/payment/config/install/

Pattern: Entity-based configuration with plugin field

# Entity configuration stores plugin ID
id: example
label: 'Example Gateway'
plugin: example_gateway
configuration:
  api_endpoint: 'https://api.example.com'
  timeout: 30

Provider Pattern Configuration:

Reference: AI module provider configuration pattern

# Provider module configuration
configs:
  default:
    api_key: ''
    timeout: 30
  production:
    api_key: ''
    timeout: 60

# Main module default provider settings
default_providers:
  process: 'example'
default_configs:
  process: 'default'

Service Collector Pattern Configuration:

Reference: /web/modules/contrib/orchestration/src/ServiceConfig.php

Pattern: Constraint-driven self-describing configuration

// ServiceConfig with constraints auto-generates UI metadata
new ServiceConfig(
  key: 'webhook_id',
  label: 'Webhook',
  description: 'Select registered webhook',
  required: true,
  type: 'string',
  constraints: [
    'Choice' => [
      'choices' => ['webhook1' => 'Webhook 1', 'webhook2' => 'Webhook 2']
    ]
  ]
)
// Auto-generates: {options: [{key: 'webhook1', name: 'Webhook 1'}, ...]}

Key Advantage: Configuration metadata embedded in service definition, automatically exposed via REST API for external UI generation.

Common Mistakes

  • Wrong: Hardcoding API keys in annotations → Right: Use Key module or config overrides with environment variables
  • Wrong: Complex config schema when ServiceConfig suffices → Right: Use ServiceConfig constraints for auto-generated metadata
  • Wrong: Entity configuration without plugin validation → Right: Validate in plugin manager's processDefinition()

See Also