Upgrade guide
Move from Atlas 2.x to 3.x without surprising your users.
Upgrading from Atlas 2.x to 3.x is a deliberate release, not a Composer bump. Treat it like shipping a new major of your own product: freeze features, migrate, verify, then publish.
Photo by AbsolutVision on Unsplash.
Breaking changes
| Area | 2.x | 3.x |
|---|---|---|
| API prefix | /api/v2 | /api/v3 |
| Eager load | withCount() helpers | unified with() |
| Config cache | optional | required in production |
| CLI | atlas2 | atlas |
Recommended sequence
- Read the migration checklist and assign owners.
- Upgrade a staging clone first and keep 2.x docs available for rollback.
- Publish a 3.x documentation release only after smoke tests pass.
bashupgrade.sh
composer require atlas/framework:^3.0 --with-all-dependencies
php atlas upgrade --from=2.x
php atlas testWarning
Do not delete your 2.x documentation channel until every production customer has migrated. Historical channels remain useful for support.
Updated Aug 5, 2026