Upgrade from 3.1 to 3.2

Overview

First read through this guide to see if there's anything that you might need to adjust.
When upgrading, Statamic may automate some things for you. They'll be noted below.

In your composer.json, change the statamic/cms requirement:

"statamic/cms": "3.2.*"

Then run:

composer update statamic/cms --with-dependencies

Changes

Medium impact changes

• Nav Page IDs

Low impact changes

• Nav GraphQL Changes
• Getting tree pages by ID
• Tree root is now an array

Nav Page IDs

In a Navigation, each branch now has its own automatically generated ID.
(This doesn't apply to collection trees.)

In 3.1:

-
  url: /some-manually-added-link
-
  entry: some-entry-id

In 3.2:

-
  id: abc-def
  url: /some-manually-added-link
-
  id: ghi-jkl
  entry: some-entry-id

In 3.1, if you were using a nav tag, the {{ id }} variable would be the ID of the entry for entry branches and null for non-entry branches.

In 3.2, the {{ id }} will be the ID of the branch.
To get the ID of the entry, you can use {{ entry_id }}.

If you had this in 3.1:

{{ nav:links }} ... {{ id }} ... {{ /nav:links }}

Change to this for 3.2:

{{ nav:links }} ... {{ entry_id }} ... {{ /nav:links }}

In PHP land, if you were doing $page->id(), you can now do $page->reference() or optional($page->entry())->id().

Nav GraphQL Changes

TreeBranch type split

The TreeBranch type has been split into NavTreeBranch and CollectionTreeBranch types.
Likely the only place you would use this is if you were using the Recursive Tree Branches example:

fragment Fields on TreeBranch {
    # ...
}
fragment RecursiveChildren on TreeBranch {
    # ...
}

PageInterface

The PageInterface now only applies to navs.

Usage in navs

The PageInterface no longer contains all the entry's fields. It now has it's own subset of fields (id, title, url, permalink).

If you needed entry specific fields, you can explicitly query the interface. In this example, url is included, but not edit_url anymore.

Before:

page {
    url
    edit_url
}

After:

page {
    url
    ... on EntryInterface {
        edit_url
    }
}

If you added any custom fields to EntryInterface, it will no longer be added to PageInterface. If you need it there, you can explicitly add it to PageInterface.

Usage in collections

Within a collection's tree, the page is now an EntryInterface.
If you're using EntryPage_x implementations, you should now just use Entry_x implementations:

page {
    ... on EntryPage_Blog_Post { # change to Entry_Blog_post
        # ...
    }
}

Also, within collection trees, since you're now getting the actual entry, page has been deprecated in favor of entry. Both still work but you may want to update it while you're here.

page { # change to entry
  # ...
}

Getting tree pages by ID

$tree->page($id) would previously get a page in a tree by an entry ID.

Now, $tree->page() has been deprecated in favor of $tree->find() which will get a page by its ID, not the entry's ID.
(For collection trees, since entry is the ID, it'll work the same way.)

If you want to find a page by the entry ID, there's a new findByEntry($id) method.

Tree root is now an array

$tree->root() would previous return the entry of the root tree branch.

Now, it'll be the entire array.

If you need the entry, you can do $tree->root()['entry'].