Use this guide to upgrade with low risk and clear rollback options.
The package keeps backward-safe runtime defaults:
- default
compatibility_moderemainslegacy - existing core API remains available
- new features are additive and opt-in
Create a small baseline set:
- one representative payload per critical flow
- one integration test that verifies encode/decode behavior
- one log/prompt path where sensitive field redaction is required
- Upgrade package version.
- Keep
compatibility_mode=legacy. - Run tests and compare output for your baseline payloads.
- Add replacer rules for sensitive fields where needed.
- Optionally test
modernmode in staging only.
// config/toon.php
return [
'compatibility_mode' => 'legacy',
'strict_mode' => false,
'delimiter' => 'comma',
];If your workflow requires strict validation:
// only where malformed input must fail hard
'strict_mode' => true,Use legacy when:
- existing downstream consumers expect current output shape
- snapshot stability is more important than modernization
Use modern when:
- you are building new flows
- you want safer nested round trips
- you can validate downstream consumers in controlled rollout
- keep production on
legacy - run staging tests with
modern - compare representative payload outputs
- validate consumer parsers and templates
- switch production after sign-off
If behavior mismatch is detected after upgrade:
- set
compatibility_modeback tolegacy - disable newly introduced replacer transforms
- disable strict decode outside critical validation paths
- rerun baseline payload tests
In most cases rollback is configuration-first, not code removal.
composer validate --strict
vendor/bin/phpunit --configuration phpunit.xml.dist
composer audit