(draft) Understanding Yii 3

Comparing #13 with #14

Revision #14 was created by samdark on Jun 17, 2022, 6:54:27 AM.

Update to current state of things

Content

# Understanding Yii 3 > Note: The information here is outdated. You can check [yii-demo](https://github.com/yiisoft/yii-demo) for current Yii 3 features.

> 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

> <img src="" />

> 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](https://www.yiiframework.com/doc/guide/2.0/en).*

*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](https://www.yiiframework.com/news/177/yii-adopts-semver-since-version-3-0-0).

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

## Changes overview

Here are the main changes in Yii 3. You can check the complete [CHANGELOG](https://github.com/yiisoft/yii-core/blob/master/CHANGELOG.md#300-under-development) 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](https://www.php-fig.org/) 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](https://github.com/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](https://hiqdev.com/pages/articles/app-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**

<small>[TODO]</small>

## Yii 3 composer packages

Here are the new packages introduced in Yii 3, which can be found in this [official list](https://github.com/yiisoft/docs/blob/master/000-packages.md#yii-framework).

Let's introduce them briefly:

### **The Framework**

* [yiisoft/yii-core](https://github.com/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](https://github.com/yiisoft/yii-console)

* [yiisoft/yii-web](https://github.com/yiisoft/yii-web)

* [yiisoft/yii-rest](https://github.com/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](https://github.com/yiisoft/log) : The logging library

* [yiisoft/di](https://github.com/yiisoft/di) : The dependency injection library

* [yiisoft/cache](https://github.com/yiisoft/cache) : The caching library

* [yiisoft/active-record](https://github.com/yiisoft/active-record) : The Active Record library

* [yiisoft/rbac](https://github.com/yiisoft/log) : The role base access control library

* [yiisoft/view](https://github.com/yiisoft/view) : The view rendering library

* [yiisoft/mutex](https://github.com/yiisoft/mutex) : The mutex lock implementation

* [yiisoft/db](https://github.com/yiisoft/db) : The database library

##### Drivers for yiisoft/db

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

  * [yiisoft/db-mysql](https://github.com/yiisoft/db-mysql) MySQL support for Yii

  * [yiisoft/db-mssql](https://github.com/yiisoft/db-mssql) MSSQL support for Yii

  * [yiisoft/db-pgsql](https://github.com/yiisoft/db-pgsql) PostgreSQL support for Yii

  * [yiisoft/db-sqlite](https://github.com/yiisoft/db-sqlite) SQLite support for Yii

  * [yiisoft/db-oracle](https://github.com/yiisoft/db-oracle) Oracle Database support for

  * [yiisoft/db-sphinx](https://github.com/yiisoft/db-sphinx) Sphinx support

  * [yiisoft/db-redis](https://github.com/yiisoft/db-redis) Redis support

  * [yiisoft/db-mongodb](https://github.com/yiisoft/db-mongodb) MongoDB support

  * [yiisoft/db-elasticsearch](https://github.com/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](https://github.com/yiisoft/yii-debug) The debug panel

* [yiisoft/yii-gii](https://github.com/yiisoft/yii-gii) The code generator extension

* [yiisoft/yii-dev](https://github.com/yiisoft/yii-dev) Tools for framework contributors

##### View rendering engines

* [yiisoft/yii-twig](https://github.com/yiisoft/yii-twig) Twig Extension

##### Data rendering

* [yiisoft/yii-dataview](https://github.com/yiisoft/yii-dataview) : ListView, GridView, DetailView

##### JS & CSS Frameworks integration

* [yiisoft/yii-bootstrap3](https://github.com/yiisoft/yii-bootstrap3) : Bootstrap 3 assets & widgets

* [yiisoft/yii-bootstrap4](https://github.com/yiisoft/yii-bootstrap4) : Bootstrap 4 assets & widgets

* [yiisoft/yii-jquery](https://github.com/yiisoft/yii-jquery) jQuery, ActiveForm

##### Widgets

* [yiisoft/yii-captcha](https://github.com/yiisoft/yii-captcha) The CAPTCHA Extension

* [yiisoft/yii-masked-input](https://github.com/yiisoft/yii-masked-input) : The masked input widget (depends on jquery)

##### Misc

* [yiisoft/yii-swiftmailer](https://github.com/yiisoft/yii-swiftmailer) Swift Mailer Extension

* [yiisoft/yii-http-client](https://github.com/yiisoft/yii-http-client) HTTP client extension

* [yiisoft/yii-auth-client](https://github.com/yiisoft/yii-auth-client) External authentication extension

### Yii project template and application bases

* [yiisoft/yii-project-template](https://github.com/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](https://github.com/yiisoft/yii-base-cli)

*  [yiisoft/yii-base-web](https://github.com/yiisoft/yii-base-web)

*  [yiisoft/yii-base-api](https://github.com/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:

<img src="https://user-images.githubusercontent.com/304450/50153967-44a6af00-02c8-11e9-9914-ceb463065cdf.png" />

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.## Introduction

*This document is intended for an audience already familiar with [Yii2](https://www.yiiframework.com/doc/guide/2.0/en).*

*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](https://www.yiiframework.com/news/177/yii-adopts-semver-since-version-3-0-0).

This rewrite addresses a lot of issues Yii 2 suffered from:

- The framework being too coupled with jQuery, bower, bootstrap.

- Big inheritance tree.

- Non-standard objects behavior (magic properties).

- Being out of the general PHP infrastructure with tons of extensions wrapping regular PHP code.

- Being monolitic framework where you can not fine-tune by picking exactly what you need.

- etc.

### **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](https://www.php-fig.org/) 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

* and more

### **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 [yiisoft/config](https://github.com/yiisoft/config), which takes care of scanning & merging all the configurations when you run `composer dump-autoload` (also know as `composer du`).

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

### **Dependency injection**

Dependency injection is a core concept of Yii3. The team intentionally dropped service locator and used injection via type-hinting. You can [learn more in the guide](https://github.com/yiisoft/docs/blob/master/guide/en/concept/di-container.md).

## Yii 3 composer packages

Here are the new packages introduced in Yii 3, which can be found in this [official list](https://github.com/topics/yii3).

## Demo

There are two demo apps available:

- [Demo](https://github.com/yiisoft/demo) - classical web application.

- [Demo API](https://github.com/yiisoft/demo-api) - REST API.

## Guide and other docs

All the current documentation could be found in [yiisoft/docs](https://github.com/yiisoft/docs) repository.