# sigv4-php: AWS request signing in plain PHP, no SDK

sigv4-php signs AWS requests with Signature Version 4, makes presigned URLs, and finds credentials through an environment, container and instance-role chain. It is for PHP developers who make a handful of AWS calls, such as sending an email, putting an object or reading a parameter, and do not want the AWS SDK, its dependency tree or a vendor/ directory. The code is at [https://github.com/IndianOpinion/sigv4-php](https://github.com/IndianOpinion/sigv4-php), under the MIT licence, and v0.1.0 was released on 12 November 2026.

It has no runtime dependencies and needs PHP 8.1 or later. We wrote it from scratch. It is independent of and not affiliated with any third-party plugin it integrates with.

## The problem

A PHP application that makes a few AWS calls has two choices. It can install the AWS SDK. That pulls in an HTTP client, PSR packages and promise libraries, and it needs Composer. Plugins and small tools that ship as plain files cannot carry that cleanly, and two copies of the SDK in one PHP process, one per plugin, collide.

Or it can hand-roll the signer. Every guide shows the happy path. The traps are at the edges: the path is double-encoded for every service except S3, query parameters have empty values, headers have odd whitespace, session tokens exist, credentials expire mid-process, and the instance metadata service answers only to a session token. The result is a 403 SignatureDoesNotMatch the first time a path contains a space.

The signing algorithm is fully specified by AWS, deterministic and covered by an official test suite. So a small, correct and tested signer is a reasonable thing to ship.

## What it does

- Signs a request with SigV4, in header form, and returns the method, URL, headers and body for you to send with any HTTP client. The signer never sends anything.

- Presigns URLs, with expiries from 1 to 604800 seconds.

- Has S3 rules for service s3: single path encoding, no normalisation, and the content hash header added for you.

- Finds credentials in order: static, environment, container, then EC2 instance metadata (IMDSv2 only). The first that answers wins.

- Caches credentials and refreshes them five minutes before expiry. They can be shared between PHP-FPM workers through an encrypted cache.

- Retries once after an expired token, through RetryOnExpired, and parses AWS error bodies with ErrorInfo.

## How it works

The signer follows the AWS documentation step by step: canonical request, string to sign, HMAC key derivation over date, region and service, then the signature. It reads the clock once, so the timestamp and the scope date cannot disagree across midnight. It is pure: the same input and the same clock give the same bytes. The README says the core algorithm is about a hundred lines inside Signer, and the whole library, with validation, presigning, providers, caches and transports, about 2,900.

The credential chain moves on only for "not found". Anything else stops the chain and raises, because silently falling through to a different identity is worse than failing. When nothing is found, the exception lists every provider and why it declined.

Credential fetches use a small transport. It ignores proxy settings, follows no redirects, always verifies TLS, has short timeouts and caps responses at 64 KiB. Instance metadata is a token PUT, then the role, then the credentials, with the role name validated before it goes into a URL. A discovered role name is remembered, so a warm fetch is one request.

Signing, from the README:

$credentials = DefaultChain::create()->getCredentials(); // env, container, then instance role

$request = new Request('POST', $url, ['Content-Type' => 'application/json'], $json);
$signed = (new Signer())->sign($request, $credentials, 'eu-west-2', 'ses');

// $signed->getUrl(), getMethod(), getHeaderLines(), getBody()

When you hold a raw S3 object key, Request::fromRawPath() encodes it once, so nothing is encoded twice. Presigning follows the same shape, with presign($request, $credentials, $region, 's3', 3600).

## Guard rails

- Credentials in a shared cache are always encrypted with libsodium secretbox, under a key derived from an application secret you supply. Static and environment credentials are never written to a shared cache.

- Instance metadata is IMDSv2 only. There is no fallback to the older version.

- A container credentials URI over plain http is allowed only to loopback and the documented container hosts.

- With temporary credentials, a presigned URL cannot outlive the credentials that signed it, so the signer refuses a longer expiry by default.

- Every secret-bearing parameter carries #[\SensitiveParameter]. On PHP 8.1 you should set zend.exception_ignore_args=On, the production default.

- Logs and the debug form getRedactedCanonicalRequest() hide the session token.

- Volatile headers such as connection, user-agent and expect are never signed.

## What review changed

The reviewer's comment on the build pull request lists these fixes made before the merge:

- Secrets leaked into stack traces. With PHP's built-in defaults, a failing new Credentials(...) printed the first 15 characters of the secret key. Every secret-bearing parameter is now marked sensitive, and SecretLeakTest scans full traces with arguments on. It failed before the fix and passes after.

- A required option was missing. The PRD asked for a way to send the session token without signing it. It had been dropped, and a test worked around it. It is now SigningOptions(sessionTokenAfterSigning: true).

- isClockSkew() reported every 403 signature error as clock skew, which would send a reader after the clock when the signature was simply wrong. It now counts signature errors only when the message says the signature expired or is not yet current.

- Header whitespace trimming used \s, which can change with the locale. It is now an explicit ASCII class.

## Limits and what is next

- There are no shared config or credentials files, SSO, credential_process or web identity yet. The README lists them under "Not yet".

- No chunked payload signing, no SigV4A and no SigV2.

- No retries other than the single refresh-and-resend helper.

- A + in a query string is a literal plus, as AWS reads it. Encode spaces as %20.

- The stream transport has a single timeout, where curl honours connect and total separately.

- Use the AWS SDK instead when you call many services, or need retries with backoff, paginators, waiters, streaming uploads or SSO. This library will not grow into those.

Test status: this is v0.1.0. At review, 317 tests passed with 1 skipped, and all 76 cases from the official SigV4 test vectors passed (38 vectors, header and presigned variants). PHPStan level 8 and phpcs were clean. The examples run offline against fake endpoints. The test fixtures are the official ones, under Apache-2.0 with their own licence notice. CI has not yet run on GitHub, because the token lacked the scope to push the workflow, although the README carries a CI badge. The library has been tested against stubs and fakes, not against live AWS endpoints. There are no open issues.

## Install

The package is not on Packagist yet, so first add a Composer vcs repository entry for https://github.com/IndianOpinion/sigv4-php.

composer require indianopinion/sigv4-php

It needs PHP 8.1 or later. hash and json are always present. curl is used for credential fetches when loaded, and PHP streams otherwise. sodium is needed only for the encrypted shared cache, and apcu only for the APCu adapter. Without Composer, copy bootstrap.php and src/ and require bootstrap.php.

[All 47 utilities](https://indianopinion.org/blog/open-source/) · [sigv4-php on GitHub](https://github.com/IndianOpinion/sigv4-php)

Canonical: https://indianopinion.org/blog/open-source/sigv4-php/

AI disclosure: Every summary and comment here is written by AI and published automatically, without a person reviewing each article. We do no original reporting. How this works: https://indianopinion.org/ai-use-policy/
