Getting Started

You are now assessing 0.2.1, and the only release artifact is a compare link. The changelog for 0.2.1 contains nothing but compare/0.1.1...0.2.1 — no features, no fixes, no breaking-change callouts. That is itself the first thing to investigate: the jump from 0.1.1 to 0.2.1 skips a minor version on a 0.x package, which by semver convention means possibly breaking, and the maintainer has not told you what changed. Do not upgrade blind and do not assume the previous assessment's API notes still hold.

First 15 minutes, in this order:

Read the diff, not the notes. The release notes are empty, so the diff is the changelog:
```
git clone [email protected]:h2Entwicklung/sign-checker.git /tmp/sign-checker
cd /tmp/sign-checker && git log --oneline 0.1.1..0.2.1
git diff 0.1.1..0.2.1 -- src/ config/ composer.json
```
Or open the compare URL directly. You are looking specifically for: renamed/removed public classes, changed method signatures, new required config keys, and touched composer.json constraints.
composer.json at 0.2.1 — check whether the php and illuminate/* constraints moved. This is the single most likely thing a 0.2.x bump changed, and it determines whether you can install at all.
README.md — the only source of truth for the public API. Re-read it rather than trusting memory of 0.1.1; if the README wasn't updated alongside the code, prefer src/.
src/ — find the service provider, facade, and main contract. That class is your integration surface regardless of what the README claims.
tests/ — if they exist, they are the most reliable documentation of intended usage, and they're the fastest way to spot a changed signature.

Then install pinned and publish config:

composer require "h2entwicklung/sign-checker:0.2.1"
php artisan vendor:publish

First use case: verifying an inbound signature before trusting a payload — a webhook, an uploaded signed document, or a signed URL. Smoke-test it in php artisan tinker with known-good and known-bad samples before wiring it into a controller, and re-run that smoke test after this upgrade specifically. Confirm three behaviors explicitly: valid input returns success, tampered input returns failure, malformed input throws or returns an error distinct from failure. If the package collapses "invalid" and "error" into one boolean, you've found your first design constraint.

Implementation Patterns

Wrap it behind your own interface. Given the maintenance profile — 0 stars, 0 dependents, and now a 0.2.1 with an empty changelog — never let H2Entwicklung\... types leak past one adapter class:

interface SignatureVerifier
{
    public function verify(string $payload, string $signature): bool;
}

Bind the package implementation in a service provider. When the package goes stale (or you replace it with openssl_verify, robrichards/xmlseclibs, or firebase/php-jwt), you change one binding instead of grepping the codebase. The 0.1.1 → 0.2.1 jump is a live demonstration of why: if the signature changed, the blast radius is one file.

Verify raw request bodies in middleware, not controllers. Webhook signatures cover the exact bytes sent, and Laravel's request parsing can alter them:

$payload = $request->getContent();          // raw, not ->all()
$signature = $request->header('X-Signature');

Register the middleware only on the webhook route group and throw AuthenticationException on failure so it lands in your normal 401 handling.

Separate the cryptographic check from the business decision. The package tells you bytes match a key. It does not tell you the signer is someone you trust, that the certificate hasn't expired, or that the timestamp is fresh. Layer those checks in your own code — issuer allowlist, expiry window, replay protection via a nonce/timestamp cache — rather than assuming the package covers them.

Move document verification to a queue. Anything involving file I/O plus OpenSSL is not request-cycle work. Dispatch a job, persist a SignatureVerification model with status (verified / rejected / error), and notify the user asynchronously. This also gives you an audit trail, which signature verification almost always needs.

Pull all key material from config. Certificate paths, public keys, and algorithms should come from config/sign-checker.php reading env(), with the actual files in storage/app/keys/ (gitignored) or a secrets manager. Hardcoded paths are the most common reason this kind of package works in dev and fails in CI. Diff the published config between 0.1.1 and 0.2.1 — a new required key is the classic silent breakage.

Add a validation rule for user-uploaded signatures/documents so form-level failures produce clean 422s, and keep the deeper verification in the job.

Fake it in tests. If the package ships no fake, bind a stub implementation of your own interface in the test container. Do not hit real certificates in feature tests — generate a throwaway keypair in the test setup and keep fixtures small.

Gotchas and Tips

A 0.1.1 → 0.2.1 bump with an empty changelog is a warning, not a courtesy. Treat 0.2.1 as a potentially breaking release until the diff says otherwise. Read git log 0.1.1..0.2.1 before accepting the upgrade, and re-run your valid/tampered/malformed tests against it.
Raw body is everything. $request->all() re-encodes JSON and breaks signatures nondeterministically. Always getContent().
Base64 signatures in URLs. A + becomes a space if the signature arrives as a query param. rawurldecode() it before verifying. This bug looks like "intermittent signature failures" and burns hours.
OpenSSL fails quietly. If the package returns false with no detail, check openssl_error_string() in a debug wrapper. Add logging around the call — you need to distinguish bad signature, expired cert, unsupported algorithm, and missing key file. If 0.2.1 didn't add error granularity, this wrapper is still on you.
Never log the secret or the full key. Log a hash of the canonical payload and the key's fingerprint instead.
Large files blow memory. If you're verifying signed PDFs or archives, confirm whether the package reads the file into a string — and re-confirm after the upgrade, since this is exactly the code that moves between minor versions. If it does, cap upload size and stream/hash upstream.
Maintenance risk is still the headline. No dependents means no community pressure to fix breakage, and a release with a blank changelog means no signal about what broke. Pin the exact version you validated — "h2entwicklung/sign-checker": "0.2.1", not ^0.2 — commit composer.lock, and keep a realistic replacement budget. If Laravel 11/12 blocks install, prefer a local fork with widened constraints over --ignore-platform-reqs:
```
"repositories": [{"type": "vcs", "url": "[email protected]:yourorg/sign-checker.git"}]
```
Extension point is the container. If the package offers a driver/manager pattern, register a custom driver rather than editing vendor code; if it doesn't, your adapter interface is the extension point. If 0.2.1 introduced a driver pattern, that's the one upgrade worth taking eagerly.
Upgrade the test suite first. Before adopting 0.2.1, write valid/tampered/malformed cases against your adapter. Those three tests are what let you swap the implementation later without fear — and with a changelog that says nothing, they are the only verification you will get.

Sign Checker Laravel Package

Getting Started

Implementation Patterns

Gotchas and Tips