# Upgrade from 3.1 to 3.2

A guide for upgrading 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:

```json
"statamic/cms": "3.2.*"
```

Then run:

``` shell
composer update statamic/cms --with-dependencies
```

## Changes

### Medium impact changes
- [Nav Page IDs](#nav-page-ids)

### Low impact changes
- [Nav GraphQL Changes](#nav-graphql-changes)
- [Getting tree pages by ID](#getting-tree-pages-by-id)
- [Tree root is now an array](#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:

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

In 3.2:

``` yaml
-
  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 }}
```

:::tip
If you're using the `nav` tag to output a _collection's_ tree (e.g. your `pages` collection), the `id` will still be the entry ID.
:::

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](/graphql.md#recursive-tree-branches):

```graphql
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:

```graphql
page {
    url
    edit_url
}
```

After:

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

If you added any [custom fields](/graphql.md#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:

```graphql
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.

```graphql
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']`.