<!--
  Upgrading to v14
  From the Iris book, chapter 23, covering Iris 14.0.0 on Go 1.27.
  Import path: github.com/kataras/iris/v14
  Canonical page: https://iris-go.com/docs/upgrading-to-v14/
-->
# Chapter 23: Upgrading to v14

This book documents Iris v14 (`github.com/kataras/iris/v14`) exclusively.
Every chapter describes the current API with no comparisons to earlier
releases, so there is nothing in these pages to translate or un-learn. This
chapter exists for one audience: readers bringing an existing v12 codebase
forward. It tells you where the migration instructions live and how to
approach the upgrade. It deliberately does not duplicate the instructions
themselves.

## Background

In semantic versioning (the `MAJOR.MINOR.PATCH` numbering Go modules
follow), a **major version upgrade** is the one release type allowed to
break existing code: names may be removed, defaults may change, and your
program may need edits before it compiles again. Breaking changes are not
carelessness; they are how a framework sheds accumulated mistakes and
unsafe defaults without carrying them forever: v14's secure-by-default
behavior exists precisely because a major release was the one moment it
could change. Go makes the break explicit by putting the major version in
the import path (`/v12`, `/v14`), so the two versions cannot be confused
inside one build.

## The Canonical Migration Guide

The step-by-step migration guide ships with the framework repository and is
maintained alongside the code:

<https://github.com/kataras/iris/blob/main/MIGRATION.md>

Because it lives next to the source, it (not this book) is the authority
on what changed between v12 and v14. Read it end to end before touching your
code. The guide covers these categories, each with the exact replacement and
a code sample:

| Category                  | What it covers                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Import path               | The module major version moves from `/v12` to `/v14`; a one-shot `sed` rewrite for `go.mod` and every source file.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| Package relocations       | `sessions`, `cache`, `websocket`, `i18n`, `view` and `versioning` move under `middleware/`; `middleware/recover` becomes `middleware/recovery`, `mvc` becomes `controller/mvc`, `macro` becomes `core/router/macro`, `x/client` becomes `client`, `x/jsonx` becomes `rest/types`, `x/errors` becomes `rest/errors`. `middleware/logger`, `hero` and `x/sqlx` are removed outright. Four moved packages also changed their entry point (`cache`, `recovery`, `websocket`, `view`).                                                                                                                                                                                                                                                                             |
| Removed v12 APIs          | Each removed name with its single v14 replacement: `Party` → `Router`, `PartyConfigure`/`Configure` → `Router`/`Routing`, `Done`/`DoneGlobal`/`UseGlobal` → the `Use` family, `OnErrorCode` → `HandleNoRoute`/`HandleNoMethod` plus `rest/errors`, `iris.Configuration` → `iris.Options`, `RegisterView`/`ctx.View` → `middleware/view`, `iris.Addr`/`iris.TLS`/`iris.AutoTLS`/`Runner` → `app.Run(iris.ServerOptions{...})`, `SetContextErrorHandler` → the `ContextOptions.ErrorHandler` option, `HandleDir`/`Favicon` → `controller/fileserver`, `WWW`/`SubdomainRedirect` → `middleware/rewrite`, `app.Validator` → `ContextOptions.RequestValidator`, `hero` → the built-in DI container, `mvc.GRPC` → `controller/mvc.GRPC`, `Dependencies()` → `DI()`. |
| Context method changes    | The largest mechanical part: all eighteen `URLParam*` methods become `ctx.Query().Get*`; `ctx.Params().Get` becomes `GetString`; request and response accessors split by name, so `ctx.GetHeader(k)` becomes `ctx.Header(k)` and the v12 two-argument `ctx.Header(k, v)` setter becomes `ctx.SetHeader(k, v)` (with `ResponseHeader` new for reading back what a handler set); the same split applies to content type. Plus the rename table (`GetCookie` → `CookieValue`, `GetBody` → `Body`, ...), the removed methods (`CallFunc`, `ReflectValue`, ...) and the new `SetLogoutFunc`/`Logout` signatures.                                                                                                                                                   |
| Corrected v12 behavior    | Two v12 bugs whose fixes change runtime behavior without needing a code change: `ReadBody` with a `*string`/`*[]byte` target no longer re-reads a drained body, and `KitchenTime.Scan` no longer drops the minutes of a database `TIME` value.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| Secure-by-default changes | Session cookies ship `Secure` with `SameSite=Lax` (and the `sessions.Database` interface is redesigned around generics); JWT verification reads the `Authorization` header only, dropping the v12 `?token=` extractor; CORS no longer advertises credentials alongside a wildcard origin; `AddCookie` defaults to `SameSite=Lax`.                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Opt-in hardening          | New v14 capabilities that are off by default: `ContextOptions.BodyMaxMemory` request-body caps, `session.RegenerateID` after sign-in, `fileserver.BlockHidden` for static servers, `requestid.ServerOnlyGenerator`, a raised `password.Cost`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

