Upgrading from Version 2.0

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

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

PHP requirements

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

• 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.0 project before porting it to Yii3. That would both make porting easier and benefit the project in question while it's not moved to Yii3 yet.

Use DI instead of the service locator

Since Yii3 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 Yii3, 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

Yii3 services are conceptually similar to Yii 2.0 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 parts of the application. The concept is very handy for Dockerized applications but might be alien to users of Yii 1.1 and Yii 2.0.

Actions

Unlike Yii 2.0, Yii3 does not require controllers. Instead, it uses actions, which are any callables. You can organize these into controllers similar to Yii 2, but it's not required.

Application structure

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

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