[github-actions]

Warning

1.2.0 requires PHP 8.2 or later. PHP 7.4, 8.0 and 8.1 are end of life. Composer does
not install 1.2.0 on them and keeps those projects on 1.1.x. Anyone who copies the
sources from the GitHub release instead of using Composer gets no such check and must
stay on 1.1.x on those PHP versions.

queuetoken-v1-php 1.2.0 — Release Notes

Previous version: 1.1.0  •  This version: 1.2.0  •  Compared range: v1.1.0..v1.2.0

This is a minor version bump (1.1.0 → 1.2.0), but it raises the minimum PHP version
to 8.2. Strict semver would make this a major bump; it ships as a minor by decision, as
the library stays on 1.x. The token format, the generated tokens and the public API are
unchanged for PHP 8.2+ users, apart from the items in §4.

1.1.1 was tagged on GitHub but never published to Packagist, and its tag has been removed.
Its only change, the AKAMAI_BOT_MANAGER_HEADER_VALIDATOR token origin (§5), ships in
1.2.0.

Summary of doc-impacting changes

• PHP 8.2 or later is required — see §1.
• The secret key no longer appears in stack traces — see §2.
• Two warnings on PHP 8 are fixed: a deprecation in withValidity() and a warning
  when parsing a malformed token — see §3.
• Implementers: Payload::enqueue() now declares its return type — see §4.
• New token origin TokenOrigin::AKAMAI_BOT_MANAGER_HEADER_VALIDATOR — see §5.

---

1. PHP 8.2 or later required (consumer-facing, breaking)

Requirement	1.1.0	1.2.0
PHP	>=7.4	>=8.2 — tested on 8.2, 8.3, 8.4 and 8.5
ext-openssl	required	required
ext-json	required	removed — JSON is always available since PHP 8.0

We support the oldest PHP version that php.net still supports, and every newer one. PHP
8.2 receives security fixes until 31 December 2026.

connector-php: connector-php 4.4.x accepts any 1.x of this library, so on PHP 8.2+ a
composer update installs 1.2.0 into an existing 4.4.x setup. connector-php's test suite
passes against it. connector-php 4.5.0 will require PHP 8.2 and this version.

Doc change needed: state "PHP 8.2 or later" wherever the library's requirements are
listed, and that PHP 7.4–8.1 users must stay on 1.1.x. The repository README now has a
Requirements section with the same text.

---

2. The secret key is redacted from stack traces (consumer-facing, security)

Every parameter that receives the secret key is now marked with PHP 8.2's
#[\SensitiveParameter]. This covers Token::parse(), EnqueueTokenGenerator::generate(),
EnqueueToken::generate() and parse(), EnqueueTokenPayload::encryptAndEncode() and
deserialize(), and the internal hashing and encryption helpers.

Exception thrown while generating or parsing a token	1.1.0	1.2.0
Secret key in the stack trace's arguments	the key, verbatim	Object(SensitiveParameterValue)

This matters whenever zend.exception_ignore_args is Off, the default in development
php.ini files. Traces end up in framework error pages, logs and error trackers. With
the production default (On), traces carry no arguments at all, so nothing changes there.

Exception types and messages are unchanged.

---

3. PHP 8 warnings fixed (consumer-facing)

• withValidity() with a validity that is not a whole number of seconds (for example
  1500) raised Deprecated: Implicit conversion from float … to int loses precision
  on PHP 8.1 and later. It no longer does. The expiry is still truncated to whole
  seconds, as before; the token header only stores seconds.
• Token::parse() with fewer than three dot-separated parts raised
  Warning: Undefined array key 2 before throwing ArgumentException("Invalid token").
  It now throws the ArgumentException without the warning. Applications whose error
  handler turns warnings into exceptions (most frameworks do) received an ErrorException
  instead of the ArgumentException; they now get the ArgumentException.

Behavior worth noting: tokens whose iss has millisecond precision (for example
1761051863001) parse correctly and keep the milliseconds. This already worked on PHP 8
and failed on PHP 7.4, which is no longer supported.

---

4. Public surface changes (implementer-facing)

Relevant only to code that extends the library's classes or implements its interfaces.

• Payload::enqueue() now declares : EnqueueTokenPayloadGenerator, matching
  Token::enqueue(). A subclass of Payload that overrides enqueue() without a
  compatible return type fails to load. Add the return type to the override.
• EnqueueTokenPayload::addCustomData(string $key, mixed $value) now declares
  mixed for the value. It accepts the same values as before, and overrides with an
  untyped $value remain compatible.
• IEnqueueTokenPayload::encryptAndEncode() marks $secretKey as sensitive. Custom
  implementations are not required to change, but should add #[\SensitiveParameter]
  to their own $secretKey parameter to get the same redaction.
• Unaffected: all other signatures, the exception classes, and the TokenOrigin,
  TokenVersion and EncryptionType constants.

---

5. New token origin (consumer-facing, additive)

TokenOrigin::AKAMAI_BOT_MANAGER_HEADER_VALIDATOR ("AkamaiBotManagerHeaderValidator")
joins CONNECTOR and INVITE_ONLY. Pass it to Payload::enqueue()->withOrigin() to mark
tokens issued by the Akamai Bot Manager header validator.

Doc change needed: list the new origin wherever the token origins are documented.

---

Everything else

• README: the usage examples were in JavaScript syntax (const, Token.enqueue(...),
  token.Token) and could not be used in PHP. They are now valid PHP. Doc action:
  replace any published copy of the old examples.
• Releases: the GitHub tag is now created on the merged release commit, so the tag,
  the GitHub release and the Packagist version all contain the released code. 1.1.1's
  tag pointed at 1.1.0's code, which is why Packagist never published it.
• Dependencies: no runtime dependencies were added. Development only: PHPUnit
  ^9.6.11.

Upgrade

1. Make sure the application runs on PHP 8.2 or later. On older PHP versions, stay on
   1.1.x; Composer does that automatically.
2. Run composer update queueit/queuetoken-v1-php, or require ^1.2.
3. Implementers only: if you override Payload::enqueue(), add the
   : EnqueueTokenPayloadGenerator return type. If you implement IEnqueueTokenPayload,
   consider marking $secretKey with #[\SensitiveParameter].