It happened! Yii3 is officially released after years of intensive development and polishing.

Yii was always following the same principles of being performant, flexible but with good defaults, practice-oriented, simple, explicit, and consistent. Yii3 is not an exception.

While Yii 1.1 and Yii 2.0 are good frameworks, Yii3 was born to improve things even more, addressing the following drawbacks:

1. Yii 2.0 had a closed ecosystem with difficulties configuring general PHP packages.
2. Some magic and implicitness. Non-standard PHP behavior for objects introduced in Yii 2.0.
3. PHP standards compatibility and modern PHP usage were not in place due to backwards compatibility constraints.
4. Some anti-patterns, such as the service locator being available out of the box. That was affecting overall projects' testability and maintainability in the long run.

In the following we will summarize some of the highlights of this long-awaited release. You may check out the Getting Started section if you want to rush to try it out first.

Independent packages ¶

Compared to Yii 1.1 and Yii 2.0 which were monolithic frameworks, Yii3 is a package ecosystem with more than 130 official packages. These packages could be used in any PHP code or as a whole framework relatively similar to Yii 2.0 or Yii 1.1. Application templates help a lot in this case.

Application templates ¶

There are three application templates available out of the box:

• Web — for classic server-rendered applications.
• API — for APIs.
• Console — for console-only tools and background workers.

Unlike Yii 2.0, these are very minimalistic, so you start with basic things such as routing, configuration, DI container, or environment already wired together for you. But, at the same time, additional functionality, such as connecting to a database, isn't in templates by default. Install only what you need—no bloat, just solutions.

Ability to use any packages ¶

Instead of focusing on Yii-specific extensions, as it was with Yii 2.0, we've made the framework to work well with any PHP packages available at Packagist, be they PSR-compatible ones, Symfony packages, or generic PHP code. The container is able to configure any of these.

Yii3 embraces the entire PHP ecosystem instead of reinventing the wheel. It integrates seamlessly with any PHP library. No vendor lock-in. No proprietary APIs. Just modern PHP standards enabling you to leverage the entire ecosystem's innovation.

First-class DI container ¶

The central part of the framework is its dependency injection container. It brings all the individual packages together, automatically resolving dependencies and helping to obtain classes requested. Usual usage is very simple and explicit:

return [
   // Interface to class mapping
   EngineInterface::class => EngineMarkOne::class,
   
   // Detailed configuration
   MyServiceInterface::class => [
       'class' => MyService::class,
       '__construct()' => [42],
       'setDiscount()' => [10],
   ],

   // Factory closures
   'api' => static fn(ApiConfig $config) => new ApiClient($config),
];

// Dependencies are automatically injected based on type hints
final readonly class MyController
{
   public function __construct(
       private CacheInterface $cache
   ) {}
}

Another advantage of the container is that it is very fast and works at runtime. Your configuration is what is actually executed, so there is no magic, and you can even step-debug it with XDebug if needed.

Configuration ¶

Following the traditional way of configuring things with Yii 2.0, we've extracted what was included into an advanced application supporting multiple environments, config overrides, etc. The configuration in Yii3 is very powerful and could be configured to follow basically any layout of the project if needed. By default, application templates are supplying configuration that is divided into web (or API) and console, also having some common shared configs. The configuration is divided into two main parts there: DI container configuration, which maps configured classes to interfaces, and parameters, which are used for configuring these classes.

'yiisoft/view' => [
    'basePath' => null,
    'parameters' => [
        'assetManager' => Reference::to(AssetManager::class),
        'applicationParams' => Reference::to(ApplicationParams::class),
        'aliases' => Reference::to(Aliases::class),
        'urlGenerator' => Reference::to(UrlGeneratorInterface::class),
        'currentRoute' => Reference::to(CurrentRoute::class),
    ],
],