One path-parameter change is easy to miss because most code keeps
compiling. In v12 a `{id:uuid}` parameter stored the text it validated;
in v14 it stores a parsed `uuid.UUID`. Read it with
`ctx.Params().GetUUID("id")` or `ctx.BindParam[uuid.UUID]("id")`.
`ctx.Params().GetString("id")` still works and returns the canonical
lowercase form, while `ctx.BindParam[string]("id")` on such a route
now answers 400.

## Tips for a Smooth Upgrade

- **Read the guide first, code second.** Skim all of MIGRATION.md before
  editing anything, and note which categories your application actually
  touches. Most codebases hit the import path, one or two removed APIs and
  one behavior change. Knowing which ones up front turns the upgrade from
  exploration into execution.
- **Upgrade in one commit on a dedicated branch.** The import-path change
  touches every Go file, so there is no useful halfway state. Do the
  mechanical rewrite, apply the API replacements, and land the whole move as
  a single reviewable change.
- **Let the compiler drive.** The removed v12 names fail loudly: the renames
  were designed so that every stale call site becomes a compile error rather
  than code that silently misbehaves. Work through the error list with the
  guide's replacement table beside you; when the build is green, the
  mechanical part of the migration is done.
- **Run your test suite before shipping.** The secure-by-default changes
  (session cookie attributes, JWT extraction, CORS credentials) and the two
  corrected v12 bugs compile without complaint but behave differently at
  runtime. Your integration tests are where those differences surface; see
  [Chapter 16](https://iris-go.com/docs/testing/) if you need to add coverage first.

## Starting Fresh

If you are not carrying v12 code, skip the migration guide entirely. New
projects should start from [Chapter 1](https://iris-go.com/docs/getting-started/) or the
framework's [TUTORIAL.md](https://github.com/kataras/iris/blob/main/TUTORIAL.md),
both of which build directly on
the recommended v14 stack: `iris.NewBuilder`, dependency-injected services,
controllers with `Routing(r iris.Router)` methods and the response helpers.
There is no v12 heritage in that path and nothing to migrate away from.

## Summary

- This book covers v14 only; upgrades from v12 are documented in the
  maintained guide at
  <https://github.com/kataras/iris/blob/main/MIGRATION.md>.
- The guide covers the import path move, package relocations, removed v12
  APIs with their replacements, the `Context` method changes, corrected v12
  behavior, secure-by-default changes and recommended opt-in hardening.
- Upgrade deliberately: read the guide first, land the change in one commit,
  let compile errors guide the API replacements, and rely on your test suite
  to catch the behavior changes that compile cleanly.
- Fresh projects have nothing to migrate. Start at
  [Chapter 1](https://iris-go.com/docs/getting-started/).

## Further Reading

- [MIGRATION.md](https://github.com/kataras/iris/blob/main/MIGRATION.md):
  the maintained, authoritative v12-to-v14 migration guide this chapter
  points at.
- [Semantic Versioning](https://semver.org/): the `MAJOR.MINOR.PATCH`
  contract and what each part promises about compatibility.
- [Go Modules: Developing a major version update](https://go.dev/doc/modules/major-version):
  why the major version appears in the import path and how `/v14`
  releases work.