Understanding Yii 3 ¶

1. Introduction
2. Changes overview
3. Yii 3 composer packages
4. Running your first Yii 3 powered application

Since this Wiki page is getting bigger and bigger, I decided to document things in a Yii 3 project instead.

Project source can be found at https://github.com/machour/yii3-kitchen-sink Live web site: https://yii3.idk.tn/

Follow the repo/website to get fresher informations, or better yet, pull the project and run it by yourself to get acquainted with Yii3

Introduction ¶

This document is intended for an audience already familiar with Yii2. It's meant to bring together all information related to Yii 3 in one place to make it easier to get on track.

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. Starting with 3.0, Yii will follow the Sementic Versionning.

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]

Changes overview ¶

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

Source code splitting ¶

The framework source code have 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 enable you to cherry pick the packages you need to compose your application.

This re-organisation is also a great news for maintainance, as these packages will be released separately, thus allowing more frequent updates.

Autoloading ¶

The custom PHP class autoloader have 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 ¶

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.

Yii 3 takes another approach. Every package bundle its own configuration, and will probably work out of the box. And you may override them, if you need to, from your configuration file.

This is all done by leveraging the hiqdev/composer-config-plugin composer plugin, which takes care of scanning & 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.

Packages authors will have the responsibility to avoid introducing BC breaks, by adopting a strict sementical versionning.

Dependencies injection ¶

[TODO]

Yii 3 composer packages ¶

Here are the new packages introduced in Yii 3, which can be found in this official list.

Let's introduce them briefly:

The Framework ¶

• yiisoft/yii-core

This is the new kernel of Yii. It defines the base framework and its core features like behaviors, i18n, mail, validation..

You will rarely want to directly install yiisoft/yii-core. Instead, you will install one or more of the following:

• yiisoft/yii-console
• yiisoft/yii-web
• yiisoft/yii-rest

This three packages, considered as Extensions, are responsible for implementing the basic functionnalities of each "channel" they refer to:

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

Librairies ¶

In Yii 3, libraries do not depend on Yii and are meant to be usable outside the framework. Their package name is yiisoft/something without yii-prefix.

• yiisoft/log : The logging library
• yiisoft/di : The dependency injection library
• yiisoft/cache : The caching library
• yiisoft/active-record : The Active Record library
• yiisoft/rbac : The role base access control library
• yiisoft/view : The view rendering library
• yiisoft/mutex : The mutex lock implementation
• yiisoft/db : The database library

Drivers for yiisoft/db ¶

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

• yiisoft/db-mysql MySQL support for Yii
• yiisoft/db-mssql MSSQL support for Yii
• yiisoft/db-pgsql PostgreSQL support for Yii
• yiisoft/db-sqlite SQLite support for Yii
• yiisoft/db-oracle Oracle Database support for
• yiisoft/db-sphinx Sphinx support
• yiisoft/db-redis Redis support
• yiisoft/db-mongodb MongoDB support
• yiisoft/db-elasticsearch Elastic

Extensions ¶

Extensions depends (at least) on yii-core. Aside from the 3 extensions already encountered above (yii-console, yii-web, yii-api), these packages are available

Development ¶

• yiisoft/yii-debug The debug panel
• yiisoft/yii-gii The code generator extension
• yiisoft/yii-dev Tools for framework contributors

View rendering engines ¶

• yiisoft/yii-twig Twig Extension

Data rendering ¶

• yiisoft/yii-dataview : ListView, GridView, DetailView

JS & CSS Frameworks integration ¶

• yiisoft/yii-bootstrap3 : Bootstrap 3 assets & widgets
• yiisoft/yii-bootstrap4 : Bootstrap 4 assets & widgets
• yiisoft/yii-jquery jQuery, ActiveForm

Widgets ¶

• yiisoft/yii-captcha The CAPTCHA Extension
• yiisoft/yii-masked-input : The masked input widget (depends on jquery)

Misc ¶

• yiisoft/yii-swiftmailer Swift Mailer Extension
• yiisoft/yii-http-client HTTP client extension
• yiisoft/yii-auth-client External authentication extension

Yii project template and application bases ¶

• yiisoft/yii-project-template

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 starters to install in your project next:

• yiisoft/yii-base-cli
• yiisoft/yii-base-web
• yiisoft/yii-base-api

Let's try running the web base template in the next section.

Running your first Yii 3 powered application ¶

Let's try running a web application using Yii 3, and the provided project template.

Installing the project template ¶

composer create-project --prefer-dist --stability=dev yiisoft/yii-project-template myapp
cd myapp

Here's the created structure:

.
├── LICENSE
├── README.md
├── composer.json
├── composer.lock
├── config
│   ├── common.php
│   └── params.php
├── docker-compose.yml
├── hidev.yml
├── public
│   ├── assets
│   ├── favicon.ico
│   ├── index.php
│   └── robots.txt
├── runtime
└── vendor

You won't be able to start the web server right away using ./vendor/bin/yii serve, as it will complain about not knowing the "app" class.

In fact, this project template only introduce the bare minimum in your application: Caching, Dependencies injection, and Logging. The template doesn't make an assumption about the kind of application you're building (web, cli, api).

You could start from scratch using this bare template, select the extensions & packages you want to use and start developing, or you can pick one of the three starters provided.

Installing the web starter ¶

Since we're doing a web application, we will need an asset manager. We can pick either one of those:

• Asset-packagist & composer-merge-plugin (requires only PHP)
• Foxy (requires npm or yarn)

Let's go with foxy (personal taste since composer is so slow from Tunisia):

composer require "foxy/foxy:^1.0.0"

We can now install the yii-base-web starter and run our application:

composer require yiisoft/yii-base-web
vendor/bin/yii serve

By visiting http://localhost:8080/, you should now see something like this:

Checking back our project structure, nothing really changed, aside from the creation of these three entries:

• node_modules/
• package-lock.json
• package.json

So where do what we see in the browser comes from ?

Exploring yiisoft/yii-base-web structure: ¶

If you explore the folder in vendor/yiisoft/yii-base-web, you will see that the template is in fact a project itself, with this structure:

.
├── LICENSE.md
├── README.md
├── composer.json
├── config
│   ├── common.php
│   ├── console.php
│   ├── env.php
│   ├── messages.php
│   ├── params.php
│   └── web.php
├── phpunit.xml.dist
├── public
│   └── css
│       └── site.css
├── requirements.php
├── runtime
└── src
    ├── assets
    │   └── AppAsset.php
    ├── commands
    │   └── HelloController.php
    ├── controllers
    │   └── SiteController.php
    ├── forms
    │   ├── ContactForm.php
    │   └── LoginForm.php
    ├── mail
    │   └── layouts
    ├── messages
    │   ├── et
    │   ├── pt-BR
    │   ├── ru
    │   └── uk
    ├── models
    │   └── User.php
    ├── views
    │   ├── layouts
    │   └── site
    └── widgets
        └── Alert.php

The folders and files should make sense to you if you already developed applications using Yii2 and the basic template.