'yiisoft/yii-view-renderer' => [
    'viewPath' => null,
    'layout' => '@src/Web/Shared/Layout/Main/layout.php',
    'injections' => [
        Reference::to(CsrfViewInjection::class),
    ],
],

Security ¶

Similar to Yii 1.1 and Yii 2.0, we take security seriously. It was considered when implementing every package, such as the presentation layer and database abstraction.

As for features:

• Access control abstraction
• RBAC implementation for access control
• JWT authentication
• User abstraction for applications
• Middleware for handling proxy chains and headers
• Third-party authentication client.

There are also helpers for common security-related actions, such as the CSRF-protection package.

Documentation contains a dedicated guide page with established security response processes.

Databases ¶

Yii 2.0 had an exceptional database abstraction layer. At first, we extracted it into a separate package and then reimagined and improved it. It resulted in yiisoft/db, which is database access, schema management, and a powerful query builder. Extra tools and storage, such as migrations, database caching, etc., were built on top of DB as well as a more explicit but still rapid Active Record implementation.

$posts = $connection
   ->select(['id', 'title', 'created_at'])
   ->from('{{%posts}}')
   ->where(['status' => 'published'])
   ->andWhere(['>', 'views', 1000])
   ->orderBy(['created_at' => SORT_DESC])
   ->limit(10)
   ->all();

Other than our own database layer, you can use Cycle ORM or Doctrine, make queries using PDO or native drivers. Whatever you prefer. Yii3 does not force you to stick to a single implementation.

Data abstraction ¶

Powerful data abstraction yiisoft/data, and widgets for it, such as grid view, are there and are perfect for creating powerful universal admin panels. The abstraction includes data formatting, pagination, sorting, and an ability to use any data source with any action/presentation and vice versa.

Caching  ¶

Caching got even more advanced than in Yii 2.0. First of all, out of the box there's a cache stampede protection. Second, cache drivers are PSR-16 compatible. That means you can use any PSR-16 implementation for a very specific storage, and it will work right away.

The following backends were implemented by our team already:

• APCu
• DB
• Files
• Memcached
• Redis

Standards first ¶

Similar to caching, the framework leverages PSR interfaces for more:

• Logging so you can either stick to Yii's logger or replace it with Monolog if you prefer it.
• Middleware so you can bring endless solutions from Packagist, such as CORS handling, and use these without any changes to the code.
• Request-response abstraction that allows optimal testing and worker mode.
• Even a DI container could be either replaced or combined with another PSR-compliant one.

Standards-first architecture ensures your code stays portable and future-proof while maintaining full access to modern PHP tooling.

Worker mode ¶

In traditional PHP servers, framework initialization and database connection are done for every request, which is not great for performance. Yii3 may run in worker mode together with RoadRunner, Swoole, or FrankenPHP. In this mode it initializes once and then serves many request-response cycles, which results in drastically lower response times.

While this mode is great, the state is largely shared between multiple request-response processing, so developers should take care of isolating the state (or not storing it at all) and potential memory leaks. Yii3 helps with it a lot: all the packages were designed either to not use any state or to reset it properly on every start of the request.

Everything for classic web applications ¶

Not every project should be an API with a client so everything for classic server-rendered web applications is available: Widgets, Views with template engines support such as Twig, Forms, asset management, HTML helpers, etc.

Additionally, there are ready-to-use widgets for Bootstrap 5 and Bulma.

A toolset for building APIs ¶

Yii3 provides many tools that help build APIs:

• Data response that takes care of data presentation.
• Swagger support.

We plan to add more in the future but the current set is already enough for building powerful APIs.

HTTP layer and networking ¶

Yii3 works with the HTTP layer on a more precise level than previous versions of the framework and follows PSR interfaces. On top of these relatively low-level interfaces, there are handy abstractions:

• HTTP helpers that define response codes and more
• Cookies
• Download Response Factory  to allow sending files from an application

Additionally, network utilities are there to help with the IP protocol. 

User input and validator ¶

