What is Yii 3?

Yii 3 is the second major rewrite of the Yii framework.

Originally started in the 2.1 branch, it was later decided to switch to the 3.X series because of all the backward compatibility breakage.

This rewrite addresses a lot of issues Yii 2 suffered from, like the framework being too coupled with jQuery, bower, bootstrap. [TODO: add more grieffs about Yii2]

Starting with 3.0, Yii will follow the Semantic Versioning.

Changes Overview

Here are the main changes in Yii 3. You can check the complete CHANGELOG and the UPGRADE guide for an exhaustive list.

Source Code Splitting

The framework source code has been split into several packages, and at its core level, Yii no longer makes assumptions about your development stack, or the features you will be using.

This enables you to cherry-pick the packages you need to compose your application.

This reorganization is also a great news for maintenance, as these packages will be released separately, thus allowing more frequent updates.


The custom PHP class autoloader has been removed in favor of Composer's PSR-4 implementation. This means that in order for Yii to see your classes, you will have to explicitly register your namespace in composer.json. We will see an example later.

PSR Compatibility

Yii 3 takes some positive steps following the PHP-FIG recommendations, by implementing the following PSRs:

  • Logging is now compliant with PSR-3
  • Caching is now compliant with PSR-16
  • Dependency Injection is now compliant with PSR-11

Application Configuration

Yii 3 is configuration based. You can check the Configuration section to see what that means.

Dependency Injection



If you've ever installed an extension using Yii 2, you may/certainly have found yourself on the extension README file, looking for the chunk of configuration to copy/paste in your own config/main.php file.

This can often lead to:

  • a huge configuration file (which you may have decided to split into smaller files)
  • non-trivials configurations update when a new version of the extension is realeased with new/changed configurations options.

In Yii 3, things are configuration-based. Every package bundle its own configuration, and will probably work out of the box.

You can override every and each configuration settings in your own config files.

Yii 3 uses the hiqdev/composer-config-plugin composer plugin, which takes care of scanning and merging all the configurations when you run composer dump-autoload (also know as composer du).

You can read Yii2 projects alternative organization for an in-depth explanation of the motivation behind hiqdev/composer-config-plugin.

When developing with Yii 3, especially the first days, you may find yourself not getting the results expected only to later understand that you forgot to run composer du, and that your new configuration isn't taken into account.

This can be solved in your development environment by calling \hiqdev\composer\config\Builder::rebuild(); from your index.php file.


Here are the new packages introduced in Yii 3, from this official list.

The Framework

  • yiisoft/yii-core : This is the new kernel of Yii. It defines the base framework and its core features like behaviors, validation..

Then there are three important packages, split by channel:

  • yiisoft/yii-console: implements the bases to build a console application (the base Controller for commands, the Command helper, ..)
  • yiisoft/yii-web: implements all that you need to build a web application (Assets management, Sessions, Request handling ..)
  • yiisoft/yii-rest: implements all that you need to build a REST interface (ActiveController, ..)

Other Extensions

Depends on yii-core

The conventional package naming is yiisoft/yii-something.

Aside from the 3 extensions already encountered above (yii-console, yii-web, yii-api), the following packages are available:

View rendering engines
Data rendering
JS & CSS Frameworks integration


Do not depend on yii-core and meant to be usable outside the framework.

The conventional package naming is yiisoft/something, without the "yii-" prefix.

Drivers for yiisoft/db

The various drivers for DB have also been separated into packages:

Project template and application bases

To get you started with your next project.

This is a very basic Yii project template, that you can use to start your development.

You will probably want to pick one or more of these three bases to install in your project next: