[12.1] Add stale environment stopping API

CHANGELOG.md

@@ -25,6 +25,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * Add support for additional filters and ordering options in `MergeRequests::all`
 * Add support for project CI/CD job token scope endpoints
 * Add support for merge request resource label event endpoints
+* Add support for `Environments::stopStale`
 
 
 ## [12.0.0] - 2025-02-23

src/Api/Environments.php

@@ -14,6 +14,7 @@
 
 namespace Gitlab\Api;
 
+use Symfony\Component\OptionsResolver\Options;
 use Symfony\Component\OptionsResolver\OptionsResolver;
 
 class Environments extends AbstractApi
@@ -64,6 +65,27 @@ public function stop(int|string $project_id, int $environment_id): mixed
         return $this->post($this->getProjectPath($project_id, 'environments/'.self::encodePath($environment_id).'/stop'));
     }
 
+    /**
+     * @param array      $parameters {
+     *
+     *     @var \DateTimeInterface $before Stop environments that have been modified or deployed to before the specified date.
+     * }
+     */
+    public function stopStale(int|string $project_id, array $parameters = []): mixed
+    {
+        $resolver = new OptionsResolver();
+        $datetimeNormalizer = function (Options $resolver, \DateTimeInterface $value): string {
+            return $value->format('c');
+        };
+
+        $resolver->setDefined('before')
+            ->setRequired('before')
+            ->setAllowedTypes('before', \DateTimeInterface::class)
+            ->setNormalizer('before', $datetimeNormalizer);
+
+        return $this->post($this->getProjectPath($project_id, 'environments/stop_stale'), $resolver->resolve($parameters));
+    }
+
     public function show(int|string $project_id, int $environment_id): mixed
     {
         return $this->get($this->getProjectPath($project_id, 'environments/'.self::encodePath($environment_id)));

tests/Api/EnvironmentsTest.php

@@ -195,6 +195,23 @@ public function shouldStopEnvironment(): void
         $this->assertEquals($expectedBool, $api->stop(1, 3));
     }
 
+    #[Test]
+    public function shouldStopStaleEnvironments(): void
+    {
+        $expectedArray = [
+            'message' => 'Successfully requested stop for all stale environments',
+        ];
+        $before = new \DateTimeImmutable('2020-01-01T08:00:00+00:00');
+
+        $api = $this->getApiMock();
+        $api->expects($this->once())
+            ->method('post')
+            ->with('projects/1/environments/stop_stale', ['before' => $before->format('c')])
+            ->willReturn($expectedArray);
+
+        $this->assertEquals($expectedArray, $api->stopStale(1, ['before' => $before]));
+    }
+
     protected function getApiClass(): string
     {
         return Environments::class;