The definitive Guide to Yii 2.0

599 Pages·2017·2.77 MB·English

The Definitive Guide
to
Yii 2.0
http://www.yiiframework.com/doc/guide
Qiang Xue,
Alexander Makarov,
Carsten Brandt,
Klimov Paul,
and
many contributors from the Yii community
This tutorial is released under the Terms of Yii Documentation.
Copyright 2014 Yii Software LLC. All Rights Reserved.
Contents
1 Introduction 1
1.1 What is Yii . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.2 Upgrading from Version 1.1 . . . . . . . . . . . . . . . . . . . 2
2 Getting Started 13
2.1 What do you need to know . . . . . . . . . . . . . . . . . . . 13
2.2 Installing Yii . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
2.3 Running Applications . . . . . . . . . . . . . . . . . . . . . . 21
2.4 Saying Hello . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
2.5 Working with Forms . . . . . . . . . . . . . . . . . . . . . . . 28
2.6 Working with Databases . . . . . . . . . . . . . . . . . . . . . 34
2.7 Generating Code with Gii . . . . . . . . . . . . . . . . . . . . 40
2.8 Looking Ahead . . . . . . . . . . . . . . . . . . . . . . . . . . 46
3 Application Structure 49
3.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
3.2 Entry Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
3.3 Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
3.4 Application Components . . . . . . . . . . . . . . . . . . . . . 64
3.5 Controllers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
3.6 Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
3.7 Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
3.8 Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
3.9 Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
3.10 Widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
3.11 Assets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
3.12 Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
4 Handling Requests 151
4.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
4.2 Bootstrapping . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
4.3 Routing and URL Creation . . . . . . . . . . . . . . . . . . . 153
4.4 Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
iii
iv CONTENTS
4.5 Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
4.6 Sessions and Cookies . . . . . . . . . . . . . . . . . . . . . . . 177
4.7 Handling Errors . . . . . . . . . . . . . . . . . . . . . . . . . . 185
4.8 Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
5 Key Concepts 199
5.1 Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
5.2 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
5.3 Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
5.4 Behaviors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
5.5 Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . 218
5.6 Aliases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
5.7 Class Autoloading . . . . . . . . . . . . . . . . . . . . . . . . 226
5.8 Service Locator . . . . . . . . . . . . . . . . . . . . . . . . . . 228
5.9 Dependency Injection Container . . . . . . . . . . . . . . . . . 231
6 Working with Databases 243
6.1 Database Access Objects . . . . . . . . . . . . . . . . . . . . . 243
6.2 Query Builder . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
6.3 Active Record . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
6.4 Database Migration . . . . . . . . . . . . . . . . . . . . . . . . 309
7 Getting Data from Users 335
7.1 Creating Forms . . . . . . . . . . . . . . . . . . . . . . . . . . 335
7.2 Validating Input . . . . . . . . . . . . . . . . . . . . . . . . . 340
7.3 Uploading Files . . . . . . . . . . . . . . . . . . . . . . . . . . 357
7.4 Collecting tabular input . . . . . . . . . . . . . . . . . . . . . 361
7.5 Getting Data for Multiple Models . . . . . . . . . . . . . . . . 364
7.6 Extending ActiveForm on the Client Side . . . . . . . . . . . 365
8 Displaying Data 371
8.1 Data Formatting . . . . . . . . . . . . . . . . . . . . . . . . . 371
8.2 Pagination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
8.3 Sorting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
8.4 Data Providers . . . . . . . . . . . . . . . . . . . . . . . . . . 380
8.5 Data widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
8.6 Working with Client Scripts . . . . . . . . . . . . . . . . . . . 401
8.7 Theming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
9 Security 409
9.1 Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
9.2 Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . 409
9.3 Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
9.4 Working with Passwords . . . . . . . . . . . . . . . . . . . . . 431
CONTENTS v
9.5 Cryptography . . . . . . . . . . . . . . . . . . . . . . . . . . . 432
9.6 Security best practices . . . . . . . . . . . . . . . . . . . . . . 435
10 Caching 443
10.1 Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
10.2 Data Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
10.3 Fragment Caching . . . . . . . . . . . . . . . . . . . . . . . . 452
10.4 Page Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . 456
10.5 HTTP Caching . . . . . . . . . . . . . . . . . . . . . . . . . . 457
11 RESTful Web Services 461
11.1 Quick Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461
11.2 Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465
11.3 Controllers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470
11.4 Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474
11.5 Response Formatting . . . . . . . . . . . . . . . . . . . . . . . 476
11.6 Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . 480
11.7 Rate Limiting . . . . . . . . . . . . . . . . . . . . . . . . . . . 483
11.8 Versioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484
11.9 Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . 486
12 Development Tools 489
13 Testing 493
13.1 Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493
13.2 Testing environment setup . . . . . . . . . . . . . . . . . . . . 494
13.3 Unit Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495
13.4 Functional Tests . . . . . . . . . . . . . . . . . . . . . . . . . 496
13.5 Acceptance Tests . . . . . . . . . . . . . . . . . . . . . . . . . 496
13.6 Fixtures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497
14 Special Topics 505
14.1 Creating your own Application structure . . . . . . . . . . . . 507
14.2 Console applications . . . . . . . . . . . . . . . . . . . . . . . 508
14.3 Core Validators . . . . . . . . . . . . . . . . . . . . . . . . . . 515
14.4 Yii and Docker . . . . . . . . . . . . . . . . . . . . . . . . . . 530
14.5 Internationalization . . . . . . . . . . . . . . . . . . . . . . . . 532
14.6 Mailing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547
14.7 Performance Tuning . . . . . . . . . . . . . . . . . . . . . . . 551
14.8 Shared Hosting Environment . . . . . . . . . . . . . . . . . . 556
14.9 Using template engines . . . . . . . . . . . . . . . . . . . . . . 558
14.10Working with Third-Party Code . . . . . . . . . . . . . . . . . 559
14.11Using Yii as a Micro-framework . . . . . . . . . . . . . . . . . 562
15 Widgets 569
vi CONTENTS
16 Helpers 573
16.1 Helpers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573
16.2 ArrayHelper . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574
16.3 Html helper . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583
16.4 Url Helper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590
Chapter 1
Introduction
1.1 What is Yii
Yii is a high performance, component-based PHP framework for rapidly
developing modern Web applications. The name Yii (pronounced Yee or [ji
:]) means “simple and evolutionary” in Chinese. It can also be thought of
as an acronym for Yes It Is!
1.1.1 What is Yii Best for?
Yii is a generic Web programming framework, meaning that it can be used
for developing all kinds of Web applications using PHP. Because of its
component-based architecture and sophisticated caching support, it is es-
pecially suitable for developing large-scale applications such as portals, for-
ums, content management systems (CMS), e-commerce projects, RESTful
Web services, and so on.
1.1.2 How does Yii Compare with Other Frameworks?
If you’re already familiar with another framework, you may appreciate know-
ing how Yii compares:
• Like most PHP frameworks, Yii implements the MVC (Model-View-
Controller) architectural pattern and promotes code organization based
on that pattern.
• Yii takes the philosophy that code should be written in a simple yet
elegant way. Yii will never try to over-design things mainly for the
purpose of strictly following some design pattern.
• Yii is a full-stack framework providing many proven and ready-to-
use features: query builders and ActiveRecord for both relational and
NoSQL databases; RESTful API development support; multi-tier cach-
ing support; and more.
1
2 CHAPTER 1. INTRODUCTION
• Yii is extremely extensible. You can customize or replace nearly every
piece of the core’s code. You can also take advantage of Yii’s solid
extension architecture to use or develop redistributable extensions.
• High performance is always a primary goal of Yii.
1
Yii is not a one-man show, it is backed up by a strong core developer team ,
as well as a large community of professionals constantly contributing to Yii’s
development. The Yii developer team keeps a close eye on the latest Web
development trends and on the best practices and features found in other
frameworks and projects. The most relevant best practices and features
found elsewhere are regularly incorporated into the core framework and ex-
posed via simple and elegant interfaces.
1.1.3 Yii Versions
Yii currently has two major versions available: 1.1 and 2.0. Version 1.1 is
the old generation and is now in maintenance mode. Version 2.0 is a com-
plete rewrite of Yii, adopting the latest technologies and protocols, including
Composer, PSR, namespaces, traits, and so forth. Version 2.0 represents the
current generation of the framework and will receive the main development
efforts over the next few years. This guide is mainly about version 2.0.
1.1.4 Requirements and Prerequisites
Yii 2.0 requires PHP 5.4.0 or above and runs best with the latest version of
PHP 7. You can find more detailed requirements for individual features by
running the requirement checker included in every Yii release.
Using Yii requires basic knowledge of object-oriented programming (OOP),
as Yii is a pure OOP-based framework. Yii 2.0 also makes use of the latest
2 3
features of PHP, such as namespaces and traits . Understanding these con-
cepts will help you more easily pick up Yii 2.0.
1.2 Upgrading from Version 1.1
There are many differences between versions 1.1 and 2.0 of Yii as the frame-
work was completely rewritten for 2.0. As a result, upgrading from version
1.1 is not as trivial as upgrading between minor versions. In this guide you’ll
find the major differences between the two versions.
If you have not used Yii 1.1 before, you can safely skip this section and
turn directly to “Getting started“.
Please note that Yii 2.0 introduces more new features than are covered
in this summary. It is highly recommended that you read through the whole
1
http://www.yiiframework.com/team/
2
http://www.php.net/manual/en/language.namespaces.php
3
http://www.php.net/manual/en/language.oop5.traits.php
1.2. UPGRADING FROM VERSION 1.1 3
definitive guide to learn about them all. Chances are that some features you
previously had to develop for yourself are now part of the core code.
1.2.1 Installation
4
Yii 2.0 fully embraces Composer , the de facto PHP package manager. In-
stallation of the core framework, as well as extensions, are handled through
Composer. Please refer to the Installing Yii section to learn how to install
Yii 2.0. If you want to create new extensions, or turn your existing 1.1 exten-
sions into 2.0-compatible extensions, please refer to the Creating Extensions
section of the guide.
1.2.2 PHP Requirements
Yii 2.0 requires PHP 5.4 or above, which is a huge improvement over PHP
version 5.2 that is required by Yii 1.1. As a result, there are many differences
on the language level that you should pay attention to. Below is a summary
of the major changes regarding PHP:
5
• Namespaces .
6
• Anonymous functions .
• Short array syntax [...elements...] is used instead of array(...elements
...).
• Short echo tags <?= are used in view files. This is safe to use starting
from PHP 5.4.
7
• SPL classes and interfaces .
8
• Late Static Bindings .
9
• Date and Time .
10
• Traits .
11
• intl . Yii 2.0 makes use of the intl PHP extension to support inter-
nationalization features.
1.2.3 Namespace
The most obvious change in Yii 2.0 is the use of namespaces. Almost every
core class is namespaced, e.g., yii\web\Request. The “C” prefix is no longer
used in class names. The naming scheme now follows the directory structure.
For example, yii\web\Request indicates that the corresponding class file is web
/Request.php under the Yii framework folder.
4
https://getcomposer.org/
5
http://php.net/manual/en/language.namespaces.php
6
http://php.net/manual/en/functions.anonymous.php
7
http://php.net/manual/en/book.spl.php
8
http://php.net/manual/en/language.oop5.late-static-bindings.php
9
http://php.net/manual/en/book.datetime.php
10
http://php.net/manual/en/language.oop5.traits.php
11
http://php.net/manual/en/book.intl.php
4 CHAPTER 1. INTRODUCTION
(You can use any core class without explicitly including that class file,
thanks to the Yii class loader.)
1.2.4 Component and Object
Yii 2.0 breaks the CComponent class in 1.1 into two classes: yii\base\BaseObject
and yii\base\Component. The BaseObject class is a lightweight base class
that allows defining object properties via getters and setters. The Component
class extends from BaseObject and supports events and behaviors.
If your class does not need the event or behavior feature, you should
consider using BaseObject as the base class. This is usually the case for
classes that represent basic data structures.
1.2.5 Object Configuration
The BaseObject class introduces a uniform way of configuring objects. Any
descendant class of BaseObject should declare its constructor (if needed) in
the following way so that it can be properly configured:
class MyClass extends \yii\base\BaseObject
{
public function __construct($param1, $param2, $config = [])
{
// ... initialization before configuration is applied
parent::__construct($config);
}
public function init()
{
parent::init();
// ... initialization after configuration is applied
}
}
In the above, the last parameter of the constructor must take a configuration
array that contains name-value pairs for initializing the properties at the end
of the constructor. You can override the init() method to do initialization
work that should be done after the configuration has been applied.
By following this convention, you will be able to create and configure
new objects using a configuration array:
$object = Yii::createObject([
’class’ => ’MyClass’,
’property1’ => ’abc’,
’property2’ => ’cde’,
], [$param1, $param2]);
More details about configurations can be found in the Configurations section.