Refactor distribution configuration

codedmonkey · codedmonkey · commit c01e4cd9a9c9 · 2026-07-07T13:17:31.000+02:00
diff --git a/config/reference.php b/config/reference.php
@@ -1643,11 +1643,19 @@
  *     storage?: array{
  *         path?: scalar|Param|null, // Default: "%kernel.project_dir%/storage"
  *     },
- *     dist_mirroring?: bool|array{
+ *     dist_mirroring?: bool|array{ // Deprecated: The node "dist_mirroring" at path "dirigent.dist_mirroring" is deprecated. Use the "distributions" section instead.
  *         enabled?: bool|Param, // Default: false
  *         preferred?: bool|Param, // Default: true
  *         dev_packages?: bool|Param, // Default: false
  *     },
+ *     distributions?: bool|array{
+ *         enabled?: bool|Param, // Host the distributions of packages // Default: false
+ *         build?: bool|Param, // Build distributions from the source code (if not already provided) // Default: true
+ *         mirror?: bool|Param, // Mirror distributions from the original source (if provided) // Default: false
+ *         async_api_requests?: bool|Param, // Fetch distributions asynchronously instead of during execution (from the API) // Default: false
+ *         dev_versions?: bool|Param, // Include distributions of development versions // Default: false
+ *         preferred_mirror?: bool|Param, // Force Composer to download distributions from this registry first // Default: false
+ *     },
  *     metadata?: array{
  *         mirror_vcs_repositories?: bool|Param, // Fetch mirrored packages from their VCS repositories by default when possible. // Default: false
  *         retain_pruned_versions?: bool|array{
diff --git a/docs/configuration-reference.md b/docs/configuration-reference.md
@@ -29,10 +29,13 @@ dirigent:
     dynamic_update_delay: 'PT4H'
     periodic_updates: true
     periodic_update_interval: 'P1W'
-  dist_mirroring:
+  distributions:
     enabled: false
-    preferred: true
+    build: true
+    mirror: false
+    async_api_requests: false
     dev_packages: false
+    preferred_mirror: true
   metadata:
     mirror_vcs_repositories: false
     retain_pruned_versions:
@@ -117,18 +120,28 @@ The time between periodic updates being scheduled, defaults to once a week.
 
 The time must be defined in the [ISO 8601 durations][iso-8601-durations] format.
 
-## dist_mirroring
+## distributions
 
 ### enabled
 
 Type: `boolean` | Default: `false`
 
-Whether to enable or disable distribution mirroring
+Enable hosting of package distributions.
 
-### preferred
+### build
+
+Type: `boolean` | Default: `true`
+
+Enable building distribution from the source.
+
+### mirror
+
+### async_api_requests
 
 ### dev_packages
 
+### preferred_mirror
+
 ## metadata
 
 ### mirror_vcs_repositories
diff --git a/docs/dist-mirroring.md b/docs/dist-mirroring.md
diff --git a/docs/distributions.md b/docs/distributions.md
@@ -0,0 +1,14 @@
+---
+sidebar_position: 31
+---
+
+# Distributions
+
+:::note
+
+This page is a stub.
+
+:::
+
+Dirigent mirrors distributions from their original source if it's provided by the package, or builds the distribution
+from the source code. 
diff --git a/docs/readme.md b/docs/readme.md
@@ -8,8 +8,11 @@ sidebar_position: 1
 - [Introduction](introduction.md)
 - [Installation](installation/readme.md)
 - [Getting Started](getting-started.md)
+
+---
+
 - [Automatic Package Updates](automatic-package-updates.md)
-- [Dist Mirroring](dist-mirroring.md)
+- [Distributions](distributions.md)
 
 ---
 
diff --git a/src/Controller/ApiController.php b/src/Controller/ApiController.php
@@ -62,7 +62,7 @@ public function root(RouterInterface $router): JsonResponse
             'notify-batch' => $router->generate('api_track_installations'),
         ];
 
-        if ($this->getParameter('dirigent.dist_mirroring.enabled')) {
+        if ($this->getParameter('dirigent.distributions.mirror')) {
             $distributionUrlPattern = u($router->getRouteCollection()->get('api_package_distribution')->getPath())
                 ->replace('{package}', '%package%')
                 ->replace('{version}', '%version%')
@@ -72,7 +72,7 @@ public function root(RouterInterface $router): JsonResponse
 
             $data['mirrors'] = [[
                 'dist-url' => $distributionUrlPattern,
-                'preferred' => $this->getParameter('dirigent.dist_mirroring.preferred'),
+                'preferred' => $this->getParameter('dirigent.distributions.preferred_mirror'),
             ]];
         }
 
@@ -118,7 +118,7 @@ public function packageMetadata(Request $request): Response
     #[IsGrantedAccess]
     public function packageDistribution(Request $request, string $reference, string $type): Response
     {
-        if (!$this->getParameter('dirigent.dist_mirroring.enabled')) {
+        if (!$this->getParameter('dirigent.distributions.enabled')) {
             throw $this->createNotFoundException();
         }
 
@@ -134,7 +134,7 @@ public function packageDistribution(Request $request, string $reference, string
                 throw $this->createNotFoundException();
             }
 
-            if ($version->isDevelopment() && !$this->getParameter('dirigent.dist_mirroring.dev_packages')) {
+            if ($version->isDevelopment() && !$this->getParameter('dirigent.distributions.dev_versions')) {
                 throw $this->createNotFoundException();
             }
 
diff --git a/src/DependencyInjection/DirigentConfiguration.php b/src/DependencyInjection/DirigentConfiguration.php
@@ -73,18 +73,39 @@ public function getConfigTreeBuilder(): TreeBuilder
             ->end()
             ->arrayNode('dist_mirroring')
                 ->canBeEnabled()
+                ->setDeprecated(
+                    package: 'codedmonkey/dirigent',
+                    version: '0.8.0',
+                    message: 'The node "%node%" at path "%path%" is deprecated. Use the "distributions" section instead.'
+                )
                 ->children()
                     ->booleanNode('preferred')->defaultTrue()->end()
                     ->booleanNode('dev_packages')->defaultFalse()->end()
                 ->end()
             ->end();
 
+        $this->addDistributionsSection($rootNode);
         $this->addMetadataSection($rootNode);
         $this->addPackagesSection($rootNode);
 
         return $treeBuilder;
     }
 
+    private function addDistributionsSection(ArrayNodeDefinition|NodeDefinition $rootNode): void
+    {
+        $rootNode->children()
+            ->arrayNode('distributions')
+                ->canBeEnabled('Host the distributions of packages')
+                ->children()
+                    ->booleanNode('build')->defaultTrue()->info('Build distributions from the source code (if not already provided)')->end()
+                    ->booleanNode('mirror')->defaultFalse()->info('Mirror distributions from the original source (if provided)')->end()
+                    ->booleanNode('async_api_requests')->defaultFalse()->info('Fetch distributions asynchronously instead of during execution (from the API)')->end()
+                    ->booleanNode('dev_versions')->defaultFalse()->info('Include distributions of development versions')->end()
+                    ->booleanNode('preferred_mirror')->defaultFalse()->info('Force Composer to download distributions from this registry first')->end()
+                ->end()
+            ->end();
+    }
+
     private function addMetadataSection(ArrayNodeDefinition|NodeDefinition $rootNode): void
     {
         $rootNode->children()
diff --git a/src/DependencyInjection/DirigentExtension.php b/src/DependencyInjection/DirigentExtension.php
@@ -19,6 +19,7 @@ protected function loadInternal(array $mergedConfig, ContainerBuilder $container
         $container->setParameter('dirigent.title', $mergedConfig['title']);
         $container->setParameter('dirigent.slug', $slug);
 
+        $this->registerDistributionsConfiguration($mergedConfig['distributions'], $mergedConfig['dist_mirroring'], $container);
         $this->registerEncryptionConfiguration($mergedConfig['encryption'], $container);
         $this->registerMetadataConfiguration($mergedConfig['metadata'], $container);
         $this->registerPackagesConfiguration($mergedConfig['packages'], $container);
@@ -31,10 +32,6 @@ protected function loadInternal(array $mergedConfig, ContainerBuilder $container
         } else {
             $container->setParameter('dirigent.storage.path', $mergedConfig['storage']['path']);
         }
-
-        $container->setParameter('dirigent.dist_mirroring.enabled', $mergedConfig['dist_mirroring']['enabled']);
-        $container->setParameter('dirigent.dist_mirroring.preferred', $mergedConfig['dist_mirroring']['preferred']);
-        $container->setParameter('dirigent.dist_mirroring.dev_packages', $mergedConfig['dist_mirroring']['dev_packages']);
     }
 
     #[\Override]
@@ -43,6 +40,19 @@ public function getConfiguration(array $config, ContainerBuilder $container): Co
         return new DirigentConfiguration();
     }
 
+    private function registerDistributionsConfiguration(array $config, array $distMirroringConfig, ContainerBuilder $container): void
+    {
+        $distributionsEnabled = $config['enabled'] || $distMirroringConfig['enabled'];
+
+        $container->setParameter('dirigent.distributions.enabled', $distributionsEnabled);
+        $container->setParameter('dirigent.distributions.build', $distributionsEnabled && $config['build']);
+        $container->setParameter('dirigent.distributions.mirror', $distributionsEnabled && ($config['mirror'] || $distMirroringConfig['enabled']));
+
+        $container->setParameter('dirigent.distributions.async_api_requests', $config['async_api_requests']);
+        $container->setParameter('dirigent.distributions.dev_versions', $config['dev_versions'] || $distMirroringConfig['dev_packages']);
+        $container->setParameter('dirigent.distributions.preferred_mirror', $config['preferred_mirror'] || $distMirroringConfig['preferred']);
+    }
+
     /**
      * @param array{private_key: ?string, private_key_path: ?string, public_key: ?string, public_key_path: ?string, rotated_keys: array<string>, rotated_key_paths: array<string>} $config
      */

Original file line number	Diff line number	Diff line change
`@@ -62,7 +62,7 @@ public function root(RouterInterface $router): JsonResponse`
`62`	`62`	`'notify-batch' => $router->generate('api_track_installations'),`
`63`	`63`	`];`
`64`	`64`
`65`		`- if ($this->getParameter('dirigent.dist_mirroring.enabled')) {`
	`65`	`+ if ($this->getParameter('dirigent.distributions.mirror')) {`
`66`	`66`	`$distributionUrlPattern = u($router->getRouteCollection()->get('api_package_distribution')->getPath())`
`67`	`67`	`->replace('{package}', '%package%')`
`68`	`68`	`->replace('{version}', '%version%')`
`@@ -72,7 +72,7 @@ public function root(RouterInterface $router): JsonResponse`
`72`	`72`
`73`	`73`	`$data['mirrors'] = [[`
`74`	`74`	`'dist-url' => $distributionUrlPattern,`
`75`		`- 'preferred' => $this->getParameter('dirigent.dist_mirroring.preferred'),`
	`75`	`+ 'preferred' => $this->getParameter('dirigent.distributions.preferred_mirror'),`
`76`	`76`	`]];`
`77`	`77`	`}`
`78`	`78`
`@@ -118,7 +118,7 @@ public function packageMetadata(Request $request): Response`
`118`	`118`	`#[IsGrantedAccess]`
`119`	`119`	`public function packageDistribution(Request $request, string $reference, string $type): Response`
`120`	`120`	`{`
`121`		`- if (!$this->getParameter('dirigent.dist_mirroring.enabled')) {`
	`121`	`+ if (!$this->getParameter('dirigent.distributions.enabled')) {`
`122`	`122`	`throw $this->createNotFoundException();`
`123`	`123`	`}`
`124`	`124`
`@@ -134,7 +134,7 @@ public function packageDistribution(Request $request, string $reference, string`
`134`	`134`	`throw $this->createNotFoundException();`
`135`	`135`	`}`
`136`	`136`
`137`		`- if ($version->isDevelopment() && !$this->getParameter('dirigent.dist_mirroring.dev_packages')) {`
	`137`	`+ if ($version->isDevelopment() && !$this->getParameter('dirigent.distributions.dev_versions')) {`
`138`	`138`	`throw $this->createNotFoundException();`
`139`	`139`	`}`
`140`	`140`