Skip to content

Instantly share code, notes, and snippets.

@machour

machour/yii3.md

Last active April 5, 2019 03:20
Show Gist options
  • Star 1 You must be signed in to star a gist
  • Fork 1 You must be signed in to fork a gist
  • Save machour/84d52e8db3b63f0f53b63b12a294f1cb to your computer and use it in GitHub Desktop.
Save machour/84d52e8db3b63f0f53b63b12a294f1cb to your computer and use it in GitHub Desktop.
Download ZIP
This is a draft of my draft at https://www.yiiframework.com/wiki/2547/draft-understanding-yii-3. Stay drafty!
Raw
yii3.md

Understanding Yii 3

Introduction

This document is intended for an audience already familiar with Yii2

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.

In order to achieve this, the framework source code have been split into several packages, and at its core level, Yii no longer makes assumptions about your web stack.

This re-organisation is also a great new for maintainance, as these packages will be maintained and released separatly, thus allowing more frequent updates.

It's also important to note that the custom PHP class autoloader have also been removed in favor of Composer's PSR-4 implementation. We will see the implications of this change later.

Other new PSR changes:

  • Logging is now compliant with PSR-3
  • Caching is now compliant with PSR-16

You can check the complete CHANGELOG for an exhaustive list of modifications.

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

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:

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.

Drivers for yiisoft/db

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

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
View rendering engines
Data rendering
JS & CSS Frameworks integration
Widgets
Misc

Yii project template and application bases

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:

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:

screen shot 2018-12-17 at 11 56 48 pm

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.

Modifying the text on the homepage

In order to modify the text on the home page, we are going to tell Yii to use our own controller, instead of the default provided one.

We are going to do the following:

  1. Create our own controller & views
  2. Configure Yii 3 so that it uses our files
  3. Tell composer about our namespace

Step 1

Create the src directory at your project root, with these contents:

  • src/controllers/SiteController.php
<?php

namespace myapp\controllers;

class SiteController extends \yii\app\controllers\SiteController
{
    public function actionIndex()
    {
        return $this->render('index');
    }
}
  • src/views/layouts/main.php
<html>
    <body>
        <?=$content?>
    </body>
</html>
  • src/views/site/index.php
<h1>Hello Yii 3!</h1>

Step 2

Next, let's configure Yii 3 so that it picks up our files:

  • in config/ at your project root, create the web.php file with this content:
<?php
return [
    'app' => [
        'controllerNamespace' => myapp\controllers::class,
    ],
];
  • modify the config/common.php file to change the application base path:
<?php

return [
    'app' => [
        'basePath' => dirname(__DIR__) . '/src',
    ],
];

Step 3

Last but far from least, and since Yii custom autoloading have been removed, we need to manually tell composer about our namespace.

Edit composer.json and add the following section at the end:

  "autoload": {
    "psr-4": {
      "myapp\\": "src"
    }
  }

Find the section extra.config-plugin in composer.json, and append "web": "config/web.php" to the list of configuration files being loaded, so that the correct controllerNamespace is set.

That's it. Now we need to run composer dump-autoload so that it re-generates the configuration and autoloading, before restarting the server:

composer install
./vendor/bin/yii serve

You should now see the Hello Yii 3 greeting when loading http://localhost:8080/, congratulations!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment