[PHP-WEBMASTER] [web-downloads] main: Improve series-init API

[Shivam Mathur]

Author: Shivam Mathur (shivammathur)
Date: 2025-09-24T20:56:42+05:30

Commit: 
https://github.com/php/web-downloads/commit/72b3cf473dc68f9544f67a99df0cd40aac765341
Raw diff: 
https://github.com/php/web-downloads/commit/72b3cf473dc68f9544f67a99df0cd40aac765341.diff

Improve series-init API

Changed paths:
  M  API.md
  M  src/Console/Command/SeriesInitCommand.php
  M  src/Http/Controllers/SeriesInitController.php


Diff:

diff --git a/API.md b/API.md
index 9d802b4..0bdcbb8 100644
--- a/API.md
+++ b/API.md
@@ -125,8 +125,8 @@ curl -i -X POST \
 - Auth: Required
 - Purpose: Initialize a series configuration by writing a JSON file into 
`BUILDS_DIRECTORY/series`.
 - Request body (JSON):
-    - `series` (string, required)
-    - `series_vs` (string, required): Matches `^v[c|s]\d{2}$`.
+    - `php_version` (string, required): Matches `^\d+.\d+$`.
+    - `source_vs` (string, required): Matches `^v[c|s]\d{2}$`.
     - `target_vs` (string, required): Matches `^v[c|s]\d{2}$`.
 - Success: `200 OK`, empty body.
 - Errors: `400` with validation details if input is invalid.
@@ -138,8 +138,8 @@ curl -i -X POST \
     -H "Authorization: Bearer $AUTH_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
-            "series": "8.4",
-            "series_vs": "vc15",
+            "php_version": "8.4",
+            "source_vs": "vc15",
             "target_vs": "vs16"
         }' \
     https://downloads.php.net/api/series-init
diff --git a/src/Console/Command/SeriesInitCommand.php 
b/src/Console/Command/SeriesInitCommand.php
index 6d6405d..0668e57 100644
--- a/src/Console/Command/SeriesInitCommand.php
+++ b/src/Console/Command/SeriesInitCommand.php
@@ -46,7 +46,7 @@ public function handle(): int
             foreach ($filteredFiles as $filepath) {
                 $data = json_decode(file_get_contents($filepath), true, 512, 
JSON_THROW_ON_ERROR);
                 extract($data);
-                $this->initSeriesFiles($series, $series_vs, $target_vs);
+                $this->initSeriesFiles($php_version, $source_vs, $target_vs);
                 unlink($filepath);
                 unlink($filepath . '.lock');
             }
@@ -61,8 +61,8 @@ public function handle(): int
      * @throws Exception
      */
     private function initSeriesFiles(
-        string $series,
-        string $series_vs,
+        string $php_version,
+        string $source_vs,
         string $target_vs
     ): void
     {
@@ -73,11 +73,14 @@ private function initSeriesFiles(
         }
         foreach(['x86', 'x64'] as $arch) {
             foreach(['stable', 'staging'] as $stability) {
-                $sourceSeries = 'packages-master-' . $series_vs . '-' . $arch 
. '-' . $stability . '.txt';
+                $sourceSeries = 'packages-master-' . $source_vs . '-' . $arch 
. '-' . $stability . '.txt';
                 if(!file_exists($baseDirectory . '/' . $sourceSeries)) {
                     throw new Exception("$baseDirectory/$sourceSeries not 
found");
                 }
-                $destinationFileName = 'packages-' . $series . '-' . 
$target_vs . '-' . $arch . '-' . $stability . '.txt';
+                $destinationFileName = 'packages-' . $php_version . '-' . 
$target_vs . '-' . $arch . '-' . $stability . '.txt';
+                if(file_exists($baseDirectory . '/' . $destinationFileName)) {
+                    throw new Exception("$baseDirectory/$destinationFileName 
already exists");
+                }
                 copy($baseDirectory . '/' . $sourceSeries, $baseDirectory . 
'/' . $destinationFileName);
             }
         }
diff --git a/src/Http/Controllers/SeriesInitController.php 
b/src/Http/Controllers/SeriesInitController.php
index c40d25e..8fa4d7f 100644
--- a/src/Http/Controllers/SeriesInitController.php
+++ b/src/Http/Controllers/SeriesInitController.php
@@ -10,8 +10,8 @@ class SeriesInitController extends BaseController
     protected function validate(array $data): bool
     {
         $validator = new Validator([
-            'series' => 'required|string',
-            'series_vs' => 'required|string|regex:/^v[c|s]\d{2}$/',
+            'php_version' => 'required|string:regex:/^\d+\.\d+$/',
+            'source_vs' => 'required|string|regex:/^v[c|s]\d{2}$/',
             'target_vs' => 'required|string|regex:/^v[c|s]\d{2}$/',
         ]);