Enhance Bootstrap failures when due to missing snapshot or bootstrap PHP binary

[schneems]

Expected

When setting a custom HEROKU_PHP_PLATFORM_REPOSITORIES , in the event of a failed build, I have enough information to trace the internal logic, so I can debug the problem.

Beyond being used for buildpack dev, this is a documented feature used by customers to host their own extensions https://github.com/heroku/heroku-buildpack-php?tab=readme-ov-file#custom-platform-repositories.

Actual

When setting a php-min for bootstrapping, that is not available in the given S3 bucket the error message is this:

remote: -----> Bootstrapping...
remote:        NOTICE: Default platform repository snapshot not available.
remote:
remote:  !     ERROR: Failed to download minimal PHP for bootstrapping!
remote:  !
remote:  !     This is most likely a temporary internal error. If the problem
remote:  !     persists, make sure that you are not running a custom or forked
remote:  !     version of the Heroku PHP buildpack which may need updating.
remote:
remote:  !     Push rejected, failed to compile PHP app.
remote:
remote:  !     Push failed
remote: Verifying deploy...
remote:
remote: !	Push rejected to thawing-inlet-74685.
remote:

This hints that the snapshot is not available, but does not tell us what URL it looked up. It tells us that the PHP it tried to bootstrap with was not downloadable, but it does not tell us the URL it tried to download from. I hit this in https://github.com/heroku/heroku-buildpack-php/pull/799/files#r2085192167.

Suggestion

In this failure mode, the problem is that the snapshot has not yet been uploaded to the stable bucket of S3. Which means that the following URLs do not exist. When a URL doesn't exist it could be because the base url is wrong or misconfigured, the stack or suffix is wrong or misconfigured, the snapshot URL is incorrect, or it's correct but is missing the version. To fully capture each of these failure modes we can emit the desired URL (the min-php) and where we got the information (or didn't in this case) of where the snapshot lives:

• https://lang-php.s3.us-east-1.amazonaws.com/dist-heroku-24-amd64-stable/packages-c0accbcb71bcc1d97eda4015364b8f223cbd965855eb11e3f643455f2513bad3.json
• https://lang-php.s3.us-east-1.amazonaws.com/dist-heroku-24-amd64-stable/php-min-8.3.21.tar.gz

We could add this information to the build output:

remote:        NOTICE: Default platform repository snapshot not available (`c0accbcb71bcc1d97eda4015364b8f223cbd965855eb11e3f643455f2513bad3`)
remote:
remote:  !     ERROR: Failed to download minimal PHP for bootstrapping!
remote:  !
remote:  !     This is most likely a temporary internal error. If the problem
remote:  !     persists, make sure that you are not running a custom or forked
remote:  !     version of the Heroku PHP buildpack which may need updating.
remote:  !
remote:  !     - Bootstrap URL (not found): https://lang-php.s3.us-east-1.amazonaws.com/dist-heroku-24-amd64-stable/php-min-8.3.21.tar.gz
remote:  !     - Snapshot URL (not found): https://lang-php.s3.us-east-1.amazonaws.com/dist-heroku-24-amd64-stable/packages-c0accbcb71bcc1d97eda4015364b8f223cbd965855eb11e3f643455f2513bad3.json
remote:  ! 
remote:  !
remote:  !     Push rejected, failed to compile PHP app.
remote:
remote:  !     Push failed
remote: Verifying deploy...
remote:
remote: !	Push rejected to thawing-inlet-74685.
remote:

In a related note, when this initial check that produces the warning message is emitted, we could add an else check here

heroku-buildpack-php/bin/compile

Line 245 in ff26615

# if no fallback is allowed, we do nothing - it is possible that $HEROKU_PHP_PLATFORM_REPOSITORIES removes the default repo

and fail early if either there's no custom HEROKU_PHP_PLATFORM_REPOSITORIES or none of the repos have a platform repository and no fallback is allowed.

I also noticed that HEROKU_PHP_PLATFORM_REPOSITORY_SNAPSHOT_FALLBACK is used in this linked code but never mentioned in any documentation.