Skip to content

Y
yii2
Commit 37dde677 by Qiang Xue
Options

guide WIP [skip ci]

parent c933d0cb
Showing with 188 additions and 90 deletions
docs/guide/extend-creating-extensions.md
......@@ -3,7 +3,7 @@ Extending Yii
> Note: This section is under development.
The Yii framework was designed to be easily extendable. Additional features can be added to your project and then reused, either by yourself on other projects or by sharing your work as a formal Yii extension.
The Yii framework was designed to be easily extensible. Additional features can be added to your project and then reused, either by yourself on other projects or by sharing your work as a formal Yii extension.
Code style
----------
......
docs/guide/extend-customizing-core.md
Helper Classes
==============
> Note: This section is under development.
Yii provides many classes that help simplify common coding tasks, such as string or array manipulations,
HTML code generation, and so forth. These helper classes are organized under the `yii\helpers` namespace and
are all static classes (meaning they contain only static properties and methods and should not be instantiated).
You use a helper class by directly calling one of its static methods:
```
use yii\helpers\ArrayHelper;
$c = ArrayHelper::merge($a, $b);
```
Extending Helper Classes
------------------------
To make helper classes easier to extend, Yii breaks each helper class into two classes: a base class (e.g. `BaseArrayHelper`)
and a concrete class (e.g. `ArrayHelper`). When you use a helper, you should only use the concrete version, never use the base class.
If you want to customize a helper, perform the following steps (using `ArrayHelper` as an example):
1. Name your class the same as the concrete class provided by Yii, including the namespace: `yii\helpers\ArrayHelper`
2. Extend your class from the base class: `class ArrayHelper extends \yii\helpers\BaseArrayHelper`.
3. In your class, override any method or property as needed, or add new methods or properties.
4. Tell your application to use your version of the helper class by including the following line of code in the bootstrap script:
```php
Yii::$classMap['yii\helpers\ArrayHelper'] = 'path/to/ArrayHelper.php';
```
Step 4 above will instruct the Yii class autoloader to load your version of the helper class instead of the one included in the Yii distribution.
> Tip: You can use `Yii::$classMap` to replace ANY core Yii class with your own customized version, not just helper classes.
docs/guide/extend-using-composer.md
......@@ -22,6 +22,20 @@ curl -s http://getcomposer.org/installer | php
We strongly recommend a global composer installation.
Installing Composer Class Autoloader
------------------------------------
Make sure the [entry script](concept-entry-scripts.md) of your application contains the following lines of code:
```php
// install Composer's class autoloader
require(__DIR__ . '/../vendor/autoload.php');
// include Yii class file
require(__DIR__ . '/../vendor/yiisoft/yii2/Yii.php');
```
Working with composer
---------------------
......@@ -52,7 +66,7 @@ composer.phar update
As an example, packages on `dev-master` will constantly get new updates when you run `update`, while running `install` won't, unless you've pulled an update of the `composer.lock` file.
There are several paramaters available to the above commands. Very commonly used ones are `--no-dev`, which would skip packages in the `require-dev` section and `--prefer-dist`, which downloads archives if available, instead of checking out repositories to your `vendor` folder.
There are several parameters available to the above commands. Very commonly used ones are `--no-dev`, which would skip packages in the `require-dev` section and `--prefer-dist`, which downloads archives if available, instead of checking out repositories to your `vendor` folder.
> Composer commands must be executed within your Yii project's directory, where the `composer.json` file can be found.
Depending upon your operating system and setup, you may need to provide paths to the PHP executable and
......@@ -100,7 +114,7 @@ afterwards.
> Depending on the package additional configuration may be required (eg. you have to register a module in the config), but autoloading of the classes should be handled by composer.
Using a specifc version of a package
Using a specific version of a package
------------------------------------
Yii always comes with the latest version of a required library that it is compatible with, but allows you to use an older version if you need to.
......
docs/guide/helper-overview.md
......@@ -3,14 +3,26 @@ Helpers
> Note: This section is under development.
Helper classes typically contain static methods only and are used as follows:
Yii provides many classes that help simplify common coding tasks, such as string or array manipulations,
HTML code generation, and so on. These helper classes are organized under the `yii\helpers` namespace and
are all static classes (meaning they contain only static properties and methods and should not be instantiated).
You use a helper class by directly calling one of its static methods, like the following:
```php
use \yii\helpers\Html;
use yii\helpers\Html;
echo Html::encode('Test > test');
```
There are several classes provided by framework:
> Note: To support [extending helper classes](#extending-helper-classes), Yii breaks each core helper class
into two classes: a base class (e.g. `BaseArrayHelper`) and a concrete class (e.g. `ArrayHelper`).
When you use a helper, you should only use the concrete version and never use the base class.
## Core Helper Classes
The following core helper classes are provided in the Yii releases:
- ArrayHelper
- Console
......@@ -25,3 +37,39 @@ There are several classes provided by framework:
- StringHelper
- Url
- VarDumper
## Extending Helper Classes
To custom a core helper class (e.g. `yii\helpers\ArrayHelper`), you should extend from its corresponding base class
(e.g. `yii\helpers\BaseArrayHelper`) and name your class the same as the corresponding concrete class
(e.g. `yii\helpers\ArrayHelper`), including its namespace.
The following example shows how to customize the [[yii\helpers\ArrayHelper::merge()|merge()]] method of the
[[yii\helpers\ArrayHelper]] class:
```php
namespace yii\helpers;
use yii\helpers\BaseArrayHelper;
class ArrayHelper extends BaseArrayHelper
{
public static function merge($a, $b)
{
// your custom implementation
}
}
```
Save your class in a file named `ArrayHelper.php`. The file can be in any directory, such as `@app/components`.
Next, in your application's [entry script](structure-entry-scripts.md), add the following line of code
after including the `yii.php` file:
```php
Yii::$classMap['yii\helpers\ArrayHelper'] = 'path/to/ArrayHelper.php';
```
The above line instructs the [Yii class autoloader](concept-autoloading.md) to load your version of the helper
class, instead of the one included in the Yii releases.
docs/guide/structure-extensions.md
......@@ -3,33 +3,36 @@ Extensions
> Note: This section is under development.
Extensions are redistributable software packages that extend Yii by providing extra features. For example,
the [yii2-debug](tool-debugger.md) extension adds a handy debug toolbar to every page in your application
to help you more easily grasp how the pages are generated. You can install and use extensions in your
applications to accelerate your development process. You can also package your code in terms of extensions
to share with other people your great work.
Extensions are redistributable software packages specifically designed to be used in Yii applications and provide
ready-to-use features. For example, the [yiisoft/yii2-debug](tool-debugger.md) extension adds a handy debug toolbar
at the bottom of every page in your application to help you more easily grasp how the pages are generated. You can
use extensions to accelerate your development process. You can also package your code as extensions to share with
other people your great work.
> Info: We use the term "extension" to refer to Yii-specific software packages. For general purpose software packages
that can be used without Yii, we will refer to them using the term "package".
## Getting Extensions
The easiest way of getting extensions is using [Composer](https://getcomposer.org/). The name "extension"
is also known as "package" in Composer's terminology. To do so, you will need to
## Using Extensions
To use an extension, you need to install it first. Most extensions are distributed as [Composer](https://getcomposer.org/)
packages, and you can take the following two simple steps to install such an extension:
1. modify the `composer.json` file of your application and specify which extensions (Composer packages) you want to install.
2. run `php composer.phar install` to install the specified extensions.
1. install [Composer](https://getcomposer.org/), which you probably have already done when
[installing Yii](start-installation.md).
2. [specify which repositories](https://getcomposer.org/doc/05-repositories.md#repository) you would like
to get extensions from. In most cases you can skip this if you only want to install open source extensions
hosted on [Packagist](https://packagist.org/) - the default and biggest Composer repository.
3. modify the `composer.json` file of your application and specify which extensions you want to use.
4. run `php composer.phar install` to install the specified extensions.
You may need to install [Composer](https://getcomposer.org/) if you do not have it. Composer is a dependency
manager. This means when installing a package, it will install all its dependent packages automatically.
You usually only need to do Step 1 and 2 once. You may need to do Step 3 and 4 multiple times depending on your
evolving requirements for extensions.
> Info: By default, Composer installs packages registered on [Packagist](https://packagist.org/) - the biggest repository
for open source Composer packages. You may also [create your own repository](https://getcomposer.org/doc/05-repositories.md#repository)
and configure Composer to use it. This is useful if you are developing closed open extensions and want to share
within your projects.
By default, extensions installed by Composer are stored under the `BasePath/vendor` directory, where `BasePath`
refers to the application's [base path](structure-applications.md#basePath).
Extensions installed by Composer are stored under the `BasePath/vendor` directory, where `BasePath` refers to the
application's [base path](structure-applications.md#basePath).
For example, to get the `yii2-imagine` extension maintained officially by Yii, modify your `composer.json` like the following:
For example, to install the `yiisoft/yii2-imagine` extension, modify your `composer.json` like the following:
```json
{
......@@ -43,33 +46,15 @@ For example, to get the `yii2-imagine` extension maintained officially by Yii, m
}
```
The installed extension will be located in the `vendor/yiisoft/yii2-imagine` directory.
> Info: All extensions officially maintained by Yii are named as `yiisoft/yii2-xyz`, where `xyz` varies for different
extensions.
## Using Extensions
In order for your applications to use extensions, you will need to install Composer's class autoloader. This is
necessary such that PHP classes in extensions can be properly autoloaded when you reference them in the application code.
To do so, use the following lines in the [entry script](concept-entry-scripts.md) of your application:
```php
// install Composer's class autoloader
require(__DIR__ . '/../vendor/autoload.php');
// include Yii class file
require(__DIR__ . '/../vendor/yiisoft/yii2/Yii.php');
```
After the installation, you should see the directory `yiisoft/yii2-imagine` under `BasePath/vendor`. You should
also see another directory `imagine/imagine` which contains the installed dependent package.
> Info: If you are using the [basic application template](start-installation.md) or
[advanced application template](tutorial-advanced-app.md), you do not need to do anything because the application templates
already contain the above code.
> Info: The `yiisoft/yii2-imagine` is a core extension developed and maintained by the Yii developer team. All
core extensions are hosted on [Packagist](https://packagist.org/) and named like `yiisoft/yii2-xyz`, where `xyz`
varies for different extensions.
Now you can enjoy using the installed extensions. For example, to use the `yii2-imagine` extension shown in the last
subsection, you can write code like the following in your application, where `Image` is the class provided by
the extension:
Now you can use the installed extensions like they are part of your application. The following example shows
how you can use the `yii\imagine\Image` class provided by the `yiisoft/yii2-imagine` extension:
```php
use Yii;
......@@ -80,8 +65,98 @@ Image::thumbnail('@webroot/img/test-image.jpg', 120, 120)
->save(Yii::getAlias('@runtime/thumb-test-image.jpg'), ['quality' => 50]);
```
> Info: Extension classes are autoloaded using the [Yii class autoloader](concept-autoloading.md). Yii automatically
creates [aliases](concept-aliases.md#extension-aliases) for the root namespaces declared by the extensions.
Also make sure in the [application configuration](structure-applications.md#application-configurations), you have
configured `extension
## Creating Extensions
You may consider creating an extension when you feel the need to redistribute some of your great code so that
they can be easily reused by other people or in your other projects.
An extension can contain any code you like, such as a helper class, a widget, a module, etc.
It is recommended that you create an extension in terms of a Composer package so that it can be more easily
used elsewhere, liked described in the last subsection. Below are the steps you may follow to create an extension.
1. Put all the files you plan to include in the extension in a single directory. The directory should contain
no other irrelevant files. For simplicity, let's call this directory the extension's *root directory*.
2. Create a `composer.json` file directly under the root directory. The file is required by Composer, which describes
the metadata about your extension. Please refer to the [Composer Manual](https://getcomposer.org/doc/01-basic-usage.md#composer-json-project-setup)
for more details about the file format.
3. Create a VCS (version control system) repository to host the extension files. Any future development
and maintenance work about the extension should be done on this repository.
4. Register your extension with a Composer repository so that other users can find and install your extension.
If you are creating an open source extension, you can register it with [Packagist](https://packagist.org/);
If you are creating a private extension for internal use, you may register it with
[your own repository](https://getcomposer.org/doc/05-repositories.md#hosting-your-own).
As an example, you may refer to the [yiisoft/yii2-bootstrap](widget-bootstrap) extension which provides a set of
widgets encapsulating the Twitter Bootstrap plugins. The extension is hosted on [GitHub](https://github.com/yiisoft/yii2-bootstrap)
and registered with [Packagist](https://packagist.org/packages/yiisoft/yii2-bootstrap). Below is the content
of its `composer.json` file (some unimportant content is removed for simplicity):
```json
{
"name": "yiisoft/yii2-bootstrap",
"description": "The Twitter Bootstrap extension for the Yii framework",
"keywords": ["yii2", "bootstrap"],
"type": "yii2-extension",
"license": "BSD-3-Clause",
"require": {
"yiisoft/yii2": "*",
"twbs/bootstrap": "3.1.* | 3.0.*"
},
"autoload": {
"psr-4": {
"yii\\bootstrap\\": ""
}
}
}
```
### Yii2 Extensions
When creating a Composer package, you may specify the package type to be `yii2-extension`, like shown in the example
in the last subsection. This is recommended if your package is an extension that is specifically designed to be
used in Yii applications. By using `yii2-extension` as the package type, your package can get the following extra benefits:
For example, if your package contains a Yii [widget](structure-widgets.md), it is most likely
that the package
## Installing Extensions Manually
In some rare occasions, you may want to install some or all extensions manually, rather than relying on Composer.
To do so, you should
1. download the extension archive files and unpack them in the `vendor` directory.
2. install the class autoloaders provided by the extensions, if any.
3. download and install all dependent extensions as instructed.
If an extension does not have a class autoloader but follows the
[PSR-4 standard](https://github.com/php-fig/fig-standards/blob/master/proposed/psr-4-autoloader/psr-4-autoloader.md),
you may use the class autoloader provided by Yii to autoload the extension classes. All you need to do is just to
declare a [root alias](concept-aliases.md#defining-aliases) for the extension root directory. For example,
assuming you have installed an extension in the directory `vendor/mycompany/myext`, and the extension classes
are under the `myext` namespace, then you can include the following code in your application configuration:
```php
[
'aliases' => [
'@myext' => '@vendor/mycompany/myext',
],
]
```
## Core Extensions
## Best Practices
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