symfony · fabpot · Oct 9, 2025 · Aug 21, 2025 · nicolas-grekas · Oct 6, 2025
diff --git a/composer.json b/composer.json
@@ -197,6 +197,10 @@
             "Symfony\\Bridge\\Twig\\": "src/Symfony/Bridge/Twig/",
             "Symfony\\Bundle\\": "src/Symfony/Bundle/",
             "Symfony\\Component\\": "src/Symfony/Component/",
+            "Symfony\\Config\\": [
+                "src/Symfony/Component/DependencyInjection/Loader/Config/",
+                "src/Symfony/Component/Routing/Loader/Config/"
+            ],
             "Symfony\\Runtime\\Symfony\\Component\\": "src/Symfony/Component/Runtime/Internal/"
         },
         "files": [

diff --git a/src/Symfony/Component/DependencyInjection/CHANGELOG.md b/src/Symfony/Component/DependencyInjection/CHANGELOG.md
@@ -12,6 +12,7 @@ CHANGELOG
  * Allow multiple `#[AsDecorator]` attributes
  * Handle returning arrays and config-builders from config files
  * Handle declaring services using PHP arrays that follow the same shape as corresponding yaml files
+ * Add `ServicesConfig` to help writing PHP configs using yaml-like array-shapes
  * Deprecate using `$this` or its internal scope from PHP config files; use the `$loader` variable instead
  * Deprecate XML configuration format, use YAML or PHP instead
  * Deprecate `ExtensionInterface::getXsdValidationBasePath()` and `getNamespace()`

diff --git a/src/Symfony/Component/DependencyInjection/Loader/Config/ServicesConfig.php b/src/Symfony/Component/DependencyInjection/Loader/Config/ServicesConfig.php
@@ -0,0 +1,142 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Config;
+
+use Symfony\Component\DependencyInjection\ContainerInterface;
+use Symfony\Component\DependencyInjection\Exception\InvalidArgumentException;
+use Symfony\Component\DependencyInjection\Loader\Configurator\ReferenceConfigurator;
+use Symfony\Component\DependencyInjection\Reference;
+use Symfony\Component\ExpressionLanguage\Expression;
+
+require_once __DIR__.\DIRECTORY_SEPARATOR.'functions.php';
+
+/**
+ * @psalm-type Arguments = list<mixed>|array<string, mixed>
+ * @psalm-type Callback = string|array{0:string|Reference|ReferenceConfigurator,1:string}|\Closure|Reference|ReferenceConfigurator|Expression
+ * @psalm-type Tags = list<string|array<string, array<string, mixed>>>
+ * @psalm-type Deprecation = array{package: string, version: string, message?: string}
+ * @psalm-type Call = array<string, Arguments>|array{0:string, 1?:Arguments, 2?:bool}|array{method:string, arguments?:Arguments, returns_clone?:bool}
+ * @psalm-type Imports = list<string|array{
+ *   resource: string,
+ *   type?: string|null,
+ *   ignore_errors?: bool,
+ * }>
+ * @psalm-type Parameters = array<string, scalar|\UnitEnum|array<scalar|\UnitEnum|array|null>|null>
+ * @psalm-type Defaults = array{
+ *   public?: bool,
+ *   tags?: Tags,
+ *   resource_tags?: Tags,
+ *   autowire?: bool,
+ *   autoconfigure?: bool,
+ *   bind?: array<string, mixed>,
+ * }
+ * @psalm-type Instanceof = array{
+ *   shared?: bool,
+ *   lazy?: bool|string,
+ *   public?: bool,
+ *   properties?: array<string, mixed>,
+ *   configurator?: Callback,
+ *   calls?: list<Call>,
+ *   tags?: Tags,
+ *   resource_tags?: Tags,
+ *   autowire?: bool,
+ *   bind?: array<string, mixed>,
+ *   constructor?: string,
+ * }
+ * @psalm-type Definition = array{
+ *   class?: string,
+ *   file?: string,
+ *   parent?: string,
+ *   shared?: bool,
+ *   synthetic?: bool,
+ *   lazy?: bool|string,
+ *   public?: bool,
+ *   abstract?: bool,
+ *   deprecated?: Deprecation,
+ *   factory?: Callback,
+ *   configurator?: Callback,
+ *   arguments?: Arguments,
+ *   properties?: array<string, mixed>,
+ *   calls?: list<Call>,
+ *   tags?: Tags,
+ *   resource_tags?: Tags,
+ *   decorates?: string,
+ *   decoration_inner_name?: string,
+ *   decoration_priority?: int,
+ *   decoration_on_invalid?: 'exception'|'ignore'|null|ContainerInterface::EXCEPTION_ON_INVALID_REFERENCE|ContainerInterface::IGNORE_ON_INVALID_REFERENCE|ContainerInterface::NULL_ON_INVALID_REFERENCE,
+ *   autowire?: bool,
+ *   autoconfigure?: bool,
+ *   bind?: array<string, mixed>,
+ *   constructor?: string,
+ *   from_callable?: mixed,
+ * }
+ * @psalm-type Alias = string|array{
+ *   alias: string,
+ *   public?: bool,
+ *   deprecated?: Deprecation,
+ * }
+ * @psalm-type Prototype = array{
+ *   resource: string,
+ *   namespace?: string,
+ *   exclude?: string|list<string>,
+ *   parent?: string,
+ *   shared?: bool,
+ *   lazy?: bool|string,
+ *   public?: bool,
+ *   abstract?: bool,
+ *   deprecated?: Deprecation,
+ *   factory?: Callback,
+ *   arguments?: Arguments,
+ *   properties?: array<string, mixed>,
+ *   configurator?: Callback,
+ *   calls?: list<Call>,
+ *   tags?: Tags,
+ *   resource_tags?: Tags,
+ *   autowire?: bool,
+ *   autoconfigure?: bool,
+ *   bind?: array<string, mixed>,
+ *   constructor?: string,
+ * }
+ * @psalm-type Stack = array{
+ *   stack: list<Definition|Alias|Prototype|array<class-string, Arguments|null>>,
+ *   public?: bool,
+ *   deprecated?: Deprecation,
+ * }
+ * @psalm-type Services = array<string, Definition|Alias|Prototype|Stack>|array<class-string, Arguments|null>
+ */
+class ServicesConfig
+{
+    public readonly array $services;
+
+    /**
+     * @param Services   $services
+     * @param Imports    $imports
+     * @param Parameters $parameters
+     * @param Defaults   $defaults
+     * @param Instanceof $instanceof
+     */
+    public function __construct(
+        array $services = [],
+        public readonly array $imports = [],
+        public readonly array $parameters = [],
+        array $defaults = [],
+        array $instanceof = [],
+    ) {
+        if (isset($services['_defaults']) || isset($services['_instanceof'])) {
+            throw new InvalidArgumentException('The $services argument should not contain "_defaults" or "_instanceof" keys, use the $defaults and $instanceof parameters instead.');
+        }
+
+        $services['_defaults'] = $defaults;
+        $services['_instanceof'] = $instanceof;
+        $this->services = $services;
+    }
+}
diff --git a/src/Symfony/Component/DependencyInjection/Loader/Config/functions.php b/src/Symfony/Component/DependencyInjection/Loader/Config/functions.php
@@ -0,0 +1,129 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Config;
+
+use Symfony\Component\Config\Loader\ParamConfigurator;
+use Symfony\Component\DependencyInjection\Argument\AbstractArgument;
+use Symfony\Component\DependencyInjection\Argument\IteratorArgument;
+use Symfony\Component\DependencyInjection\Argument\ServiceLocatorArgument;
+use Symfony\Component\DependencyInjection\Argument\TaggedIteratorArgument;
+use Symfony\Component\DependencyInjection\Definition;
+use Symfony\Component\DependencyInjection\Loader\Configurator\AbstractConfigurator;
+use Symfony\Component\DependencyInjection\Loader\Configurator\ClosureReferenceConfigurator;
+use Symfony\Component\DependencyInjection\Loader\Configurator\EnvConfigurator;
+use Symfony\Component\DependencyInjection\Loader\Configurator\InlineServiceConfigurator;
+use Symfony\Component\DependencyInjection\Loader\Configurator\ReferenceConfigurator;
+use Symfony\Component\ExpressionLanguage\Expression;
+
+/**
+ * Creates a parameter.
+ */
+function param(string $name): ParamConfigurator
+{
+    return new ParamConfigurator($name);
+}
+
+/**
+ * Creates a reference to a service.
+ */
+function service(string $serviceId): ReferenceConfigurator
+{
+    return new ReferenceConfigurator($serviceId);
+}
+
+/**
+ * Creates an inline service.
+ */
+function inline_service(?string $class = null): InlineServiceConfigurator
+{
+    return new InlineServiceConfigurator(new Definition($class));
+}
+
+/**
+ * Creates a service locator.
+ *
+ * @param array<ReferenceConfigurator|InlineServiceConfigurator> $values
+ */
+function service_locator(array $values): ServiceLocatorArgument
+{
+    $values = AbstractConfigurator::processValue($values, true);
+
+    return new ServiceLocatorArgument($values);
+}
+
+/**
+ * Creates a lazy iterator.
+ *
+ * @param ReferenceConfigurator[] $values
+ */
+function iterator(array $values): IteratorArgument
+{
+    return new IteratorArgument(AbstractConfigurator::processValue($values, true));
+}
+
+/**
+ * Creates a lazy iterator by tag name.
+ */
+function tagged_iterator(string $tag, ?string $indexAttribute = null, ?string $defaultIndexMethod = null, ?string $defaultPriorityMethod = null, string|array $exclude = [], bool $excludeSelf = true): TaggedIteratorArgument
+{
+    return new TaggedIteratorArgument($tag, $indexAttribute, $defaultIndexMethod, false, $defaultPriorityMethod, (array) $exclude, $excludeSelf);
+}
+
+/**
+ * Creates a service locator by tag name.
+ */
+function tagged_locator(string $tag, ?string $indexAttribute = null, ?string $defaultIndexMethod = null, ?string $defaultPriorityMethod = null, string|array $exclude = [], bool $excludeSelf = true): ServiceLocatorArgument
+{
+    return new ServiceLocatorArgument(new TaggedIteratorArgument($tag, $indexAttribute, $defaultIndexMethod, true, $defaultPriorityMethod, (array) $exclude, $excludeSelf));
+}
+
+/**
+ * Creates an expression.
+ */
+function expr(string $expression): Expression
+{
+    return new Expression($expression);
+}
+
+/**
+ * Creates an abstract argument.
+ */
+function abstract_arg(string $description): AbstractArgument
+{
+    return new AbstractArgument($description);
+}
+
+/**
+ * Creates an environment variable reference.
+ */
+function env(string $name): EnvConfigurator
+{
+    return new EnvConfigurator($name);
+}
+
+/**
+ * Creates a closure service reference.
+ */
+function service_closure(string $serviceId): ClosureReferenceConfigurator
+{
+    return new ClosureReferenceConfigurator($serviceId);
+}
+
+/**
+ * Creates a closure.
+ */
+function closure(string|array|\Closure|ReferenceConfigurator|Expression $callable): InlineServiceConfigurator
+{
+    return (new InlineServiceConfigurator(new Definition('Closure')))
+        ->factory(['Closure', 'fromCallable'])
+        ->args([$callable]);
+}
diff --git a/src/Symfony/Component/DependencyInjection/Loader/Configurator/AbstractConfigurator.php b/src/Symfony/Component/DependencyInjection/Loader/Configurator/AbstractConfigurator.php
@@ -101,6 +101,9 @@ public static function processValue(mixed $value, bool $allowServices = false):
             case $value instanceof \UnitEnum:
                 return $value;
 
+            case $value instanceof \Closure:
+                return self::processClosure($value);
+
             case $value instanceof ArgumentInterface:
             case $value instanceof Definition:
             case $value instanceof Expression:
@@ -120,7 +123,7 @@ public static function processValue(mixed $value, bool $allowServices = false):
      *
      * @throws InvalidArgumentException if the closure is anonymous or references a non-static method
      */
-    final public static function processClosure(\Closure $closure): callable
+    private static function processClosure(\Closure $closure): callable
     {
         $function = new \ReflectionFunction($closure);
         if ($function->isAnonymous()) {