Yii3 has a powerful validator powered by attributes, the ability to fill forms with data from HTTP (input-http) or elsewhere, tools to work with forms, and more.

<?php

declare(strict_types=1);

namespace App\Web\Echo;

use Yiisoft\FormModel\FormModel;
use Yiisoft\Validator\Label;
use Yiisoft\Validator\Rule\Length;

final class Form extends FormModel
{
    #[Label('The message to be echoed')]
    #[Length(min: 2)]
    public string $message = '';
}

Helpers ¶

There are various helpers available to simplify common programming tasks.

• Arrays
• Files
• JSON
• Strings
• VarDumper

Internationalization ¶

Since the Yii framework community and the team members are from all over the world, we take internationalization seriously and understand it very well.

Out of the box, Yii3 has:

• Message translation with intl-powered ICU formatting.
• Support in a view layer.
• Support in the router.

Testing ¶

Proper dependency Inversion makes it easy to unit test the code created with Yii3. Following PSR for request and response allows you to perform API testing without actually running an HTTP server.

To ease testing even more, a set of test-specific PSR implementations are provided by yiisoft/test-support.

Error handling ¶

We value developers' time. That's why we pay attention to error messages and the error page. All these are exceptionally useful. Messages provide context. We'll never use "Error" as a message. Additionally, we took it to the next level with "friendly exceptions." In development mode these are rendered with the information block that explains why the error happened and how to likely fix it. In the future we'll try to provide a button that will automatically try to apply the fix.

The error page contains the error. For each stack trace level, it displays the source code. The line where the error happened is highlighted. Stacktrace items that are part of the framework packages are collapsed by default because these are tested so much that it's unlikely that the error is there.

The handler itself, yiisoft/error-handler, is even more interesting than the one of Yii2. It handles out-of-memory errors and fatals, can maps certain exception types to custom exceptions, respond in different formats, etc.

Additionally, there is a package to integrate Sentry for error collection.

Documentation ¶

There are the following resources available:

• The definitive guide — the main source about using the framework as a whole.
• Community cookbook — how to do X with Yii3.
• API docs for all packages — all the public API rendered nicely for browsing
• Individual package readme and docs — explains how to use each individual package

Exceptional quality standards ¶

Yii3 maintains exceptional code quality standards across all packages. Every line undergoes rigorous verification through multiple layers of automated testing and analysis. 

For all the packages, we have nearly 100% coverage with tests, strict Psalm/PhpStan types, and a close to 100% mutation score. Every code change is reviewed publicly. All these measures give an exceptionally stable and predictable foundation for your projects.

Predictable releases ¶

The release policy is SemVer. Each package is versioned independently. Patch versions never break anything while fixing bugs. The minor version introduces enhancements and features but is still compatible. The major version introduces backwards incompatible changes requiring code updates.

And more ¶

There are many additional features that are less exciting but are very important:

• Aliases
• Events
• Profiler
• Requirements checker
• Mailer
• Console
• Mutex locks with various backends

Likely we forgot to mention some parts of the framework, so go ahead and explore.

Useful resources ¶

Below are some useful links about Yii3:

• Check out the nice landing page here.
• The guide is here. We recommend the "getting started" first.
• API docs are available as well.
• Yii3 packages. Don't forget to star these!
• Telegram group.
• Yii project site
• Yii Facebook group
• Yii X feeds
• Yii LinkedIn group

Thank you! ¶

Thank you for your support and patience! We did it together. All the core team members, community contributors, and backers.

We're pretty sure the Yii3 codebase will serve us well in at least the next 10 years or even more.

Future plans are:

1. Guide improvements and missing pieces.
2. More package releases to enrich the ecosystem and tooling. Queue, the debug panel, and Gii already work well, but we're still polishing these.
3. Checking feedback, fixing, and improving things.
4. Website improvements.

Merry Christmas and Happy New Year! Enjoy!