Download the PHP package woweb/laravel-version-endpoint without Composer

Laravel version endpoint

A signed, read-only /__version endpoint that reports what a Laravel application is actually running: the PHP version, the framework version, the deployed git tag and commit, the hash of the deployed composer.lock, and the versions of the runtimes around it.

It exists for inventory tooling. Something has to answer the question "which version of this application is live, and is anything underneath it out of support" without a person logging in to look. This package answers that question over HTTP, to one caller, and to nobody else.

How it is protected

The caller signs a short message with an ed25519 private key and sends it in two headers. The application verifies that signature with the matching public key.

That direction matters. The public key sits in the application's environment and is not a secret, so an application that is compromised leaks nothing that lets anyone impersonate the caller or read any other application. The signed message is the request timestamp plus the request path, so a captured request cannot be replayed once its timestamp falls outside the tolerance window, and it cannot be pointed at a different path.

Every failure, including a missing key, answers 404. Without a valid signature the endpoint is indistinguishable from a path that does not exist.

Requirements

PHP 8.2 or newer with ext-sodium, and Laravel 12 or 13.

Installation

The service provider is auto-discovered and registers the route. Publish the config only if you want to change something:

1. Generate a keypair

On the machine that will do the probing:

Keep the private key on the caller. One keypair can serve every application, or you can issue one per application; the package does not care which you choose.

2. Configure the application

Optional:

REGISTER_VERSION_FILE is resolved against the application base path when it is relative, and used as given when it is absolute. Keep it outside public/.

3. Write the deploy facts on every deploy

The command records the tag, commit, branch, Node.js version and deploy timestamp in the version file. The sha, branch and Node.js version are read from the checkout when they are not passed. The endpoint reads that file instead of shelling out to git per request, so a web request never starts a subprocess.

There is no fallback. If a deploy does not run this command, the endpoint reports null for the git fields, which is honest: nothing knows what was deployed.

The command also answers to register:build-version, so an application that already had a command by that name can adopt the package without touching its deploy pipeline in the same release.

4. Sign the request on the caller

The path in the signed message is the path the application sees. A proxy that rewrites the path breaks verification, which shows up as an unexplained 404 after a deploy.

The response

runtimes can carry:

• nodejs, from the deploy;
• the distribution id and version from the os-release file, for example debian or alpine;
• postgresql, when the default database connection runs on PostgreSQL;
• redis or valkey, from the default Redis connection.

Valkey reports a redis_version as well, but that is a protocol compatibility number: reporting it as Redis would produce a wrong end of life verdict, so the Valkey version wins and decides the slug.

Every runtime lookup runs only after the signature has been verified, reads no application data, and is wrapped on its own. An engine that is down, absent or not configured drops out of the payload rather than failing the response: a 500 would hide the whole version picture behind a single outage. Switch individual lookups off in the config if you would rather not have them at all.

The contract

The response shape is the point of this package, so it is versioned with the package itself.

• A patch release changes behaviour that is not visible in the response.
• A minor release may add a field to the response, or a key to runtimes. Consumers must ignore fields they do not know.
• A major release removes or renames a field, changes the type of one, or changes the signed message format.

Consumers should read the package version from the application's composer.lock to know which contract they are talking to.

What it deliberately does not do

• It does not report host names, credentials, configuration values, schema or extension lists. Only version metadata.
• It does not run git or any other subprocess while serving a request.
• It does not sign the response. The caller authenticates itself to the application, not the other way around; a caller that needs the channel authenticated should use TLS, which it needs anyway.
• It does not detect MySQL or MariaDB. Their version strings do not map onto one support cycle without guessing, and a wrong end of life verdict is worse than a missing one.

Configuration reference

Everything lives in config/version-endpoint.php:

The route is registered outside any middleware group, so it carries no session or cookie handling.

Development

License

MIT. See LICENSE.md.