Standardize signature parity testing, add Docker for testing

.dockerignore

@@ -0,0 +1,7 @@
+.git
+.gitignore
+.docker-cache
+.env
+vendor
+node_modules
+transloadit-*.tgz

.gitignore

@@ -8,3 +8,4 @@ env.sh
 .phpunit.cache
 .aider*
 .env
+.docker-cache/

CHANGELOG.md

@@ -1,28 +1,36 @@
-## Versions
+# Changelog
 
-### [main](https://github.com/transloadit/php-sdk/tree/main)
+## [main](https://github.com/transloadit/php-sdk/tree/main)
 
-diff: https://github.com/transloadit/php-sdk/compare/3.2.0...main
+diff: https://github.com/transloadit/php-sdk/compare/3.3.0...main
 
-### [3.2.0](https://github.com/transloadit/php-sdk/tree/3.2.0)
+## [3.3.0](https://github.com/transloadit/php-sdk/tree/3.3.0)
+
+- Replace the custom Node parity helper with the official `transloadit` CLI for Smart CDN signatures
+- Add a Docker-based test harness and document the parity workflow
+- Randomize system-test request signatures and document optional `auth.nonce` usage to avoid replay protection failures
+
+diff: https://github.com/transloadit/php-sdk/compare/3.2.0...3.3.0
+
+## [3.2.0](https://github.com/transloadit/php-sdk/tree/3.2.0)
 
 - Implement `signedSmartCDNUrl`
 
 diff: https://github.com/transloadit/php-sdk/compare/3.1.0...3.2.0
 
-### [3.1.0](https://github.com/transloadit/php-sdk/tree/3.1.0)
+## [3.1.0](https://github.com/transloadit/php-sdk/tree/3.1.0)
 
 - Pass down `curlOptions` when `TransloaditRequest` reinstantiates itself for `waitForCompletion`
 
 diff: https://github.com/transloadit/php-sdk/compare/3.0.4-dev...3.1.0
 
-### [3.0.4-dev](https://github.com/transloadit/php-sdk/tree/3.0.4-dev)
+## [3.0.4-dev](https://github.com/transloadit/php-sdk/tree/3.0.4-dev)
 
 - Pass down `curlOptions` when `TransloaditRequest` reinstantiates itself for `waitForCompletion`
 
 diff: https://github.com/transloadit/php-sdk/compare/3.0.4...3.0.4-dev
 
-### [3.0.4](https://github.com/transloadit/php-sdk/tree/3.0.4)
+## [3.0.4](https://github.com/transloadit/php-sdk/tree/3.0.4)
 
 - Ditch `v` prefix in versions as that's more idiomatic
 - Bring back the getAssembly() function
@@ -34,7 +42,7 @@ diff: https://github.com/transloadit/php-sdk/compare/3.0.4...3.0.4-dev
 
 diff: https://github.com/transloadit/php-sdk/compare/v2.0.0...3.0.4
 
-### [v2.1.0](https://github.com/transloadit/php-sdk/tree/v2.1.0)
+## [v2.1.0](https://github.com/transloadit/php-sdk/tree/v2.1.0)
 
 - Fix for CURL deprecated functions (thanks @ABerkhout)
 - CI improvements (phpunit, travis, composer)
@@ -43,7 +51,7 @@ diff: https://github.com/transloadit/php-sdk/compare/v2.0.0...3.0.4
 
 diff: https://github.com/transloadit/php-sdk/compare/v2.0.0...v2.1.0
 
-### [v2.0.0](https://github.com/transloadit/php-sdk/tree/v2.0.0)
+## [v2.0.0](https://github.com/transloadit/php-sdk/tree/v2.0.0)
 
 - Retire host + protocol in favor of one endpoint property,
   allow passing that on to the Request object.
@@ -52,14 +60,14 @@ diff: https://github.com/transloadit/php-sdk/compare/v2.0.0...v2.1.0
 
 diff: https://github.com/transloadit/php-sdk/compare/v1.0.1...v2.0.0
 
-### [v1.0.1](https://github.com/transloadit/php-sdk/tree/v1.0.1)
+## [v1.0.1](https://github.com/transloadit/php-sdk/tree/v1.0.1)
 
 - Fix broken examples
 - Improve documentation (version changelogs)
 
 diff: https://github.com/transloadit/php-sdk/compare/v1.0.0...v1.0.1
 
