[web-downloads] main: Add support for staging PHP releases

From: Date: Thu, 19 Nov 2026 09:30:13 +0000
Subject: [web-downloads] main: Add support for staging PHP releases
Groups: php.webmaster 
Request: Send a blank email to php-webmaster+get-34226@lists.php.net to get a copy of this message
Author: Shivam Mathur (shivammathur) Date: 2026-11-19T14:41:07+05:30 Commit: https://github.com/php/web-downloads/commit/15e1092215403bc541ced34d62bafe0f78b9cf9c Raw diff: https://github.com/php/web-downloads/commit/15e1092215403bc541ced34d62bafe0f78b9cf9c.diff 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);

« previous php.webmaster (#34226) next »