Migration Guide
Use this guide to upgrade with low risk and clear rollback options.
Migration Promise
The package keeps backward-safe runtime defaults:
- default
compatibility_mode remains legacy
- existing core API remains available
- new features are additive and opt-in
Before You Upgrade
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 Steps
- 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
modern mode in staging only.
Configuration During Rollout
// 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,
Legacy vs Modern Decision
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
Safe Trial Plan for Modern Mode
- keep production on
legacy
- run staging tests with
modern
- compare representative payload outputs
- validate consumer parsers and templates
- switch production after sign-off
Rollback Plan
If behavior mismatch is detected after upgrade:
- set
compatibility_mode back to legacy
- 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.
Useful Validation Commands
composer validate --strict
vendor/bin/phpunit --configuration phpunit.xml.dist
composer audit
Related Guides