Skip to content

Y
yii2
Commit b80c0c3b by Qiang Xue
Options

guide WIP [skip ci]

parent 58967f13
Showing with 98 additions and 131 deletions
docs/guide/concept-aliases.md
......@@ -7,8 +7,7 @@ For example, the alias `@yii` represents the installation path of the Yii framew
the base URL for the currently running Web application.
<a name="defining-aliases"></a>
Defining Aliases
Defining Aliases <a name="defining-aliases"></a>
----------------
You can call [[Yii::setAlias()]] to define an alias for a given file path or URL. For example,
......@@ -50,8 +49,7 @@ return [
```
<a name="resolving-aliases"></a>
Resolving Aliases
Resolving Aliases <a name="resolving-aliases"></a>
-----------------
You can call [[Yii::getAlias()]] to resolve a root alias into the file path or URL it is representing.
......@@ -83,8 +81,7 @@ Yii::getAlias('@foo/bar/file.php'); // displays: /path2/bar/file.php
If `@foo/bar` is not defined as a root alias, the last statement would display `/path/to/foo/bar/file.php`.
<a name="using-aliases"></a>
Using Aliases
Using Aliases <a name="using-aliases"></a>
-------------
Aliases are recognized in many places in Yii without the need of calling [[Yii::getAlias()]] to convert
......@@ -103,8 +100,7 @@ $cache = new FileCache([
Please pay attention to the API documentation to see if a property or method parameter supports aliases.
<a name="predefined-aliases"></a>
Predefined Aliases
Predefined Aliases <a name="predefined-aliases"></a>
------------------
Yii predefines a set of aliases to ease the need of referencing commonly used file paths and URLs.
......@@ -122,8 +118,7 @@ while the rest of the aliases are defined in the application constructor when ap
[configuration](concept-configurations.md).
<a name="extension-aliases"></a>
Extension Aliases
Extension Aliases <a name="extension-aliases"></a>
-----------------
An alias is automatically defined for each [extension](structure-extensions.md) that is installed via Composer.
......
docs/guide/concept-autoloading.md
......@@ -10,8 +10,7 @@ The autoloader is installed when you include the `Yii.php` file.
mind that the content we are describing here applies to autoloading of interfaces and traits as well.
<a name="using-yii-autoloader"></a>
Using the Yii Autoloader
Using the Yii Autoloader <a name="using-yii-autoloader"></a>
------------------------
To make use of the Yii class autoloader, you should follow two simple rules when creating and naming your classes:
......@@ -39,8 +38,7 @@ put the front-end classes under the namespace `frontend` while the back-end clas
allow these classes to be autoloaded by the Yii autoloader.
<a name="class-map"></a>
Class Map
Class Map <a name="class-map"></a>
---------
The Yii class autoloader supports the *class map* feature which maps class names to the corresponding class file paths.
......@@ -58,8 +56,7 @@ Yii::$classMap['foo\bar\MyClass'] = 'path/to/MyClass.php';
[bootstrapping](runtime-bootstrapping.md) process so that the map is ready before your classes are used.
<a name="using-other-autoloaders"></a>
Using Other Autoloaders
Using Other Autoloaders <a name="using-other-autoloaders"></a>
-----------------------
Because Yii embraces Composer as a package dependency manager, it is recommended that you also install
......@@ -85,8 +82,7 @@ to be autoloadable.
and include it in your [entry script](structure-entry-scripts.md).
<a name="autoloading-extension-classes"></a>
Autoloading Extension Classes
Autoloading Extension Classes <a name="autoloading-extension-classes"></a>
-----------------------------
The Yii autoloader is capable of autoloading [extension](structure-extensions.md) classes. The sole requirement
......
docs/guide/concept-behaviors.md
......@@ -10,8 +10,7 @@ can respond to the [events](concept-events.md) triggered by the component so tha
code execution of the component.
<a name="using-behaviors"></a>
Using Behaviors
Using Behaviors <a name="using-behaviors"></a>
---------------
To use a behavior, you first need to attach it to a [[yii\base\Component|component]]. We will describe how to
......@@ -55,8 +54,7 @@ $behaviors = $component->getBehaviors();
```
<a name="attaching-behaviors"></a>
Attaching Behaviors
Attaching Behaviors <a name="attaching-behaviors"></a>
-------------------
You can attach a behavior to a [[yii\base\Component|component]] either statically or dynamically. The former
......@@ -132,8 +130,7 @@ You may also attach behaviors through [configurations](concept-configurations.md
refer to the [Configurations](concept-configurations.md#configuration-format) section.
<a name="detaching-behaviors"></a>
Detaching Behaviors
Detaching Behaviors <a name="detaching-behaviors"></a>
-------------------
To detach a behavior, you can call [[yii\base\Component::detachBehavior()]] with the name associated with the behavior:
......@@ -149,8 +146,7 @@ $component->detachBehaviors();
```
<a name="defining-behaviors"></a>
Defining Behaviors
Defining Behaviors <a name="defining-behaviors"></a>
------------------
To define a behavior, create a class by extending from [[yii\base\Behavior]] or its child class. For example,
......@@ -235,8 +231,7 @@ function ($event) {
```
<a name="using-timestamp-behavior"></a>
Using `TimestampBehavior`
Using `TimestampBehavior` <a name="using-timestamp-behavior"></a>
-------------------------
To wrap up, let's take a look at [[yii\behaviors\TimestampBehavior]] - a behavior that supports automatically
......@@ -294,8 +289,7 @@ $user->touch('login_time');
```
<a name="comparison-with-traits"></a>
Comparison with Traits
Comparison with Traits <a name="comparison-with-traits"></a>
----------------------
While behaviors are similar to [traits](http://www.php.net/traits) in that they both "inject" their
......@@ -322,8 +316,7 @@ Name conflict caused by different traits requires you to manually resolve it by
properties or methods.
<a name="pros-for-traits"></a>
### Pros for Traits
### Pros for Traits <a name="pros-for-traits"></a>
Traits are much more efficient than behaviors because behaviors are objects which take both time and memory.
......
docs/guide/concept-configurations.md
......@@ -35,8 +35,7 @@ Yii::configure($object, $config);
Note that in this case, the configuration should not contain the `class` element.
<a name="configuration-format"></a>
Configuration Format
Configuration Format <a name="configuration-format"></a>
--------------------
The format of a configuration can be formally described as follows,
......@@ -80,8 +79,7 @@ Below is an example showing a configuration with property initial values, event
```
<a name="using-configurations"></a>
Using Configurations
Using Configurations <a name="using-configurations"></a>
--------------------
Configurations are used in many places in Yii. At the beginning of this section, we have shown how to use
......@@ -89,8 +87,7 @@ create an object according to a configuration by using [[Yii::createObject()]].
describe application configurations and widget configurations - two major usages of configurations.
<a name="application-configurations"></a>
### Application Configurations
### Application Configurations <a name="application-configurations"></a>
Configuration for an [application](structure-applications.md) is probably one of the most complex configurations.
This is because the [[yii\web\Application|application]] class has a lot of configurable properties and events.
......@@ -141,8 +138,7 @@ For more details about configuring the `components` property of an application c
in the [Applications](structure-applications.md) section and the [Service Locator](concept-service-locator.md) section.
<a name="widget-configurations"></a>
### Widget Configurations
### Widget Configurations <a name="widget-configurations"></a>
When using [widgets](structure-widgets.md), you often need to use configurations to customize the widget properties.
Both of the [[yii\base\Widget::widget()]] and [[yii\base\Widget::beginWidget()]] methods can be used to create
......@@ -167,8 +163,7 @@ The `items` property is also configured with menu items to be displayed.
Note that because the class name is already given, the configuration array should NOT have the `class` key.
<a name="configuration-files"></a>
Configuration Files
Configuration Files <a name="configuration-files"></a>
-------------------
When a configuration is very complex, a common practice is to store it in one or multiple PHP files, known as
......@@ -222,8 +217,7 @@ $config = require('path/to/web.php');
```
<a name="default-configurations"></a>
Default Configurations
Default Configurations <a name="default-configurations"></a>
----------------------
The [[Yii::createObject()]] method is implemented based on a [dependency injection container](concept-di-container.md).
......@@ -244,8 +238,7 @@ Without using default configurations, you would have to configure `maxButtonCoun
link pagers.
<a name="environment-constants"></a>
Environment Constants
Environment Constants <a name="environment-constants"></a>
---------------------
Configurations often vary according to the environment in which an application runs. For example,
......
docs/guide/concept-di-container.md
......@@ -6,8 +6,7 @@ all their dependent objects. [Martin's article](http://martinfowler.com/articles
explained why DI container is useful. Here we will mainly explain the usage of the DI container provided by Yii.
<a name="dependency-injection"></a>
Dependency Injection
Dependency Injection <a name="dependency-injection"></a>
--------------------
Yii provides the DI container feature through the class [[yii\di\Container]]. It supports the following kinds of
......@@ -18,8 +17,7 @@ dependency injection:
* PHP callable injection.
<a name="constructor-injection"></a>
### Constructor Injection
### Constructor Injection <a name="constructor-injection"></a>
The DI container supports constructor injection with the help of type hints for constructor parameters.
The type hints tell the container which classes or interfaces are dependent when it is used to create a new object.
......@@ -41,8 +39,7 @@ $foo = new Foo($bar);
```
<a name="setter-and-property-injection"></a>
### Setter and Property Injection
### Setter and Property Injection <a name="setter-and-property-injection"></a>
Setter and property injection is supported through [configurations](concept-configurations.md).
When registering a dependency or when creating a new object, you can provide a configuration which
......@@ -76,8 +73,7 @@ $container->get('Foo', [], [
```
<a name="php-callable-injection"></a>
### PHP Callable Injection
### PHP Callable Injection <a name="php-callable-injection"></a>
In this case, the container will use a registered PHP callable to build new instances of a class.
The callable is responsible to resolve the dependencies and inject them appropriately to the newly
......@@ -92,8 +88,7 @@ $foo = $container->get('Foo');
```
<a name="registering-dependencies"></a>
Registering Dependencies
Registering Dependencies <a name="registering-dependencies"></a>
------------------------
You can use [[yii\di\Container::set()]] to register dependencies. The registration requires a dependency name
......@@ -162,8 +157,7 @@ $container->setSingleton('yii\db\Connection', [
```
<a name="resolving-dependencies"></a>
Resolving Dependencies
Resolving Dependencies <a name="resolving-dependencies"></a>
----------------------
Once you have registered dependencies, you can use the DI container to create new objects,
......@@ -252,9 +246,8 @@ $lister = new UserLister($finder);
```
<a name="practical-usages"></a>
Practical Usages
----------------
Practical Usage <a name="practical-usage"></a>
---------------
Yii creates a DI container when you include the `Yii.php` file in the [entry script](structure-entry-scripts.md)
of your application. The DI container is accessible via [[Yii::$container]]. When you call [[Yii::createObject()]],
......@@ -315,8 +308,7 @@ Now if you access the controller again, an instance of `app\components\BookingSe
created and injected as the 3rd parameter to the controller's constructor.
<a name="when-to-register-dependencies"></a>
When to Register Dependencies
When to Register Dependencies <a name="when-to-register-dependencies"></a>
-----------------------------
Because dependencies are needed when new objects are being created, their registration should be done
......@@ -328,8 +320,7 @@ as early as possible. The followings are the recommended practices:
in the bootstrap class of the extension.
<a name="summary"></a>
Summary
Summary <a name="summary"></a>
-------
Both dependency injection and [service locator](concept-service-locator.md) are popular design patterns
......
docs/guide/concept-events.md
......@@ -10,8 +10,7 @@ Yii introduces a base class called [[yii\base\Component]] to support events. If
events, it should extend from [[yii\base\Component]] or its child class.
<a name="triggering-events"></a>
Triggering Events
Triggering Events <a name="triggering-events"></a>
-----------------
Events are triggered by calling the [[yii\base\Component::trigger()]] method. The method requires an *event name*
......@@ -77,8 +76,7 @@ When the [[yii\base\Component::trigger()]] method is called, it will call handle
the named event.
<a name="event-handlers"></a>
Event Handlers
Event Handlers <a name="event-handlers"></a>
--------------
An event handler is a [PHP callback](http://www.php.net/manual/en/language.types.callable.php) that gets executed
......@@ -104,8 +102,7 @@ Through the `$event` parameter, an event handler may get the following informati
- [[yii\base\Event::data|custom data]]: the data that is provided when attaching the event handler (to be explained shortly).
<a name="attaching-event-handlers"></a>
Attaching Event Handlers
Attaching Event Handlers <a name="attaching-event-handlers"></a>
------------------------
You can attach a handler to an event by calling the [[yii\base\Component::on()]] method. For example,
......@@ -166,8 +163,7 @@ $foo->on(Foo::EVENT_HELLO, function ($event) {
```
<a name="detaching-event-handlers"></a>
Detaching Event Handlers
Detaching Event Handlers <a name="detaching-event-handlers"></a>
------------------------
To detach a handler from an event, call the [[yii\base\Component::off()]] method. For example,
......@@ -197,8 +193,7 @@ $foo->off(Foo::EVENT_HELLO);
```
<a name="class-level-event-handlers"></a>
Class-Level Event Handlers
Class-Level Event Handlers <a name="class-level-event-handlers"></a>
--------------------------
In the above subsections, we have described how to attach a handler to an event at *instance level*.
......@@ -256,8 +251,7 @@ Event::off(Foo::className(), Foo::EVENT_HELLO);
```
<a name="global-events"></a>
Global Events
Global Events <a name="global-events"></a>
-------------
The so-called *global event* is actually a trick based on the event mechanism described above.
......
docs/guide/start-databases.md
......@@ -17,8 +17,7 @@ Note that in order to finish this section, you should have basic knowledge and e
In particular, you should know how to create a database and how to execute SQL statements using a DB client tool.
<a name="preparing-database"></a>
Preparing a Database
Preparing a Database <a name="preparing-database"></a>
--------------------
To begin with, create a database named `yii2basic` from which you will fetch data in your application.
......@@ -50,8 +49,7 @@ To this end, you have a database named `yii2basic`, and within this database the
with ten rows of data.
<a name="configuring-db-connection"></a>
Configuring a DB Connection
Configuring a DB Connection <a name="configuring-db-connection"></a>
---------------------------
Make sure you have installed the [PDO](http://www.php.net/manual/en/book.pdo.php) PHP extension and
......@@ -84,8 +82,7 @@ The DB connection configured above can be accessed in the code via the expressio
For more information, please refer to the [Configurations](concept-configurations.md) section.
<a name="creating-active-record"></a>
Creating an Active Record
Creating an Active Record <a name="creating-active-record"></a>
-------------------------
To represent and fetch the data in the `country` table, create an [Active Record](db-active-record.md)
......@@ -130,8 +127,7 @@ You may find more detailed information in the [Active Record](db-active-record.m
use a lower-level data accessing method called [Data Access Objects](db-dao.md).
<a name="creating-action"></a>
Creating an Action
Creating an Action <a name="creating-action"></a>
------------------
To expose the country data to end users, you need to create a new action. Instead of doing this in the `site`
......@@ -185,8 +181,7 @@ At the end, the `index` action renders a view named `index` and passes the count
information to it.
<a name="creating-view"></a>
Creating a View
Creating a View <a name="creating-view"></a>
---------------
Under the `views` directory, first create a sub-directory named `country`. This will used to hold all
......@@ -216,8 +211,7 @@ The `LinkPager` widget displays a list of page buttons. Clicking on any of them
in the corresponding page.
<a name="how-it-works"></a>
How It Works
How It Works <a name="how-it-works"></a>
------------
To see how it works, use your browser to access the following URL:
......@@ -247,8 +241,7 @@ Behind the scene, [[yii\data\Pagination|Pagination]] is playing the magic.
for display.
<a name="summary"></a>
Summary
Summary <a name="summary"></a>
-------
In this section, you have learned how to work with a database. You have also learned how to fetch and display
......
docs/guide/start-forms.md
......@@ -15,8 +15,7 @@ Through this tutorial, you will learn
* How to build an HTML form in a [view](structure-views.md).
<a name="creating-model"></a>
Creating a Model
Creating a Model <a name="creating-model"></a>
----------------
To represent the data entered by a user, create an `EntryForm` model class as shown below and
......@@ -59,8 +58,7 @@ failure will turn on the [[yii\base\Model::hasErrors|hasErrors]] property, and t
[[yii\base\Model::getErrors|errors]] you may learn what validation errors the model has.
<a name="creating-action"></a>
Creating an Action
Creating an Action <a name="creating-action"></a>
------------------
Next, create an `entry` action in the `site` controller, like you did in the previous section.
......@@ -110,8 +108,7 @@ be rendered, which will show the HTML form together with the validation error me
In the above code, the `request` component is used to access the `$_POST` data.
<a name="creating-views"></a>
Creating Views
Creating Views <a name="creating-views"></a>
--------------
Finally, create two views named `entry-confirm` and `entry` that are rendered by the `entry` action,
......@@ -159,8 +156,7 @@ and the second the "email" data. After the input fields, the [[yii\helpers\Html:
is called to generate a submit button.
<a name="how-it-works"></a>
How It Works
How It Works <a name="how-it-works"></a>
------------
To see how it works, use your browser to access the following URL:
......@@ -178,8 +174,7 @@ After entering a valid name and email address and clicking the submit button, yo
displaying the data that you just entered.
<a name="magic-explained"></a>
### Magic Explained
### Magic Explained <a name="magic-explained"></a>
You may wonder how the HTML form works behind the scene, because it seems almost magical that it can
display a label for each input field and show error messages if you do not enter the data correctly
......@@ -205,8 +200,7 @@ the following code:
view code into reusable widgets to simplify view development in future.
<a name="summary"></a>
Summary
Summary <a name="summary"></a>
-------
In this section, you have touched every part in the MVC design pattern. You have learned how
......
docs/guide/start-gii.md
......@@ -13,7 +13,7 @@ Through this tutorial, you will learn
* How to customize the code generated by Gii.
Starting Gii
Starting Gii <a name="starting-gii"></a>
------------
[Gii](tool-gii.md) is provided by Yii in terms of a [module](structure-modules.md). You can enable Gii
......@@ -46,7 +46,7 @@ http://hostname/index.php?r=gii
```
Generating an Active Record Class
Generating an Active Record Class <a name="generating-ar"></a>
---------------------------------
To use Gii to generate an Active Record class, select the "Model Generator". You will see the following page:
......@@ -70,7 +70,7 @@ a confirmation page indicating the code has been successfully generated and your
is overwritten with the newly generated code.
Generating CRUD Code
Generating CRUD Code <a name="generating-crud"></a>
--------------------
To create CRUD code, select the "CRUD Generator". Fill out the form as follows:
......@@ -87,7 +87,7 @@ because you have already created this file in the previous section and the file
to have full CRUD support.
How It Works
How It Works <a name="how-it-works"></a>
------------
To see how it works, use your browser to access the following URL:
......@@ -114,7 +114,7 @@ or if you want to customize them.
the [Gii](tool-gii.md) section.
Summary
Summary <a name="summary"></a>
-------
In this section, you have learned how to use Gii to generate the code that implements a complete
......
docs/guide/start-hello.md
......@@ -15,8 +15,7 @@ Through this tutorial, you will learn
* How an application dispatches requests to [actions](structure-controllers.md).
<a name="creating-action"></a>
Creating an Action
Creating an Action <a name="creating-action"></a>
------------------
For the "Hello" task, you will create a `say` [action](structure-controllers.md) which reads
......@@ -66,8 +65,7 @@ so that it can be echoed there. The rendering result is returned by the action m
by the application and displayed to the end user.
<a name="creating-view"></a>
Creating a View
Creating a View <a name="creating-view"></a>
---------------
[Views](structure-views.md) are scripts that you write to compose response content.
......@@ -93,8 +91,7 @@ In fact, the `say` view is just a PHP script which is executed by the [[yii\web\
The content echoed by the view script will be forwarded by the application as the response to the end user.
<a name="how-it-works"></a>
How It Works
How It Works <a name="how-it-works"></a>
------------
After creating the action and the view, you may access the new page by the following URL:
......@@ -126,8 +123,7 @@ the `SiteController::actionSay()` method will be called to handle the request.
to the controller class name `PostCommentController`.
<a name="summary"></a>
Summary
Summary <a name="summary"></a>
-------
In this section, you have touched the controller part and the view part in the MVC design pattern.
......
docs/guide/start-installation.md
......@@ -6,8 +6,7 @@ The former is the preferred way as it allows you to install new [extensions](str
or update Yii by running a single command.
<a name="installing-via-composer"></a>
Installing via Composer
Installing via Composer <a name="installing-via-composer"></a>
-----------------------
If you do not already have Composer installed, you may get it by following the instructions at
......@@ -40,8 +39,7 @@ composer create-project --prefer-dist --stability=dev yiisoft/yii2-app-basic bas
Note that the development version of Yii should not be used for production as it may break your running code.
<a name="installing-from-archive-file"></a>
Installing from an Archive File
Installing from an Archive File <a name="installing-from-archive-file"></a>
-------------------------------
Installing Yii from an archive file involves two steps:
......@@ -50,8 +48,7 @@ Installing Yii from an archive file involves two steps:
2. Unpack the downloaded file to a Web accessible folder.
<a name="other-installation-options"></a>
Other Installation Options
Other Installation Options <a name="other-installation-options"></a>
--------------------------
The above installation instructions show how to install Yii in terms of a basic Web application that works out of box.
......@@ -65,8 +62,7 @@ There are other installation options available:
you may consider [Advanced Application Template](tutorial-advanced-app.md).
<a name="verifying-installation"></a>
Verifying Installation
Verifying Installation <a name="verifying-installation"></a>
----------------------
After installation, you can use your browser to access the installed Yii application with the following URL,
......@@ -94,8 +90,7 @@ the [PDO PHP Extension](http://www.php.net/manual/en/pdo.installation.php) and a
(such as `pdo_mysql` for MySQL databases), if your application needs a database.
<a name="configuring-web-servers"></a>
Configuring Web Servers
Configuring Web Servers <a name="configuring-web-servers"></a>
-----------------------
> Info: You may skip this sub-section for now if you are just testing driving Yii with no intention
......@@ -120,8 +115,7 @@ to modify its Web server setting, you may adjust the structure of your applicati
the [Shared Hosting Environment](tutorial-shared-hosting.md) section for more details.
<a name="recommended-apache-configuration"></a>
### Recommended Apache Configuration
### Recommended Apache Configuration <a name="recommended-apache-configuration"></a>
Use the following configuration in Apache's `httpd.conf` file or within a virtual host configuration. Note that you
should replace `path/to/basic/web` with the actual path of `basic/web`.
......@@ -144,8 +138,7 @@ DocumentRoot "path/to/basic/web"
```
<a name="recommended-nginx-configuration"></a>
### Recommended Nginx Configuration
### Recommended Nginx Configuration <a name="recommended-nginx-configuration"></a>
You should have installed PHP as an [FPM SAPI](http://php.net/install.fpm) for [Nginx](http://wiki.nginx.org/).
Use the following Nginx configuration and replace `path/to/basic/web` with the actual path of `basic/web`.
......
docs/guide/start-looking-head.md
Looking Ahead
=============
> Note: This section is under development.
To this end, you have created a complete Yii application, and you have learned how to implement some commonly
needed features, such as getting data from users using an HTML form, fetching data from database and
displaying it in a paginated fashion. You have also learned how to use [Gii](tool-gii.md) to generate
code automatically, which turns programming into a task as simple as just filling out some forms. In this
section, we will summarize the resources about Yii that help you be more productive when using Yii.
* Documentation
- The Definitive Guide:
As the name indicates, the guide precisely defines how Yii should work and gives you a general guidance
about using Yii. It is the single most important Yii tutorial that you should read through
before writing any Yii code.
- The Class Reference:
This specifies the usage of every class provided by Yii. It should be mainly used when you are writing
code and want to understand the usage of a particular class, method, property.
- The Wiki Articles:
The wiki articles are written by Yii users based on their own experiences. Most of them are written
like cookbook recipes which show how to solve particular problems using Yii. While the quality of these
articles may be as good as the Definitive Guide, they are useful in that they cover broader topics
and can often provide to you ready-to-use solutions.
- Books
* [Extensions](http://www.yiiframework.com/extensions/):
Yii boasts a library of thousands of user-contributed extensions that can be easily plugged into your applications
and make your application development even faster and easier.
* Community
- [Forum](http://www.yiiframework.com/forum/)
- [GitHub](https://github.com/yiisoft/yii2)
- [Facebook](https://www.facebook.com/groups/yiitalk/)
- [Twitter](https://twitter.com/yiiframework)
- [LinkedIn](https://www.linkedin.com/groups/yii-framework-1483367)
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment