Upgrading from Version 2.0

If you haven't used Yii2, you can skip this section and get directly to "getting started" section.

While sharing some common ideas and values, Yii 3 is conceptually different from Yii 2. There is no easy upgrade path, so first check maintenance policy and end-of-life dates for Yii 2 and consider starting new projects on Yii 3 while keeping existing ones on Yii 2.

PHP requirements

Yii3 requires PHP 8.2 or above. As a result, there are language features used that weren't used in Yii 2:

• Type declarations
• Return type declarations
• Class constant visibility
• Named arguments
• Anonymous classes
• ::class
• Generators
• Variadic functions
• Readonly properties
• Readonly classes
• Constructor property promotion
• Attributes

Preliminary refactoring

It's a good idea to refactor your Yii 2 project before porting it to Yii 3. That would both make porting easier and benefit the project in question while it's not moved to Yii 3 yet.

Use DI instead of the service locator

Since Yii 3 is forcing you to inject dependencies, it's a good idea to prepare and switch from using service locator (Yii::$app->) to DI container.

If usage of DI container is problematic for whatever reason, consider moving all calls to Yii::$app-> to controller actions and widgets and passing dependencies manually from a controller to what needs them.

See Dependency injection and container for an explanation of the idea.

Introduce repositories for getting data

Since Active Record isn't the only way to work with a database in Yii 3, consider introducing repositories that would hide details of getting data and gather them in a single place. You can later redo it:

final readonly class PostRepository
{
    public function getArchive()
    {
        // ...
    }
    
    public function getTop10ForFrontPage()
    {
        // ...
    }

}

Separate domain layer from infrastructure

In case you have a rich complicated domain, it's a good idea to separate it from infrastructure provided by a framework that's all the business logic has to go to framework-independent classes.

Move more into components

Yii 3 services are conceptually similar to Yii 2 components, so it's a good idea to move reusable parts of your application into components.

Things to learn

Docker

Default application templates are using Docker to run application. It's a good idea to learn how to use it and use it for your own projects since it provides a lot of benefits:

1. Exactly the same environment as in production.
2. No need to install anything except Docker itself.
3. Environment is per application, not per server.

Environment variables

Yii3 application templates are using environment variables to configure pars of the application. The concept is very handy for Dockerized applications but might be alien to users of Yii 1.1 and Yii 2.

Handlers

Unlike Yii2, Yii3 doesn't have controllers per se. Instead, it uses handlers which are similar to controllers but different.

Application structure

Suggested Yii3 application structure is different from Yii 2. It's described in application structure.

Despite that, Yii3 is flexible, so it's still possible to use a structure similar to Yii 2 with Yii 3.