[web-downloads] main: Merge pull request #9 from shivammathur/staging-php-releases
| From: | Shivam Mathur via GitHub | Date: | Thu, 19 Nov 2026 09:30:16 +0000 |
| Subject: | [web-downloads] main: Merge pull request #9 from shivammathur/staging-php-releases | ||
| Groups: | php.webmaster | ||
| Request: | Send a blank email to php-webmaster+get-34227@lists.php.net to get a copy of this message | ||
Author: Shivam Mathur (shivammathur)
Committer: GitHub (web-flow)
Pusher: shivammathur
Date: 2026-11-19T15:00:10+05:30
Commit: https://github.com/php/web-downloads/commit/42467e461fbec53a0f1e590dee183915a58e94b5
Raw diff: https://github.com/php/web-downloads/commit/42467e461fbec53a0f1e590dee183915a58e94b5.diff
Merge pull request #9 from shivammathur/staging-php-releases
Add support for staging PHP releases
Changed paths:
A .github/workflows/php-release.yml
A src/Http/Controllers/PhpReleaseController.php
M .github/workflows/php.yml
M API.md
M routes.php
M src/Http/Controllers/DeletePendingJobController.php
M src/Http/Controllers/PhpController.php
M tests/Console/Command/PhpCommandTest.php
M tests/Http/Controllers/DeletePendingJobControllerTest.php
M tests/Http/Controllers/ListBuildsControllerTest.php
Diff:
diff --git a/.github/workflows/php-release.yml b/.github/workflows/php-release.yml
new file mode 100644
index 0000000..a5f9c5d
--- /dev/null
+++ b/.github/workflows/php-release.yml
@@ -0,0 +1,24 @@
+name: Release staged PHP builds
+run-name: ${{ inputs.build == 'all' && 'Release all staged PHP builds'
|| format('Release staged PHP build {0}', inputs.build) }}
+
+on:
+ workflow_dispatch:
+ inputs:
+ build:
+ description: 'Build filename from the upload summary, or all'
+ required: true
+
+jobs:
+ release:
+ runs-on: ubuntu-latest
+ environment: downloads.php.net
+ steps:
+ - name: Queue staged builds for release
+ shell: bash
+ env:
+ AUTH_TOKEN: ${{ secrets.AUTH_TOKEN }}
+ run: |
+ jq -c '{build: .inputs.build}' "$GITHUB_EVENT_PATH" | \
+ curl --silent --show-error --fail-with-body \
+ --header "Authorization: Bearer $AUTH_TOKEN" --json @- \
+ https://downloads.php.net/api/php-release
diff --git a/.github/workflows/php.yml b/.github/workflows/php.yml
index cc84dea..62a2c7e 100644
--- a/.github/workflows/php.yml
+++ b/.github/workflows/php.yml
@@ -1,5 +1,5 @@
name: Upload PHP Builds
-run-name: Upload PHP builds for ${{ inputs.php-version }}
+run-name: ${{ inputs.staging && 'Stage PHP build' || format('Upload PHP
builds for {0}', inputs.php-version) }}
on:
workflow_dispatch:
inputs:
@@ -9,6 +9,10 @@ on:
url:
description: 'Artifact URL'
required: true
+ staging:
+ description: 'Stage for manual release'
+ type: boolean
+ default: false
jobs:
test:
@@ -16,9 +20,21 @@ jobs:
steps:
- name: Upload
+ shell: bash
+ env:
+ AUTH_TOKEN: ${{ secrets.AUTH_TOKEN }}
+ ARTIFACT_TOKEN: ${{ secrets.TOKEN }}
+ STAGING: ${{ inputs.staging }}
run: |
- curl \
- --request POST \
- --location https://downloads.php.net/api/php \
- --header 'Authorization: Bearer ${{ secrets.AUTH_TOKEN }}' \
- --data '{ "url": "${{ inputs.url }}", "token":
"${{ secrets.TOKEN }}" }'
+ if ! response=$(jq -c --arg token "$ARTIFACT_TOKEN" --argjson staging
"$STAGING" \
+ '{url: .inputs.url, token: $token, staging: $staging}'
"$GITHUB_EVENT_PATH" | \
+ curl --silent --show-error --fail-with-body \
+ --header "Authorization: Bearer $AUTH_TOKEN" --json @- https://downloads.php.net/api/php); then
+ printf '%s\n' "$response" >&2
+ exit 1
+ fi
+
+ if [[ "$STAGING" == true ]]; then
+ build=$(jq -er '.build | strings | select(length > 0)' <<<
"$response")
+ printf 'Staged PHP build %s\n' "$build" >>
"$GITHUB_STEP_SUMMARY"
+ fi
diff --git a/API.md b/API.md
index 9376c69..6027187 100644
--- a/API.md
+++ b/API.md
@@ -28,6 +28,7 @@
- [
GET /api/list-builds](#get-apilist-builds)
- [POST /api/delete-pending-job](#post-apidelete-pending-job)
- [POST /api/php](#post-apiphp)
+- [POST /api/php-release](#post-apiphp-release)
- [POST /api/pecl](#post-apipecl)
- [POST /api/winlibs](#post-apiwinlibs)
- [POST /api/winlibs-delete](#post-apiwinlibs-delete)
@@ -65,7 +66,7 @@ curl -i -X GET \
- Purpose: Remove a queued build job before it is processed.
- Request body (JSON):
- type (string, required): One of php, pecl, or
winlibs.
- - job (string, required): The job filename (for
php/pecl) or directory name (for winlibs).
+ - job (string, required): The job filename for php or
pecl, or directory name for winlibs. To delete a completed staged PHP ZIP,
set type to php and send staging/<filename>.zip. Use
the php/staging/<filename>.zip path from /api/list-builds and drop
the leading php/.
- Success: 200 OK with { "status": "deleted" }.
- Errors:
- 400 if validation fails (missing/invalid fields).
@@ -94,9 +95,12 @@ curl -i -X POST \
- Request body (JSON):
- url (string, required, URL): Direct download URL of the artifact.
- token (string, required): Used as a GitHub token if the URL points to
api.github.com.
-- Success: 200 OK, returned as soon as the download is accepted. The download
continues after the response and the completed ZIP is published atomically in
BUILDS_DIRECTORY/php.
+ - staging (boolean, optional, default false): Hold the ZIP in
BUILDS_DIRECTORY/php/staging until approved for release. The API creates this directory
on first use.
+- Success is 200 OK as soon as the download is accepted. The completed ZIP is moved
atomically into its queue directory after the response.
+ - For a regular upload, the response is empty and the ZIP goes into
BUILDS_DIRECTORY/php.
+ - For a staged upload, the response is JSON such as
{"build":"php-0123456789abcdef0123456789abcdef.zip"}. To recover
the filename later, use GET /api/list-builds and look for paths of the form
php/staging/<build>.zip. Pass the ZIP basename, including .zip, to
/api/php-release.
- Errors:
- - 400 with validation details if url or token are
missing/invalid.
+ - 400 with validation details if url, token, or
staging are invalid.
- 500 with Error: ... if the download cannot be prepared.
- Download failures after the response are written to the server error log and no ZIP is
published.
@@ -115,6 +119,23 @@ curl -i -X POST \
---
+### POST /api/php-release
+
+- Auth required.
+- Set build to the exact filename returned by a staged upload or to all
to queue every completed ZIP present in staging when the API runs. In-progress downloads stay in
staging.
+- 200 OK with an empty body means the selected ZIPs were moved into
BUILDS_DIRECTORY/php for the next cron run. all also returns 200
OK when there are no completed builds.
+- 400 for an invalid build value, 404 if a requested staged
ZIP is absent, 409 if a destination already exists, or 500 if the queue
operation fails.
+
+```bash
+curl -i -X POST \
+ -H "Authorization: Bearer $AUTH_TOKEN" \
+ -H "Content-Type: application/json" \
+ -d '{"build":"all"}' \
+ https://downloads.php.net/api/php-release
+```
+
+---
+
### POST /api/pecl
- Auth: Required
diff --git a/routes.php b/routes.php
index 1ccb6a5..a4577ed 100644
--- a/routes.php
+++ b/routes.php
@@ -6,6 +6,7 @@
use App\Http\Controllers\ListBuildsController;
use App\Http\Controllers\PeclController;
use App\Http\Controllers\PhpController;
+use App\Http\Controllers\PhpReleaseController;
use App\Http\Controllers\SbomUpdateController;
use App\Http\Controllers\SeriesDeleteController;
use App\Http\Controllers\SeriesInitController;
@@ -23,6 +24,7 @@
$router->registerRoute('/api/winlibs', 'POST', WinlibsController::class,
true);
$router->registerRoute('/api/winlibs-delete', 'POST',
WinlibsDeleteController::class, true);
$router->registerRoute('/api/php', 'POST', PhpController::class, true);
+$router->registerRoute('/api/php-release', 'POST',
PhpReleaseController::class, true);
$router->registerRoute('/api/sbom-update', 'POST',
SbomUpdateController::class, true);
$router->registerRoute('/api/series-init', 'POST',
SeriesInitController::class, true);
$router->registerRoute('/api/series-delete', 'POST',
SeriesDeleteController::class, true);
diff --git a/src/Http/Controllers/DeletePendingJobController.php
b/src/Http/Controllers/DeletePendingJobController.php
index d0d3288..1d36887 100644
--- a/src/Http/Controllers/DeletePendingJobController.php
+++ b/src/Http/Controllers/DeletePendingJobController.php
@@ -22,9 +22,15 @@ public function __construct(string $inputPath = 'php://input', ?string
$buildsDi
protected function validate(array $data): bool
{
+ $type = $data['type'] ?? null;
+ $namePattern = '(?!\.{1,2}\z)[A-Za-z0-9._-]+';
+ if (is_string($type) && strtolower($type) === 'php') {
+ $namePattern = '(?:' . $namePattern .
'|staging/[A-Za-z0-9._-]+\.zip)';
+ }
+
$validator = new Validator([
'type' => 'required|string|regex:/^(php|pecl|winlibs)$/i',
- 'job' =>
'required|string|regex:/\A(?!\.{1,2}\z)[A-Za-z0-9._-]+\z/',
+ 'job' => 'required|string|regex:~\A' . $namePattern .
'\z~',
]);
$validator->validate($data);
diff --git a/src/Http/Controllers/PhpController.php b/src/Http/Controllers/PhpController.php
index d765428..1a472ba 100644
--- a/src/Http/Controllers/PhpController.php
+++ b/src/Http/Controllers/PhpController.php
@@ -15,6 +15,12 @@ class PhpController extends BaseController
{
protected function validate(array $data): bool
{
+ if (array_key_exists('staging', $data) &&
!is_bool($data['staging'])) {
+ http_response_code(400);
+ echo 'Invalid request: The staging field must be a boolean.';
+ return false;
+ }
+
$validator = new Validator([
'url' => 'required|url',
'token' => 'required|string',
@@ -34,16 +40,23 @@ protected function validate(array $data): bool
protected function execute(array $data): void
{
+ $staging = $data['staging'] ?? false;
try {
- $filepath = $this->prepareBuildFilepath($data['url']);
+ $filepath = $this->prepareBuildFilepath($data['url'], $staging);
} catch (Exception $exception) {
http_response_code(500);
echo 'Error: ' . $exception->getMessage();
return;
}
+ $response = '';
+ if ($staging) {
+ header('Content-Type: application/json');
+ $response = json_encode(['build' => basename($filepath)],
JSON_THROW_ON_ERROR);
+ }
http_response_code(200);
- header('Content-Length: 0');
+ header('Content-Length: ' . strlen($response));
+ echo $response;
DeferredCallbacks::add(
fn () => $this->fetchPhpBuild($data['url'], $data['token'],
$filepath),
@@ -85,7 +98,7 @@ protected function fetchPhpBuild(
}
}
- private function prepareBuildFilepath(string $url): string
+ private function prepareBuildFilepath(string $url, bool $staging): string
{
$buildsDirectory = getenv('BUILDS_DIRECTORY');
if ($buildsDirectory === false || $buildsDirectory === '') {
@@ -98,7 +111,7 @@ private function prepareBuildFilepath(string $url): string
$previousUmask = umask(0);
try {
- if (!mkdir($directory, 0777, true) && !is_dir($directory)) {
+ if (!@mkdir($directory, 0777, true) && !is_dir($directory)) {
throw new RuntimeException('Failed to create the PHP builds
directory');
}
} finally {
@@ -106,12 +119,19 @@ private function prepareBuildFilepath(string $url): string
}
}
+ if ($staging) {
+ $directory .= '/staging';
+ if (!is_dir($directory) && !@mkdir($directory, 0755) &&
!is_dir($directory)) {
+ throw new RuntimeException('Failed to create the PHP staging directory');
+ }
+ }
+
if (!is_writable($directory)) {
- throw new RuntimeException('PHP builds directory is not writable');
+ throw new RuntimeException('PHP ' . ($staging ? 'staging' :
'builds') . ' directory is not writable');
}
- $hash = hash('sha256', $url) . uniqid('', true);
+ $id = $staging ? bin2hex(random_bytes(16)) : hash('sha256', $url) .
uniqid('', true);
- return $directory . '/php-' . $hash . '.zip';
+ return $directory . '/php-' . $id . '.zip';
}
}
diff --git a/src/Http/Controllers/PhpReleaseController.php
b/src/Http/Controllers/PhpReleaseController.php
new file mode 100644
index 0000000..0789849
--- /dev/null
+++ b/src/Http/Controllers/PhpReleaseController.php
@@ -0,0 +1,85 @@
+<?php
+declare(strict_types=1);
+
+namespace App\Http\Controllers;
+
+use App\Http\BaseController;
+use App\Validator;
+use RuntimeException;
+
+class PhpReleaseController extends BaseController
+{
+ private const string BUILD_FILENAME_PATTERN = 'php-[a-f0-9]{32}\.zip';
+
+ protected function validate(array $data): bool
+ {
+ $validator = new Validator([
+ 'build' => 'required|string|regex:/\A(?:all|' .
self::BUILD_FILENAME_PATTERN . ')\z/',
+ ]);
+ $validator->validate($data);
+
+ if (!$validator->isValid) {
+ http_response_code(400);
+ echo 'Invalid request: ' . $validator;
+ }
+
+ return $validator->isValid;
+ }
+
+ protected function execute(array $data): void
+ {
+ $buildsDirectory = getenv('BUILDS_DIRECTORY');
+ if ($buildsDirectory === false || $buildsDirectory === '') {
+ http_response_code(500);
+ echo 'Error: Builds directory is not configured.';
+ return;
+ }
+
+ $queue = $buildsDirectory . '/php';
+ $staging = $queue . '/staging';
+
+ try {
+ $builds = $data['build'] === 'all' ?
$this->listCompletedBuilds($staging) : [$data['build']];
+
+ foreach ($builds as $build) {
+ $source = $staging . '/' . $build;
+ $destination = $queue . '/' . $build;
+ if (!is_file($source) || is_link($source)) {
+ throw new RuntimeException('Completed staged PHP build not found.',
404);
+ }
+ if (file_exists($destination) || is_link($destination)) {
+ throw new RuntimeException('A PHP build with this filename is already
queued: ' . $build, 409);
+ }
+ }
+
+ foreach ($builds as $build) {
+ if (!@rename($staging . '/' . $build, $queue . '/' . $build)) {
+ throw new RuntimeException('Failed to queue staged PHP build ' .
$build, 500);
+ }
+ }
+
+ http_response_code(200);
+ } catch (RuntimeException $error) {
+ http_response_code($error->getCode());
+ echo 'Error: ' . $error->getMessage();
+ }
+ }
+
+ private function listCompletedBuilds(string $staging): array
+ {
+ if (!is_dir($staging)) {
+ return [];
+ }
+
+ $entries = @scandir($staging);
+ if ($entries === false) {
+ throw new RuntimeException('Failed to list staged PHP builds.', 500);
+ }
+
+ return array_filter($entries, static function (string $build) use ($staging): bool {
+ $path = $staging . '/' . $build;
+ return preg_match('/\A' . self::BUILD_FILENAME_PATTERN . '\z/',
$build) === 1
+ && is_file($path) && !is_link($path);
+ });
+ }
+}
diff --git a/tests/Console/Command/PhpCommandTest.php b/tests/Console/Command/PhpCommandTest.php
index 218da51..a962d12 100644
--- a/tests/Console/Command/PhpCommandTest.php
+++ b/tests/Console/Command/PhpCommandTest.php
@@ -5,6 +5,9 @@
use App\Actions\GetListing;
use App\Actions\UpdateReleasesJson;
+use App\Http\Controllers\PhpController;
+use App\Http\Controllers\PhpReleaseController;
+use App\Http\DeferredCallbacks;
use PHPUnit\Framework\Attributes\DataProvider;
use PHPUnit\Framework\TestCase;
use App\Console\Command\PhpCommand;
@@ -176,6 +179,89 @@ public function testCommandHandlerWithMissingTestPackZip(): void
$this->assertEquals(1, $result, "Command should return failure.");
}
+ public static function stagedReleaseModes(): array
+ {
+ return [
+ 'selected build' => [false],
+ 'all completed builds' => [true],
+ ];
+ }
+
+ #[DataProvider('stagedReleaseModes')]
+ public function testStagedBuildsArePublishedOnlyAfterRelease(bool $releaseAll): void
+ {
+ $build = 'php-8.4.1-Win32-vs17-x64.zip';
+ $artifact = $this->baseDirectory . '/artifact.zip';
+ $this->stageBuilds([$build, 'php-test-pack-8.4.1.zip'], $artifact);
+
+ $queue = $this->buildsDirectory . '/php';
+ $request = $this->baseDirectory . '/request.json';
+ file_put_contents($request, json_encode([
+ 'url' => 'file://' . $artifact,
+ 'token' => 'unused-token',
+ 'staging' => true,
+ ]));
+
+ $previousBuildsDirectory = getenv('BUILDS_DIRECTORY');
+ putenv('BUILDS_DIRECTORY=' . $this->buildsDirectory);
+ try {
+ ob_start();
+ try {
+ (new PhpController($request))->handle();
+ $response = ob_get_contents();
+ } finally {
+ ob_end_clean();
+ }
+ $this->assertSame(200, http_response_code());
+ $stagedBuild = json_decode($response, true, 512,
JSON_THROW_ON_ERROR)['build'];
+ $staging = $queue . '/staging';
+ $this->assertDirectoryExists($staging);
+ $this->assertFileDoesNotExist($staging . '/' . $stagedBuild);
+ DeferredCallbacks::invoke();
+ $this->assertFileEquals($artifact, $staging . '/' . $stagedBuild);
+
+ $otherBuild = 'php-' . bin2hex(random_bytes(16)) . '.zip';
+ $incompleteBuild = 'php-' . bin2hex(random_bytes(16)) .
'.zip.part';
+ copy($artifact, $staging . '/' . $otherBuild);
+ touch($staging . '/' . $incompleteBuild);
+
+ $command = new PhpCommand(new GetListing(), new UpdateReleasesJson());
+ $command->options = ['base-directory' => $this->baseDirectory,
'builds-directory' => $this->buildsDirectory];
+ $releases = $this->baseDirectory . '/releases';
+ $this->assertSame(0, $command->handle());
+ $this->assertFileDoesNotExist($releases . '/' . $build);
+ $this->assertFileDoesNotExist($releases . '/releases.json');
+ $this->assertFileExists($staging . '/' . $stagedBuild);
+
+ file_put_contents($request, json_encode(['build' => $releaseAll ?
'all' : $stagedBuild]));
+ (new PhpReleaseController($request))->handle();
+ $this->assertSame(200, http_response_code());
+ $this->assertFileDoesNotExist($staging . '/' . $stagedBuild);
+ $this->assertFileEquals($artifact, $queue . '/' . $stagedBuild);
+ if ($releaseAll) {
+ $this->assertFileDoesNotExist($staging . '/' . $otherBuild);
+ $this->assertFileEquals($artifact, $queue . '/' . $otherBuild);
+ } else {
+ $this->assertFileEquals($artifact, $staging . '/' . $otherBuild);
+ $this->assertFileDoesNotExist($queue . '/' . $otherBuild);
+ }
+ $this->assertFileExists($staging . '/' . $incompleteBuild);
+ $this->assertFileDoesNotExist($queue . '/' . $incompleteBuild);
+ $this->assertFileDoesNotExist($releases . '/' . $build);
+
+ $this->assertSame(0, $command->handle());
+ $this->assertFileDoesNotExist($queue . '/' . $stagedBuild);
+ $this->assertFileDoesNotExist($queue . '/' . $otherBuild);
+ $this->assertFileExists($releases . '/' . $build);
+ $this->assertFileEquals($releases . '/' . $build, $releases .
'/archives/' . $build);
+ $this->assertFileEquals($releases . '/' . $build, $releases .
'/latest/php-8.4-Win32-vs17-x64-latest.zip');
+ } finally {
+ DeferredCallbacks::clear();
+ header_remove();
+ putenv($previousBuildsDirectory === false ? 'BUILDS_DIRECTORY' :
'BUILDS_DIRECTORY=' . $previousBuildsDirectory);
+ }
+ }
+
public function testCommandHandlesMissingBaseDirectory(): void
{
$command = new PhpCommand(new GetListing(), new UpdateReleasesJson());
diff --git a/tests/Http/Controllers/DeletePendingJobControllerTest.php
b/tests/Http/Controllers/DeletePendingJobControllerTest.php
index 1f172b8..c874a77 100644
--- a/tests/Http/Controllers/DeletePendingJobControllerTest.php
+++ b/tests/Http/Controllers/DeletePendingJobControllerTest.php
@@ -54,6 +54,27 @@ public function testDeletesPhpJobAndLock(): void
unlink($inputFile);
}
+ public function testDeletesOnlyTheStagedPhpBuild(): void
+ {
+ $build = 'php-0123456789abcdef0123456789abcdef.zip';
+ $queue = $this->tempDir . '/php';
+ mkdir($queue . '/staging', 0755, true);
+ file_put_contents($queue . '/' . $build, 'queued build');
+ file_put_contents($queue . '/staging/' . $build, 'staged build');
+
+ $input = $this->tempDir . '/request.json';
+ file_put_contents($input, json_encode(['type' => 'php',
'job' => 'staging/' . $build], JSON_THROW_ON_ERROR));
+
+ ob_start();
+ (new DeletePendingJobController($input, $this->tempDir))->handle();
+ $output = ob_get_clean();
+
+ static::assertSame(200, http_response_code());
+
static::assertJsonStringEqualsJsonString('{"status":"deleted"}',
$output);
+ static::assertFileDoesNotExist($queue . '/staging/' . $build);
+ static::assertStringEqualsFile($queue . '/' . $build, 'queued build');
+ }
+
/**
* @throws JsonException
*/
diff --git a/tests/Http/Controllers/ListBuildsControllerTest.php
b/tests/Http/Controllers/ListBuildsControllerTest.php
index 2b818da..77c2890 100644
--- a/tests/Http/Controllers/ListBuildsControllerTest.php
+++ b/tests/Http/Controllers/ListBuildsControllerTest.php
@@ -12,6 +12,8 @@
class ListBuildsControllerTest extends TestCase
{
+ private const string STAGED_BUILD =
'php/staging/php-0123456789abcdef0123456789abcdef.zip';
+
public function testHandleOutputsBuildListing(): void
{
$tempDir = $this->createTempBuildDirectory();
@@ -29,9 +31,10 @@ public function testHandleOutputsBuildListing(): void
static::assertSame(200, http_response_code());
static::assertArrayHasKey('builds', $data);
- static::assertCount(2, $data['builds']);
+ static::assertCount(3, $data['builds']);
static::assertSame('php/build-one.zip',
$data['builds'][0]['path']);
- static::assertSame('winlibs/run/info.json',
$data['builds'][1]['path']);
+ static::assertSame(self::STAGED_BUILD, $data['builds'][1]['path']);
+ static::assertSame('winlibs/run/info.json',
$data['builds'][2]['path']);
$this->removeDirectory($tempDir);
}
@@ -63,11 +66,12 @@ private function decodeJson(string $json): array
private function createTempBuildDirectory(): string
{
$base = sys_get_temp_dir() . '/list-builds-' . uniqid();
- mkdir($base . '/php', 0755, true);
+ mkdir($base . '/php/staging', 0755, true);
mkdir($base . '/winlibs/run', 0755, true);
file_put_contents($base . '/php/build-one.zip', 'fake-zip-data');
touch($base . '/php/build-one.zip', 1730000000);
+ file_put_contents($base . '/' . self::STAGED_BUILD, 'staged-zip-data');
file_put_contents($base . '/winlibs/run/info.json', '{}');
touch($base . '/winlibs/run/info.json', 1730003600);