> For the complete documentation index, see [llms.txt](https://quantumphp.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://quantumphp.gitbook.io/docs/getting-started/upgrade-guide.md).

# Upgrade Guide (2.x to 3.0)

This guide summarizes required changes when upgrading Quantum projects from 2.x to 3.0.

## 1. Platform Requirements

* Minimum PHP version is now `7.4`.
* PHP `7.3` and older are no longer supported.

## 2. Route and Middleware Response Contract

3.0 enforces explicit `Quantum\Http\Response` returns.

* Route handlers must return `Response`.
* Middleware `apply()` must return `Response`.
* `redirect()` and `redirectWith()` now return `Response` and should be returned by caller.

Before:

```php
$route->get('home', function ($response) {
    $response->html('ok');
});
```

After:

```php
$route->get('home', function (): Quantum\Http\Response {
    return response()->html('ok');
});
```

## 3. Request and Response Access

`Request` and `Response` are now instance-based in runtime flow.

* Use `request()` and `response()` helpers.
* Remove assumptions based on static facade behavior.

## 4. Dependency Injection Is Stricter

* `Di::get()` no longer auto-registers dependencies.
* Dependencies must be explicitly registered before retrieval.

Typical pattern:

```php
if (!Di::isRegistered(SomeService::class)) {
    Di::register(SomeService::class);
}

$service = Di::get(SomeService::class);
```

## 5. Renamed Base Classes

Update references:

* `Quantum\Service\QtService` -> `Quantum\Service\Service`
* `Quantum\Middleware\QtMiddleware` -> `Quantum\Middleware\Middleware`
* `Quantum\Migration\QtMigration` -> `Quantum\Migration\Migration`
* `Quantum\Console\QtCommand` -> `Quantum\Console\CliCommand`

## 6. Environment API Changes

* `Environment` is no longer a static singleton.
* Use `environment()` helper and methods like `isProduction()`, `isTesting()`, `isStaging()`, `isDevelopment()`, `isLocal()`.

## 7. Model and DB Behavior Updates

* `DbModel` fetch methods now return new model instances instead of mutating current model.
* `create()` resets model state before insert flows.
* DB-generated primary keys are synced back after save.

## 8. Router and Execution Changes

* Middleware ordering is prepend-based (later middleware wraps earlier).
* Route name uniqueness is validated at build time.
* Legacy implicit controller resolution paths were removed.

## 9. Upgrade Verification Checklist

After code changes, run:

```bash
vendor/bin/phpunit
composer phpstan
composer cs:check
```

Then smoke-test:

* Authentication routes
* Redirect/error flows
* Middleware validation branches
* Pagination and model fetch flows


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://quantumphp.gitbook.io/docs/getting-started/upgrade-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.