-### [v1.0.0](https://github.com/transloadit/php-sdk/tree/v1.0.0)
+## [v1.0.0](https://github.com/transloadit/php-sdk/tree/v1.0.0)
 
 A big thanks to [@nervetattoo](https://github.com/nervetattoo) for making this version happen!
 
@@ -69,7 +77,7 @@ A big thanks to [@nervetattoo](https://github.com/nervetattoo) for making this v
 
 diff: https://github.com/transloadit/php-sdk/compare/v0.10.0...v1.0.0
 
-### [v0.10.0](https://github.com/transloadit/php-sdk/tree/v0.10.0)
+## [v0.10.0](https://github.com/transloadit/php-sdk/tree/v0.10.0)
 
 - Add support for Strict mode
 - Add support for more auth params
@@ -79,15 +87,15 @@ diff: https://github.com/transloadit/php-sdk/compare/v0.10.0...v1.0.0
 
 diff: https://github.com/transloadit/php-sdk/compare/v0.9.1...v0.10.0
 
-### [v0.9.1](https://github.com/transloadit/php-sdk/tree/v0.9.1)
+## [v0.9.1](https://github.com/transloadit/php-sdk/tree/v0.9.1)
 
 - Improve documentation
 - Better handling of errors & non-json responses
 - Change directory layout
 
 diff: https://github.com/transloadit/php-sdk/compare/v0.9...v0.9.1
 
-### [v0.9](https://github.com/transloadit/php-sdk/tree/v0.9)
+## [v0.9](https://github.com/transloadit/php-sdk/tree/v0.9)
 
 - Use markdown for docs
 - Add support for signed GET requests
@@ -97,12 +105,12 @@ diff: https://github.com/transloadit/php-sdk/compare/v0.9...v0.9.1
 
 diff: https://github.com/transloadit/php-sdk/compare/v0.2...v0.9
 
-### [v0.2](https://github.com/transloadit/php-sdk/tree/v0.2)
+## [v0.2](https://github.com/transloadit/php-sdk/tree/v0.2)
 
 - Add error handling
 
 diff: https://github.com/transloadit/php-sdk/compare/v0.1...v0.2
 
-### [v0.1](https://github.com/transloadit/php-sdk/tree/v0.1)
+## [v0.1](https://github.com/transloadit/php-sdk/tree/v0.1)
 
 The very first version

CONTRIBUTING.md

@@ -0,0 +1,95 @@
+# Contributing
+
+Feel free to fork this project. We will happily merge bug fixes or other small
+improvements. For bigger changes you should probably get in touch with us
+before you start to avoid not seeing them merged.
+
+## Testing
+
+### Basic Tests
+
+```bash
+make test
+```
+
+### System Tests
+
+System tests require:
+
+1. Valid Transloadit credentials in environment:
+
+```bash
+export TRANSLOADIT_KEY='your-auth-key'
+export TRANSLOADIT_SECRET='your-auth-secret'
+```
+
+Then run:
+
+```bash
+make test-all
+```
+
+### Node.js Reference Implementation Parity Assertions
+
+The SDK includes assertions that compare Smart CDN URL signatures and regular request signatures with our reference Node.js implementation. To run these tests:
+
+1. Requirements:
+
+   - Node.js 20+ with npm
+   - Ability to execute `npx transloadit smart_sig` (the CLI is downloaded on demand)
+   - Ability to execute `npx transloadit sig` (the CLI is downloaded on demand)
+
+2. Run the tests:
+
+```bash
+export TRANSLOADIT_KEY='your-auth-key'
+export TRANSLOADIT_SECRET='your-auth-secret'
+TEST_NODE_PARITY=1 make test-all
+```
+
+If you want to warm the CLI cache ahead of time you can run:
+
+```bash
+npx --yes transloadit smart_sig --help
+```
+
+For regular request signatures, you can also prime the CLI by running:
+
+```bash
+TRANSLOADIT_KEY=... TRANSLOADIT_SECRET=... \
+  npx --yes transloadit sig --algorithm sha1 --help
+```
+
+CI opts into `TEST_NODE_PARITY=1`, and you can optionally do this locally as well.
+
+### Run Tests in Docker
+
+Use `scripts/test-in-docker.sh` for a reproducible environment:
+
+```bash
+./scripts/test-in-docker.sh
+```
+
+This builds the local image, runs `composer install`, and executes `make test-all` (unit + integration tests). Pass a custom command to run something else (composer install still runs first):
+
+```bash
+./scripts/test-in-docker.sh vendor/bin/phpunit --filter signedSmartCDNUrl
+```
+
+Environment variables such as `TEST_NODE_PARITY` or the credentials in `.env` are forwarded, so you can combine parity checks and integration tests with Docker:
+
+```bash
+TEST_NODE_PARITY=1 ./scripts/test-in-docker.sh
+```
+
+## Releasing a new version
+
+To release, say `3.2.0` [Packagist](https://packagist.org/packages/transloadit/php-sdk), follow these steps:
+
+1. Make sure `PACKAGIST_TOKEN` is set in your `.env` file
+1. Make sure you are in main: `git checkout main`
+1. Update `CHANGELOG.md` and `composer.json`
+1. Commit: `git add CHANGELOG.md composer.json && git commit -m "Release 3.2.0"`
+1. Tag, push, and release: `source .env && VERSION=3.2.0 ./release.sh`
+
+This project implements the [Semantic Versioning](http://semver.org/) guidelines.

Dockerfile

@@ -0,0 +1,27 @@
+# syntax=docker/dockerfile:1
+
+FROM php:8.3-cli AS base
+
+ENV COMPOSER_ALLOW_SUPERUSER=1
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+       git \
+       unzip \
+       zip \
+       libzip-dev \
+       curl \
+       ca-certificates \
+    && docker-php-ext-configure zip \
+    && docker-php-ext-install zip \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=composer:2 /usr/bin/composer /usr/bin/composer
+
+# Install Node.js (for transloadit CLI parity checks)
+RUN curl -fsSL https://deb.nodesource.com/setup_22.x | bash - \
+    && apt-get install -y --no-install-recommends nodejs \
+    && npm install -g npm@latest \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /workspace

README.md

@@ -276,6 +276,23 @@ echo '</pre>';
 
 <dfn>Signature Authentication</dfn> is done by the PHP SDK by default internally so you do not need to worry about this :)
 
+If you script the same request payload multiple times in quick succession (for example inside a health check or tight integration test loop), add a random nonce to keep each signature unique:
+
+```php
+$params = [
+  'auth' => [
+    'key'     => 'MY_TRANSLOADIT_KEY',
+    'expires' => gmdate('Y/m/d H:i:s+00:00', strtotime('+2 hours')),
+    'nonce'   => bin2hex(random_bytes(16)),
+  ],
+  'steps' => [
+    // …
+  ],
+];
+```
+
+The nonce is optional for regular usage, but including it in heavily scripted flows prevents Transloadit from rejecting repeated identical signatures.
+
 ### Signature Auth (Smart CDN)
 
 You can use the `signedSmartCDNUrl` method to generate signed URLs for Transloadit's [Smart CDN](https://transloadit.com/services/content-delivery/):
@@ -522,74 +539,6 @@ All of the following will cause an error string to be returned:
 
 **_Note_**: You will need to set waitForCompletion = True in the $Transloadit->createAssembly($options) function call.
 
-## Contributing
-
-Feel free to fork this project. We will happily merge bug fixes or other small
-improvements. For bigger changes you should probably get in touch with us
-before you start to avoid not seeing them merged.
-
-### Testing
-
-#### Basic Tests
-
-```bash
-make test
-```
-
-#### System Tests
-
-System tests require:
-
-1. Valid Transloadit credentials in environment:
-
-```bash
-export TRANSLOADIT_KEY='your-auth-key'
-export TRANSLOADIT_SECRET='your-auth-secret'
-```
-
-Then run:
-
-```bash
-make test-all
-```
-
-#### Node.js Reference Implementation Parity Assertions
-
-The SDK includes assertions that compare URL signing with our reference Node.js implementation. To run these tests:
-
-1. Requirements:
-
-   - Node.js installed
-   - tsx installed globally (`npm install -g tsx`)
-
-2. Install dependencies:
-
-```bash
-npm install -g tsx
-```
-
-3. Run the test:
-
-```bash
-export TRANSLOADIT_KEY='your-auth-key'
-export TRANSLOADIT_SECRET='your-auth-secret'
-TEST_NODE_PARITY=1 make test-all
-```
-
-CI opts-into `TEST_NODE_PARITY=1`, and you can optionally do this locally as well.
-
-### Releasing a new version
-
-To release, say `3.2.0` [Packagist](https://packagist.org/packages/transloadit/php-sdk), follow these steps:
-
-1. Make sure `PACKAGIST_TOKEN` is set in your `.env` file
-1. Make sure you are in main: `git checkout main`
-1. Update `CHANGELOG.md` and `composer.json`
-1. Commit: `git add CHANGELOG.md composer.json && git commit -m "Release 3.2.0"`
-1. Tag, push, and release: `source env.sh && VERSION=3.2.0 ./release.sh`
-
-This project implements the [Semantic Versioning](http://semver.org/) guidelines.
-
 ## License
 
 [MIT Licensed](LICENSE)