diff --git a/apps/advanced/common/models/User.php b/apps/advanced/common/models/User.php index b3156a251b..6f43b28710 100644 --- a/apps/advanced/common/models/User.php +++ b/apps/advanced/common/models/User.php @@ -44,6 +44,20 @@ class User extends ActiveRecord implements IdentityInterface ]; } + /** + * @inheritdoc + */ + public function rules() + { + return [ + ['status', 'default', 'value' => self::STATUS_ACTIVE], + ['status', 'in', 'range' => [self::STATUS_ACTIVE, self::STATUS_DELETED]], + + ['role', 'default', 'value' => self::ROLE_USER], + ['role', 'in', 'range' => [self::ROLE_USER]], + ]; + } + /** * @inheritdoc */ diff --git a/apps/advanced/frontend/models/SignupForm.php b/apps/advanced/frontend/models/SignupForm.php index 0597cbc664..17bcdeb51a 100644 --- a/apps/advanced/frontend/models/SignupForm.php +++ b/apps/advanced/frontend/models/SignupForm.php @@ -48,7 +48,7 @@ class SignupForm extends Model $user->email = $this->email; $user->setPassword($this->password); $user->generateAuthKey(); - $user->save(false); + $user->save(); return $user; } diff --git a/apps/advanced/init b/apps/advanced/init index a82de2742b..4858321b1a 100755 --- a/apps/advanced/init +++ b/apps/advanced/init @@ -5,7 +5,7 @@ * * In order to run in non-interactive mode: * - * init --env=dev --overwrite=n + * init --env=Development --overwrite=n * * @author Alexander Makarov * diff --git a/docs/documentation_style_guide.md b/docs/documentation_style_guide.md new file mode 100644 index 0000000000..f26a54fe95 --- /dev/null +++ b/docs/documentation_style_guide.md @@ -0,0 +1,27 @@ +# Yii Documentation Style Guide + +Guidelines to go by when writing or editing any Yii documentation. + +*This needs to be expanded.* + +## General Style + +* Try to use an active voice. +* Use short, declarative sentences. +* Demonstrate ideas using code as much as possible. +* Never use "we". It's the Yii development team or the Yii core team. Better yet to put things in terms of the framework or the guide. +* Use the Oxford comma (e.g., "this, that, and the other" not "this, that and the other"). +* Numeric lists should be complete sentences that end with periods (or other punctuation). +* Bullet lists should be fragments that don't end with periods. + +## Formatting + +## References + +* Yii 2.0 or Yii 2 (not Yii2 or Yii2.0) +* Each "page" of the guide is referred to as a "section". + +## Capitalizations + +* Web, not web +* the guide or this guide, not the Guide \ No newline at end of file diff --git a/docs/guide/README.md b/docs/guide/README.md index e8c54f5624..afe817ecbc 100644 --- a/docs/guide/README.md +++ b/docs/guide/README.md @@ -18,11 +18,13 @@ Introduction Getting Started --------------- -* [Preparing Your Environment](start-environment.md) -* [Creating Your First Yii Application](start-basic.md) -* [Application Structure](start-structure.md) -* [Request Lifecycle](start-lifecycle.md) -* **TBD** [Next Steps](start-next-steps.md) +* [Installing Yii](start-installation.md) +* [Running Applications](start-workflow.md) +* [Saying "Hello World"](start-hello-world.md) +* [Working with Forms](start-forms.md) +* [Working with Databases](start-databases.md) +* [Generating Code with Gii](start-gii.md) +* [Looking Ahead](start-looking-head.md) Application Structure @@ -77,8 +79,8 @@ Working with Databases * **TBD** [ElasticSearch](db-elastic-search.md) -Getting User Inputs -------------------- +Getting Data from Users +----------------------- * [Creating Forms](input-forms.md) * [Input Validation](input-validation.md) @@ -86,7 +88,7 @@ Getting User Inputs * **TBD** [Inputs for Multiple Models](input-multiple-models.md) -Presenting Data +Displaying Data --------------- * **TBD** [Data Formatting](output-formatting.md) @@ -190,7 +192,6 @@ Widgets * **TBD** [Jquery UI Widgets](jui-widgets.md) - Helpers ------- diff --git a/docs/guide/bootstrap-widgets.md b/docs/guide/bootstrap-widgets.md index a44298959a..ec33073a31 100644 --- a/docs/guide/bootstrap-widgets.md +++ b/docs/guide/bootstrap-widgets.md @@ -1,7 +1,7 @@ Bootstrap Widgets ================= -> Note: This chapter is under development. +> Note: This section is under development. Out of the box, Yii includes support for the [Bootstrap 3](http://getbootstrap.com/) markup and components framework (also known as "Twitter Bootstrap"). Bootstrap is an excellent, responsive framework that can greatly speed up the diff --git a/docs/guide/caching-overview.md b/docs/guide/caching-overview.md index 5fcee7d51e..714cfd29d1 100644 --- a/docs/guide/caching-overview.md +++ b/docs/guide/caching-overview.md @@ -1,7 +1,7 @@ Caching ======= -> Note: This chapter is under development. +> Note: This section is under development. Caching is a cheap and effective way to improve the performance of a web application. By storing relatively static data in cache and serving it from cache when requested, the application saves the time required to generate the data from scratch. Caching is one of the best ways to improve the performance of your application, almost mandatory on any large-scale site. diff --git a/docs/guide/concept-autoloading.md b/docs/guide/concept-autoloading.md index 0e6bfb0586..f6ca0855ca 100644 --- a/docs/guide/concept-autoloading.md +++ b/docs/guide/concept-autoloading.md @@ -6,7 +6,7 @@ to locate and include required class files. It provides a high-performance class [PSR-4 standard](https://github.com/php-fig/fig-standards/blob/master/proposed/psr-4-autoloader/psr-4-autoloader.md). The autoloader is installed when you include the `Yii.php` file. -> Note: For simplicity of description, in this chapter we will only talk about autoloading of classes. However, keep in +> Note: For simplicity of description, in this section we will only talk about autoloading of classes. However, keep in mind that the content we are describing here applies to autoloading of interfaces and traits as well. diff --git a/docs/guide/concept-behaviors.md b/docs/guide/concept-behaviors.md index 28429acaef..b18033f248 100644 --- a/docs/guide/concept-behaviors.md +++ b/docs/guide/concept-behaviors.md @@ -15,7 +15,7 @@ Using Behaviors --------------- To use a behavior, you first need to attach it to a [[yii\base\Component|component]]. We will describe how to -attach a behavior in the next section. +attach a behavior in the next subsection. Once a behavior is attached to a component, its usage is straightforward. @@ -129,7 +129,7 @@ $component->attachBehavior('myBehavior3', [ ``` You may also attach behaviors through [configurations](concept-configurations.md). For more details, please -refer to the [Configurations](concept-configurations.md#configuration-format) chapter. +refer to the [Configurations](concept-configurations.md#configuration-format) section. @@ -184,7 +184,7 @@ class MyBehavior extends Behavior } ``` -The above code defines the behavior class `app\components\MyBehavior` which will provides two properties +The above code defines the behavior class `app\components\MyBehavior` which will provide two properties `prop1` and `prop2`, and one method `foo()` to the component it is attached to. Note that property `prop2` is defined via the getter `getProp2()` and the setter `setProp2()`. This is so because [[yii\base\Object]] is an ancestor class of [[yii\base\Behavior]], which supports defining [properties](concept-properties.md) by getters/setters. @@ -227,7 +227,7 @@ its handler `beforeValidate()`. When specifying an event handler, you may use on * an anonymous function. The signature of an event handler should be as follows, where `$event` refers to the event parameter. Please refer -to the [Events](concept-events.md) chapter for more details about events. +to the [Events](concept-events.md) section for more details about events. ```php function ($event) { diff --git a/docs/guide/concept-configurations.md b/docs/guide/concept-configurations.md index a846ad0778..03ff3cea3b 100644 --- a/docs/guide/concept-configurations.md +++ b/docs/guide/concept-configurations.md @@ -58,7 +58,7 @@ where defined by getters/setters can be configured. * The `on eventName` elements specify what handlers should be attached to the object [events](concept-events.md). Notice that the array keys are formed by prefixing event names with `on `. Please refer to - the [Events](concept-events.md) chapter for supported event handler formats. + the [Events](concept-events.md) section for supported event handler formats. * And the `as behaviorName` elements specify what [behaviors](concept-behaviors.md) should be attached to the object. Notice that the array keys are formed by prefixing behavior names with `on `. `$behaviorConfig` represents the configuration for creating a behavior, like a normal configuration as we are describing here. @@ -84,8 +84,8 @@ Below is an example showing a configuration with property initial values, event Using Configurations -------------------- -Configurations are used in many places in Yii. At the beginning of this chapter, we have shown how to use -create an object according to a configuration by using [[Yii::createObject()]]. In this section, we will +Configurations are used in many places in Yii. At the beginning of this section, we have shown how to use +create an object according to a configuration by using [[Yii::createObject()]]. In this subsection, we will describe application configurations and widget configurations - two major usages of configurations. @@ -138,7 +138,7 @@ an [entry script](structure-entry-scripts.md), where the class name is already g ``` For more details about configuring the `components` property of an application can be found -in the [Applications](structure-applications.md) chapter and the [Service Locator](concept-service-locator.md) chapter. +in the [Applications](structure-applications.md) section and the [Service Locator](concept-service-locator.md) section. diff --git a/docs/guide/concept-di-container.md b/docs/guide/concept-di-container.md index b175f5f4c1..8c03e6194c 100644 --- a/docs/guide/concept-di-container.md +++ b/docs/guide/concept-di-container.md @@ -1,30 +1,104 @@ Dependency Injection Container ============================== -Both service locator and dependency injection are popular design patterns that allow building software -in a loosely-coupled fashion. Yii uses service locator and dependency injection extensively, -even though you may not be aware of them. In this tutorial, we will explore their implementation -and support to help you write code more consciously. We also highly recommend you to read -[Martin's article](http://martinfowler.com/articles/injection.html) to get a deeper understanding of -service locator and dependency injection. - A dependency injection (DI) container is an object that knows how to instantiate and configure objects and all their dependent objects. [Martin's article](http://martinfowler.com/articles/injection.html) has well explained why DI container is useful. Here we will mainly explain the usage of the DI container provided by Yii. + + +Dependency Injection +-------------------- + Yii provides the DI container feature through the class [[yii\di\Container]]. It supports the following kinds of dependency injection: * Constructor injection; -* Setter injection; +* Setter and property injection; * PHP callable injection. -### Registering Dependencies + +### Constructor Injection + +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. +The container will try to get the instances of the dependent classes or interfaces and then inject them +into the new object through the constructor. For example, + +```php +class Foo +{ + public function __construct(Bar $bar) + { + } +} + +$foo = $container->get('Foo'); +// which is equivalent to the following: +$bar = new Bar; +$foo = new Foo($bar); +``` + + + +### Setter and Property Injection + +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 +will be used by the container to inject the dependencies through the corresponding setters or properties. +For example, + +```php +use yii\base\Object; + +class Foo extends Object +{ + public $bar; + + private $_qux; + + public function getQux() + { + return $this->_qux; + } + + public function setQux(Qux $qux) + { + $this->_qux = $qux; + } +} + +$container->get('Foo', [], [ + 'bar' => $container->get('Bar'), + 'qux' => $container->get('Qux'), +]); +``` + + + +### PHP Callable Injection + +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 +created objects. For example, + +```php +$container->set('Foo', function () { + return new Foo(new Bar); +}); + +$foo = $container->get('Foo'); +``` + + + +Registering Dependencies +------------------------ You can use [[yii\di\Container::set()]] to register dependencies. The registration requires a dependency name -as well as a dependency definition. The name can be a class name, an interface name, or an alias name; -and the definition can be a class name, a configuration array, or a PHP callable. +as well as a dependency definition. A dependency name can be a class name, an interface name, or an alias name; +and a dependency definition can be a class name, a configuration array, or a PHP callable. ```php $container = new \yii\di\Container; @@ -61,10 +135,14 @@ $container->set('db', [ ]); // register a PHP callable -// The callable will be executed when $container->get('db') is called +// The callable will be executed each time when $container->get('db') is called $container->set('db', function ($container, $params, $config) { return new \yii\db\Connection($config); }); + +// register a component instance +// $container->get('pageCache') will return the same instance each time it is called +$container->set('pageCache', new FileCache); ``` > Tip: If a dependency name is the same as the corresponding dependency definition, you do not @@ -84,28 +162,31 @@ $container->setSingleton('yii\db\Connection', [ ``` -### Resolving Dependencies + +Resolving Dependencies +---------------------- Once you have registered dependencies, you can use the DI container to create new objects, and the container will automatically resolve dependencies by instantiating them and injecting them into the newly created objects. The dependency resolution is recursive, meaning that if a dependency has other dependencies, those dependencies will also be resolved automatically. -You use [[yii\di\Container::get()]] to create new objects. The method takes a class name or -a dependency name (class name, interface name or alias name) that you previously registered -via `set()` or `setSingleton()`. You may optionally provide a list of class constructor parameters -and a list of name-value pairs to configure the newly created object. For example, +You can use [[yii\di\Container::get()]] to create new objects. The method takes a dependency name, +which can be a class name, an interface name or an alias name. The dependency name may or may +not be registered via `set()` or `setSingleton()`. You may optionally provide a list of class +constructor parameters and a [configuration](concept-configurations.md) to configure the newly created object. +For example, ```php -// equivalent to: $map = new \app\components\GoogleMap($apiKey); -$map = $container->get('app\components\GoogleMap', [$apiKey]); - // "db" is a previously registered alias name $db = $container->get('db'); + +// equivalent to: $engine = new \app\components\SearchEngine($apiKey, ['type' => 1]); +$engine = $container->get('app\components\SearchEngine', [$apiKey], ['type' => 1]); ``` Behind the scene, the DI container does much more work than just creating a new object. -The container will inspect the class constructor to find out dependent class or interface names +The container will first inspect the class constructor to find out dependent class or interface names and then automatically resolve those dependencies recursively. The following code shows a more sophisticated example. The `UserLister` class depends on an object implementing @@ -114,7 +195,6 @@ a `Connection` object. All these dependencies are declared through type hinting With property dependency registration, the DI container is able to resolve these dependencies automatically and creates a new `UserLister` instance with a simple call of `get('userLister')`. - ```php namespace app\models; @@ -172,11 +252,13 @@ $lister = new UserLister($finder); ``` -### Practical Usage + +Practical Usages +---------------- -Yii creates a DI container when you include the `yii.php` file in your application's entry script. -The DI container is accessible via [[Yii::$container]]. When you call [[Yii::createObject()]], the method -will actually call the container's [[yii\di\Container::get()|get()]] method to create a new object. +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()]], +the method will actually call the container's [[yii\di\Container::get()|get()]] method to create a new object. As aforementioned, the DI container will automatically resolve the dependencies (if any) and inject them into the newly created object. Because Yii uses [[Yii::createObject()]] in most of its core code to create new objects, this means you can customize the objects globally by dealing with [[Yii::$container]]. @@ -188,13 +270,13 @@ For example, you can customize globally the default number of pagination buttons ``` Now if you use the widget in a view with the following code, the `maxButtonCount` property will be initialized -as 5 instead of 10 as defined in the class. +as 5 instead of the default value 10 as defined in the class. ```php echo \yii\widgets\LinkPager::widget(); ``` -You can still override the value set via DI container: +You can still override the value set via DI container, though: ```php echo \yii\widgets\LinkPager::widget(['maxButtonCount' => 20]); @@ -233,13 +315,29 @@ 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. -### When to Register Dependencies + +When to Register Dependencies +----------------------------- Because dependencies are needed when new objects are being created, their registration should be done as early as possible. The followings are the recommended practices: * If you are the developer of an application, you can register dependencies in your - application's entry script or in a script that is included by the entry script. -* If you are the developer of a redistributable extension, you can register dependencies + application's [entry script](structure-entry-scripts.md) or in a script that is included by the entry script. +* If you are the developer of a redistributable [extension](structure-extensions.md), you can register dependencies in the bootstrap class of the extension. + + +Summary +------- + +Both dependency injection and [service locator](concept-service-locator.md) are popular design patterns +that allow building software in a loosely-coupled and more testable fashion. We highly recommend you to read +[Martin's article](http://martinfowler.com/articles/injection.html) to get a deeper understanding of +dependency injection and service locator. + +Yii implements its [service locator](concept-service-locator.md) on top of the dependency injection (DI) container. +When a service locator is trying to create a new object instance, it will forward the call to the DI container. +The latter will resolve the dependencies automatically as described above. + diff --git a/docs/guide/concept-events.md b/docs/guide/concept-events.md index 82449ddd0a..3f5002265b 100644 --- a/docs/guide/concept-events.md +++ b/docs/guide/concept-events.md @@ -129,7 +129,7 @@ $foo->on(Foo::EVENT_HELLO, function ($event) { ``` You may also attach event handlers through [configurations](concept-configurations.md). For more details, please -refer to the [Configurations](concept-configurations.md#configuration-format) chapter. +refer to the [Configurations](concept-configurations.md#configuration-format) section. When attaching an event handler, you may provide additional data as the third parameter to [[yii\base\Component::on()]]. @@ -201,7 +201,7 @@ $foo->off(Foo::EVENT_HELLO); Class-Level Event Handlers -------------------------- -In the above sections, we have described how to attach a handler to an event at *instance level*. +In the above subsections, we have described how to attach a handler to an event at *instance level*. Sometimes, you may want to respond to an event triggered by EVERY instance of a class instead of a specific instance. Instead of attaching an event handler to every instance, you may attach the handler at *class level* by calling the static method [[yii\base\Event::on()]]. diff --git a/docs/guide/concept-service-locator.md b/docs/guide/concept-service-locator.md index 4350981acb..cc9c3e1e0e 100644 --- a/docs/guide/concept-service-locator.md +++ b/docs/guide/concept-service-locator.md @@ -1,24 +1,16 @@ Service Locator =============== -> Note: This chapter needs cleanup. - -Both service locator and dependency injection are popular design patterns that allow building software -in a loosely-coupled fashion. Yii uses service locator and dependency injection extensively, -even though you may not be aware of them. In this tutorial, we will explore their implementation -and support to help you write code more consciously. We also highly recommend you to read -[Martin's article](http://martinfowler.com/articles/injection.html) to get a deeper understanding of -service locator and dependency injection. - A service locator is an object that knows how to provide all sorts of services (or components) that an application might need. Within a service locator, each component has only a single instance which is uniquely identified by an ID. -You use the ID to retrieve a component from the service locator. In Yii, a service locator is simply an instance -of [[yii\di\ServiceLocator]] or its child class. +You use the ID to retrieve a component from the service locator. + +In Yii, a service locator is simply an instance of [[yii\di\ServiceLocator]] or its child class. The most commonly used service locator in Yii is the *application* object which can be accessed through -`\Yii::$app`. The services it provides are called *application components*, such as `request`, `response`, -`urlManager`. You may configure these components or replace them with your own implementations easily -through functionality provided the service locator. +`\Yii::$app`. The services it provides are called *application components*, such as the `request`, `response`, +`urlManager` components. You may configure these components or even replace them with your own implementations easily +through functionality provided by the service locator. Besides the application object, each module object is also a service locator. @@ -26,7 +18,10 @@ To use a service locator, the first step is to register components. A component via [[yii\di\ServiceLocator::set()]]. The following code shows different ways of registering components: ```php -$locator = new \yii\di\ServiceLocator; +use yii\di\ServiceLocator; +use yii\caching\FileCache; + +$locator = new ServiceLocator; // register "cache" using a class name that can be used to create a component $locator->set('cache', 'yii\caching\ApcCache'); @@ -43,6 +38,9 @@ $locator->set('db', [ $locator->set('search', function () { return new app\components\SolrService; }); + +// register "pageCache" using a component +$locator->set('pageCache', new FileCache); ``` Once a component is registered, you can access it using its ID in one of the following two ways: @@ -62,11 +60,10 @@ You may use [[yii\di\ServiceLocator::has()]] to check if a component ID has alre If you call [[yii\di\ServiceLocator::get()]] with an invalid ID, an exception will be thrown. -Because service locators are often being configured using configuration arrays, a method named -[[yii\di\ServiceLocator::setComponents()]] is provided to allow registering components in configuration arrays. -The method is a setter which defines a writable property `components` that can be configured. -The following code shows a configuration array that can be used to configure an application and register -the "db", "cache" and "search" components: +Because service locators are often being created with [configurations](concept-configurations.md), +a writable property named [[yii\di\ServiceLocator::setComponents()|components]] is provided so that +you can configure it and register multiple components at once. The following code shows a configuration array +that can be used to configure an application and register the "db", "cache" and "search" components: ```php return [ diff --git a/docs/guide/db-active-record.md b/docs/guide/db-active-record.md index 1057ef7e11..584f8c7c5f 100644 --- a/docs/guide/db-active-record.md +++ b/docs/guide/db-active-record.md @@ -1,7 +1,7 @@ Active Record ============= -> Note: This chapter is under development. +> Note: This section is under development. [Active Record](http://en.wikipedia.org/wiki/Active_record_pattern) provides an object-oriented interface for accessing data stored in a database. An Active Record class is associated with a database table, diff --git a/docs/guide/db-dao.md b/docs/guide/db-dao.md index b7f1940367..d5eac7d7ad 100644 --- a/docs/guide/db-dao.md +++ b/docs/guide/db-dao.md @@ -1,7 +1,7 @@ Database basics =============== -> Note: This chapter is under development. +> Note: This section is under development. Yii has a database access layer built on top of PHP's [PDO](http://www.php.net/manual/en/book.pdo.php). It provides uniform API and solves some inconsistencies between different DBMS. By default Yii supports the following DBMS: @@ -182,7 +182,7 @@ Quoting table and column names Most of the time you would use the following syntax for quoting table and column names: ```php -$sql = "SELECT COUNT([[$column]]) FROM {{$table}}"; +$sql = "SELECT COUNT([[$column]]) FROM {{table}}"; $rowCount = $connection->createCommand($sql)->queryScalar(); ``` @@ -192,7 +192,7 @@ quoted table name. For table names there's a special variant `{{%Y}}` that allows you to automatically appending table prefix if it is set: ```php -$sql = "SELECT COUNT([[$column]]) FROM {{%$table}}"; +$sql = "SELECT COUNT([[$column]]) FROM {{%table}}"; $rowCount = $connection->createCommand($sql)->queryScalar(); ``` diff --git a/docs/guide/db-migrations.md b/docs/guide/db-migrations.md index afcb0e22f3..c591fa499a 100644 --- a/docs/guide/db-migrations.md +++ b/docs/guide/db-migrations.md @@ -1,7 +1,7 @@ Database Migration ================== -> Note: This chapter is under development. +> Note: This section is under development. Like source code, the structure of a database evolves as a database-driven application is developed and maintained. For example, during development, a new table may be added; Or, after the application goes live, it may be discovered that an additional index is required. It is important to keep track of these structural database changes (called **migration**), just as changes to the source code is tracked using version control. If the source code and the database become out of sync, bugs will occur, or the whole application might break. For this reason, Yii provides a database migration tool that can keep track of database migration history, apply new migrations, or revert existing ones. diff --git a/docs/guide/db-query-builder.md b/docs/guide/db-query-builder.md index a73613af08..b30aedff7d 100644 --- a/docs/guide/db-query-builder.md +++ b/docs/guide/db-query-builder.md @@ -1,7 +1,7 @@ Query Builder and Query ======================= -> Note: This chapter is under development. +> Note: This section is under development. Yii provides a basic database access layer as described in the [Database basics](database-basics.md) section. The database access layer provides a low-level way to interact with the database. While useful in some situations, diff --git a/docs/guide/extend-creating-extensions.md b/docs/guide/extend-creating-extensions.md index cb5e6ab3d0..d1ab25a691 100644 --- a/docs/guide/extend-creating-extensions.md +++ b/docs/guide/extend-creating-extensions.md @@ -1,7 +1,7 @@ Extending Yii ============= -> Note: This chapter is under development. +> 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. diff --git a/docs/guide/extend-customizing-core.md b/docs/guide/extend-customizing-core.md index ef05c915af..e9e8d6ce9c 100644 --- a/docs/guide/extend-customizing-core.md +++ b/docs/guide/extend-customizing-core.md @@ -1,7 +1,7 @@ Helper Classes ============== -> Note: This chapter is under development. +> 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 diff --git a/docs/guide/extend-using-composer.md b/docs/guide/extend-using-composer.md index 2da5bf9662..2058e3a2d5 100644 --- a/docs/guide/extend-using-composer.md +++ b/docs/guide/extend-using-composer.md @@ -1,7 +1,7 @@ Composer ======== -> Note: This chapter is under development. +> Note: This section is under development. Yii2 uses Composer as its dependency management tool. Composer is a PHP utility that can automatically handle the installation of needed libraries and extensions, thereby keeping those third-party resources up to date while absolving you of the need to manually manage the project's dependencies. diff --git a/docs/guide/extend-using-libs.md b/docs/guide/extend-using-libs.md index 805ff47a62..27fd2d7913 100644 --- a/docs/guide/extend-using-libs.md +++ b/docs/guide/extend-using-libs.md @@ -1,7 +1,7 @@ Using 3rd-Party Libraries ========================= -> Note: This chapter is under development. +> Note: This section is under development. Yii is carefully designed so that third-party libraries can be easily integrated to further extend Yii's functionalities. diff --git a/docs/guide/helper-overview.md b/docs/guide/helper-overview.md index 78a6d97832..df17c1fa2a 100644 --- a/docs/guide/helper-overview.md +++ b/docs/guide/helper-overview.md @@ -1,7 +1,7 @@ Helpers ======= -> Note: This chapter is under development. +> Note: This section is under development. Helper classes typically contain static methods only and are used as follows: diff --git a/docs/guide/input-forms.md b/docs/guide/input-forms.md index 74dac43c1d..144a07d036 100644 --- a/docs/guide/input-forms.md +++ b/docs/guide/input-forms.md @@ -1,7 +1,7 @@ Working with forms ================== -> Note: This chapter is under development. +> Note: This section is under development. The primary way of using forms in Yii is through [[yii\widgets\ActiveForm]]. This approach should be preferred when the form is based upon a model. Additionally, there are some useful methods in [[yii\helpers\Html]] that are typically diff --git a/docs/guide/input-validation.md b/docs/guide/input-validation.md index 9e775c6832..31e0275c9d 100644 --- a/docs/guide/input-validation.md +++ b/docs/guide/input-validation.md @@ -1,7 +1,7 @@ Model validation reference ========================== -> Note: This chapter is under development. +> Note: This section is under development. As a model both represents data and defines the business rules to which that data must adhere, comprehending data validation is key to using Yii. In order to learn model validation basics, please refer to [Model, Validation subsection](model.md#Validation). diff --git a/docs/guide/intro-upgrade-from-v1.md b/docs/guide/intro-upgrade-from-v1.md index 62b9f98cc0..b29d4463fe 100644 --- a/docs/guide/intro-upgrade-from-v1.md +++ b/docs/guide/intro-upgrade-from-v1.md @@ -1,30 +1,29 @@ Upgrading from Version 1.1 ========================== -There are many differences between Yii version 2.0 and 1.1, because Yii is completely rewritten for 2.0. -As a result, upgrading from version 1.1 is not as trivial as upgrading between minor versions. In this chapter, -we will summarize the major differences between the two versions. +There are many differences between versions 1.1 and 2.0 of the Yii as the framework 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. -Please note that Yii 2.0 introduces many new features which are not covered in this summary. It is highly recommended -that you read through the whole definitive guide to learn about these features. Chances could be that -some features you previously have to develop by yourself are already part of the core code now. +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 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. Installation ------------ -Yii 2.0 fully embraces [Composer](https://getcomposer.org/), a de facto PHP package manager. Installation -of the core framework as well as extensions are all installed through Composer. Please refer to -the [Starting from Basic App](start-basic.md) chapter to learn how to install Yii 2.0. If you want to -create new extensions or turn your existing 1.1 extensions into 2.0, please refer to -the [Creating Extensions](extend-creating-extensions.md) chapter. +Yii 2.0 fully embraces [Composer](https://getcomposer.org/), the de facto PHP package manager. Installation +of the core framework, as well as extensions, are handled through Composer. Please refer to +the [Starting from Basic App](start-basic.md) section to learn how to install Yii 2.0. If you want to +create new extensions, or turn your existing 1.1 extensions into 2.0-compatible extensions, please refer to +the [Creating Extensions](extend-creating-extensions.md) section of the guide. PHP Requirements ---------------- -Yii 2.0 requires PHP 5.4 or above, which is a huge improvement over PHP 5.2 as required by Yii 1.1. -As a result, there are many differences at language level that you should pay attention to. +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: - [Namespaces](http://php.net/manual/en/language.namespaces.php). @@ -44,10 +43,11 @@ 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 of the namespaces follows the directory structure. For example, `yii\web\Request` -indicates the corresponding class file is `web/Request.php` under the Yii framework folder. -You can use any core class without explicitly including that class file, thanks to the Yii -class loader. +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. + +(You can use any core class without explicitly including that class file, thanks to the Yii +class loader.) Component and Object @@ -90,12 +90,12 @@ class MyClass extends \yii\base\Object ``` In the above, the last parameter of the constructor must take a configuration array -which contains name-value pairs for initializing the properties at the end of the constructor. +that contains name-value pairs for initializing the properties at the end of the constructor. You can override the [[yii\base\Object::init()|init()]] method to do initialization work that should be done after -the configuration is applied. +the configuration has been applied. -By following this convention, you will be able to create and configure a new object -using a configuration array like the following: +By following this convention, you will be able to create and configure new objects +using a configuration array: ```php $object = Yii::createObject([ @@ -105,14 +105,13 @@ $object = Yii::createObject([ ], [$param1, $param2]); ``` -More details about configurations can be found in the [Object Configurations](concept-configurations.md) chapter. +More details about configurations can be found in the [Object Configurations](concept-configurations.md) section. Events ------ -There is no longer the need to define an `on`-method in order to define an event in Yii 2.0. -Instead, you can use whatever event names. You can trigger an event by calling +In Yii 1, events were created by defining an `on`-method (e.g., `onBeforeSave`). In Yii 2, you can now use any event name. You trigger an event by calling the [[yii\base\Component::trigger()|trigger()]] method: ```php @@ -120,7 +119,7 @@ $event = new \yii\base\Event; $component->trigger($eventName, $event); ``` -And to attach a handler to an event, you can use the [[yii\base\Component::on()|on()]] method: +To attach a handler to an event, use the [[yii\base\Component::on()|on()]] method: ```php $component->on($eventName, $handler); @@ -128,39 +127,38 @@ $component->on($eventName, $handler); // $component->off($eventName, $handler); ``` -There are many enhancements to the event features. For more details, please refer to the [Events](concept-events.md) chapter. +There are many enhancements to the event features. For more details, please refer to the [Events](concept-events.md) section. Path Aliases ------------ -Yii 2.0 expands the usage of path aliases to both file/directory paths and URLs. It also requires -an alias name to start with a `@` character so that it can be differentiated from normal file/directory paths and URLs. +Yii 2.0 expands the usage of path aliases to both file/directory paths and URLs. Yii 2.0 also now requires +an alias name to start with the `@` character, to differentiate aliases from normal file/directory paths or URLs. For example, the alias `@yii` refers to the Yii installation directory. Path aliases are supported in most places in the Yii core code. For example, [[yii\caching\FileCache::cachePath]] can take both a path alias and a normal directory path. -Path alias is also closely related with class namespaces. It is recommended that a path -alias be defined for each root namespace so that you can use Yii the class autoloader without +A path alias is also closely related to a class namespace. It is recommended that a path +alias be defined for each root namespace, thereby allowing you to use Yii the class autoloader without any further configuration. For example, because `@yii` refers to the Yii installation directory, -a class like `yii\web\Request` can be autoloaded by Yii. If you use a third party library -such as Zend Framework, you may define a path alias `@Zend` which refers to its installation -directory and Yii will be able to autoload any class in this library. +a class like `yii\web\Request` can be autoloaded. If you use a third party library, +such as the Zend Framework, you may define a path alias `@Zend` that refers to that framework's installation +directory. Once you've done that, Yii will be able to autoload any class in that Zend Framework library, too. -More on path aliases can be found in the [Path Aliases](concept-aliases.md) chapter. +More on path aliases can be found in the [Path Aliases](concept-aliases.md) section. Views ----- -The most significant change about views is that `$this` in a view no longer refers to -the current controller or widget. Instead, it refers to a *view* object which is a new concept -introduced in 2.0. The *view* object is of class [[yii\web\View]] which represents the view part -of the MVC pattern. In you want to access the controller or widget in a view, you should use `$this->context`. +The most significant change about views in Yii 2 is that the special variable `$this` in a view no longer refers to +the current controller or widget. Instead, `$this` now refers to a *view* object, a new concept +introduced in 2.0. The *view* object is of type [[yii\web\View]], which represents the view part +of the MVC pattern. In you want to access the controller or widget in a view, you can use `$this->context`. -To render a partial view within another view, you should use `$this->render()` now. -And you have to echo it explicitly because the `render()` method will return the rendering -result rather than directly displaying it. For example, +To render a partial view within another view, you use `$this->render()`, not `$this->renderPartial()`. The call to `render` also now has to be explicitly echoed, as the `render()` method returns the rendering +result, rather than directly displaying it. For example: ```php echo $this->render('_item', ['item' => $item]); @@ -170,18 +168,17 @@ Besides using PHP as the primary template language, Yii 2.0 is also equipped wit support for two popular template engines: Smarty and Twig. The Prado template engine is no longer supported. To use these template engines, you need to configure the `view` application component by setting the [[yii\base\View::$renderers|View::$renderers]] property. Please refer to the [Template Engines](tutorial-template-engines.md) -chapter for more details. +section for more details. Models ------ -Yii 2.0 uses [[yii\base\Model]] as the base model class which is similar to `CModel` in 1.1. -The class `CFormModel` is dropped. Instead, you should extend [[yii\base\Model]] to create a form model class. +Yii 2.0 uses [[yii\base\Model]] as the base model, similar to `CModel` in 1.1. +The class `CFormModel` has been dropped entirely. Instead, in Yii 2 you should extend [[yii\base\Model]] to create a form model class. Yii 2.0 introduces a new method called [[yii\base\Model::scenarios()|scenarios()]] to declare -supported scenarios and under which scenario an attribute needs to be validated and can be considered as safe or not. -For example, +supported scenarios, and to indicate under which scenario an attribute needs to be validated, can be considered as safe or not, etc. For example: ```php public function scenarios() @@ -193,28 +190,27 @@ public function scenarios() } ``` -In the above, two scenarios are declared: `backend` and `frontend`. For the `backend` scenario, both of the -`email` and `role` attributes are safe and can be massively assigned; for the `frontend` scenario, -`email` can be massively assigned while `role` cannot. Both `email` and `role` should be validated. +In the above, two scenarios are declared: `backend` and `frontend`. For the `backend` scenario, both the +`email` and `role` attributes are safe, and can be massively assigned. For the `frontend` scenario, +`email` can be massively assigned while `role` cannot. Both `email` and `role` should be validated using rules. -The [[yii\base\Model::rules()|rules()]] method is still used to declare validation rules. Note that because -of the introduction of [[yii\base\Model::scenarios()|scenarios()]], there is no more `unsafe` validator. +The [[yii\base\Model::rules()|rules()]] method is still used to declare the validation rules. Note that due to the introduction of [[yii\base\Model::scenarios()|scenarios()]], there is no longer an `unsafe` validator. In most cases, you do not need to override [[yii\base\Model::scenarios()|scenarios()]] -if the [[yii\base\Model::rules()|rules()]] method fully specifies the scenarios and there is no need to declare +if the [[yii\base\Model::rules()|rules()]] method fully specifies the scenarios that will exist, and if there is no need to declare `unsafe` attributes. -To learn more details about models, please refer to the [Models](basic-models.md) chapter. +To learn more details about models, please refer to the [Models](basic-models.md) section. Controllers ----------- -Yii 2.0 uses [[yii\web\Controller]] as the base controller class which is similar to `CWebController` in 1.1. -And [[yii\base\Action]] is the base class for action classes. +Yii 2.0 uses [[yii\web\Controller]] as the base controller class, similar to `CWebController` in Yii 1.1. +[[yii\base\Action]] is the base class for action classes. -The most obvious change when you write code in a controller action is that you should return the content -that you want to render instead of echoing it. For example, +The most obvious impact of these changes on your code is that a controller action should return the content +that you want to render instead of echoing it: ```php public function actionView($id) @@ -228,17 +224,17 @@ public function actionView($id) } ``` -Please refer to the [Controllers](structure-controllers.md) chapter for more details about controllers. +Please refer to the [Controllers](structure-controllers.md) section for more details about controllers. Widgets ------- -Yii 2.0 uses [[yii\base\Widget]] as the base widget class which is similar to `CWidget` in 1.1. +Yii 2.0 uses [[yii\base\Widget]] as the base widget class, similar to `CWidget` in Yii 1.1. -To get better IDE support, Yii 2.0 introduces a new syntax for using widgets. The static methods -[[yii\base\Widget::begin()|begin()]], [[yii\base\Widget::end()|end()]] and [[yii\base\Widget::widget()|widget()]] -are introduced and can be used as follows, +To get better support for the framework in IDEs, Yii 2.0 introduces a new syntax for using widgets. The static methods +[[yii\base\Widget::begin()|begin()]], [[yii\base\Widget::end()|end()]], and [[yii\base\Widget::widget()|widget()]] +have been introduced, to be used like so: ```php use yii\widgets\Menu; @@ -256,29 +252,29 @@ $form = ActiveForm::begin([ ActiveForm::end(); ``` -Please refer to the [Widgets](structure-widgets.md) chapter for more details. +Please refer to the [Widgets](structure-widgets.md) section for more details. Themes ------ -Themes work completely different in 2.0. They are now based on a path mapping mechanism which maps a source +Themes work completely differently in 2.0. They are now based on a path mapping mechanism that maps a source view file path to a themed view file path. For example, if the path map for a theme is -`['/web/views' => '/web/themes/basic']`, then the themed version for a view file +`['/web/views' => '/web/themes/basic']`, then the themed version for the view file `/web/views/site/index.php` will be `/web/themes/basic/site/index.php`. For this reason, themes can now -be applied to any view file, even if a view rendered outside of the context of a controller or a widget. +be applied to any view file, even a view rendered outside of the context of a controller or a widget. -Also, there is no more `CThemeManager`. Instead, `theme` is a configurable property of the `view` +Also, there is no more `CThemeManager` component. Instead, `theme` is a configurable property of the `view` application component. -Please refer to the [Theming](tutorial-theming.md) chapter for more details. +Please refer to the [Theming](tutorial-theming.md) section for more details. Console Applications -------------------- Console applications are now organized as controllers, like Web applications. Console controllers -should extend from [[yii\console\Controller]] which is similar to `CConsoleCommand` in 1.1. +should extend from [[yii\console\Controller]], similar to `CConsoleCommand` in 1.1. To run a console command, use `yii `, where `` stands for a controller route (e.g. `sitemap/index`). Additional anonymous arguments are passed as the parameters to the @@ -287,27 +283,26 @@ the declarations in [[yii\console\Controller::options()]]. Yii 2.0 supports automatic generation of command help information from comment blocks. -Please refer to the [Console Commands](tutorial-console.md) chapter for more details. +Please refer to the [Console Commands](tutorial-console.md) section for more details. I18N ---- -Yii 2.0 removes date formatter and number formatter in favor of the PECL intl PHP module. +Yii 2.0 removes the built-in date formatter and number formatter pieces in favor of the [PECL intl PHP module](http://pecl.php.net/package/intl). Message translation is now performed via the `i18n` application component. -The component manages a set of message sources, which allows you to use different message +This component manages a set of message sources, which allows you to use different message sources based on message categories. -Please refer to the [Internationalization](tutorial-i18n.md) chapter for more details. +Please refer to the [Internationalization](tutorial-i18n.md) section for more details. Action Filters -------------- -Action filters are implemented via behaviors now. You should extend from [[yii\base\ActionFilter]] to -define a new filter. To use a filter, you should attach the filter class to the controller -as a behavior. For example, to use the [[yii\filters\AccessControl]] filter, you should have the following +Action filters are implemented via behaviors now. To define a new, custom filter, extend from [[yii\base\ActionFilter]]. To use a filter, attach the filter class to the controller +as a behavior. For example, to use the [[yii\filters\AccessControl]] filter, you would have the following code in a controller: ```php @@ -324,27 +319,27 @@ public function behaviors() } ``` -Please refer to the [Filtering](runtime-filtering.md) chapter for more details. +Please refer to the [Filtering](runtime-filtering.md) section for more details. Assets ------ -Yii 2.0 introduces a new concept called *asset bundle* which replaces the script package concept in 1.1. +Yii 2.0 introduces a new concept called *asset bundle* that replaces the script package concept found in Yii 1.1. An asset bundle is a collection of asset files (e.g. JavaScript files, CSS files, image files, etc.) -under a directory. Each asset bundle is represented as a class extending [[yii\web\AssetBundle]]. -By registering an asset bundle via [[yii\web\AssetBundle::register()]], you will be able to make -the assets in that bundle accessible via Web, and the page registering the bundle will automatically +within a directory. Each asset bundle is represented as a class extending [[yii\web\AssetBundle]]. +By registering an asset bundle via [[yii\web\AssetBundle::register()]], you make +the assets in that bundle accessible via the Web. Unlike in Yii 1, the page registering the bundle will automatically contain the references to the JavaScript and CSS files specified in that bundle. -Please refer to the [Managing Assets](output-assets.md) chapter for more details. +Please refer to the [Managing Assets](output-assets.md) section for more details. Helpers ------- -Yii 2.0 introduces many commonly used static helper classes, such as +Yii 2.0 introduces many commonly used static helper classes, including. * [[yii\helpers\Html]] * [[yii\helpers\ArrayHelper]] @@ -353,13 +348,14 @@ Yii 2.0 introduces many commonly used static helper classes, such as * [[yii\helpers\Json]] * [[yii\helpers\Security]] +Please refer to the [Helper Overview](helper-overview.md) section for more details. Forms ----- Yii 2.0 introduces the *field* concept for building a form using [[yii\widgets\ActiveForm]]. A field is a container consisting of a label, an input, an error message, and/or a hint text. -It is represented as an [[yii\widgets\ActiveField|ActiveField]] object. +A field is represented as an [[yii\widgets\ActiveField|ActiveField]] object. Using fields, you can build a form more cleanly than before: ```php @@ -372,13 +368,15 @@ Using fields, you can build a form more cleanly than before: ``` +Please refer to the [Creating Forms](input-forms.md) section for more details. + Query Builder ------------- -In 1.1, query building is scattered among several classes, including `CDbCommand`, +In 1.1, query building was scattered among several classes, including `CDbCommand`, `CDbCriteria`, and `CDbCommandBuilder`. Yii 2.0 represents a DB query in terms of a [[yii\db\Query|Query]] object -which can be turned into a SQL statement with the help of [[yii\db\QueryBuilder|QueryBuilder]] behind the scene. +that can be turned into a SQL statement with the help of [[yii\db\QueryBuilder|QueryBuilder]] behind the scene. For example: ```php @@ -394,28 +392,27 @@ $rows = $command->queryAll(); Best of all, such query building methods can also be used when working with [Active Record](db-active-record.md). -Please refer to the [Query Builder](db-query-builder.md) chapter for more details. +Please refer to the [Query Builder](db-query-builder.md) section for more details. Active Record ------------- -Yii 2.0 introduces a lot of changes to [Active Record](db-active-record.md). Two most obvious ones are: +Yii 2.0 introduces a lot of changes to [Active Record](db-active-record.md). The two most obvious ones involve query building and relational query handling. -The `CDbCriteria` class in 1.1 is replaced by [[yii\db\ActiveQuery]] which extends from [[yii\db\Query]] and thus -inherits all query building methods. You call [[yii\db\ActiveRecord::find()]] to start building a query. -For example, +The `CDbCriteria` class in 1.1 is replaced by [[yii\db\ActiveQuery]] in Yii 2. That class extends from [[yii\db\Query]], and thus +inherits all query building methods. You call [[yii\db\ActiveRecord::find()]] to start building a query: ```php -// to retrieve all *active* customers and order them by their ID: +// To retrieve all *active* customers and order them by their ID: $customers = Customer::find() ->where(['status' => $active]) ->orderBy('id') ->all(); ``` -To declare a relation, you simply define a getter method that returns an [[yii\db\ActiveQuery|ActiveQuery]] object. +To declare a relation, simply define a getter method that returns an [[yii\db\ActiveQuery|ActiveQuery]] object. The property name defined by the getter represents the relation name. For example, the following code declares an `orders` relation (in 1.1, you would have to declare relations in a central place `relations()`): @@ -429,20 +426,20 @@ class Customer extends \yii\db\ActiveRecord } ``` -You can use `$customer->orders` to access the customer's orders. You can also use the following code -to perform on-the-fly relational query with customized query conditions: +Now you can use `$customer->orders` to access a customer's orders from the related table. You can also use the following code +to perform an on-the-fly relational query with a customized query condition: ```php $orders = $customer->getOrders()->andWhere('status=1')->all(); ``` When eager loading a relation, Yii 2.0 does it differently from 1.1. In particular, in 1.1 a JOIN query -would be created to bring both the primary and the relational records; in 2.0, two SQL statements are executed +would be created to select both the primary and the relational records. In Yii 2.0, two SQL statements are executed without using JOIN: the first statement brings back the primary records and the second brings back the relational records by filtering with the primary keys of the primary records. Instead of returning [[yii\db\ActiveRecord|ActiveRecord]] objects, you may chain the [[yii\db\ActiveQuery::asArray()|asArray()]] -method when building a query to return large number of records. This will cause the query result to be returned +method when building a query to return a large number of records. This will cause the query result to be returned as arrays, which can significantly reduce the needed CPU time and memory if large number of records . For example, ```php @@ -450,7 +447,7 @@ $customers = Customer::find()->asArray()->all(); ``` There are many other changes and enhancements to Active Record. Please refer to -the [Active Record](db-active-record.md) chapter for more details. +the [Active Record](db-active-record.md) section for more details. User and IdentityInterface @@ -458,15 +455,17 @@ User and IdentityInterface The `CWebUser` class in 1.1 is now replaced by [[yii\web\User]], and there is no more `CUserIdentity` class. Instead, you should implement the [[yii\web\IdentityInterface]] which -is much more straightforward to implement. The advanced application template provides such an example. +is much more straightforward to use. The advanced application template provides such an example. + +Please refer to the [Authentication](security-authentication.md), [Authorization](security-authorization.md), and [Advanced Application Technique](tutorial-advanced-app.md) sections for more details. URL Management -------------- -URL management is similar to 1.1. A major enhancement is that it now supports optional -parameters. For example, if you have rule declared as follows, then it will match -both `post/popular` and `post/1/popular`. In 1.1, you would have to use two rules to achieve +URL management in Yii 2 is similar to that in 1.1. A major enhancement is that URL management now supports optional +parameters. For example, if you have a rule declared as follows, then it will match +both `post/popular` and `post/1/popular`. In 1.1, you would have had to use two rules to achieve the same goal. ```php @@ -477,12 +476,11 @@ the same goal. ] ``` -More details in the [Url manager docs](url.md). - +Please refer to the [Url manager docs](url.md) section for more details. Using Yii 1.1 and 2.x together ------------------------------ -If you have legacy Yii 1.1 code and you want to use it together with Yii 2.0, please refer to -the [Using Yii 1.1 and 2.0 Together](extend-using-v1-v2.md) chapter. +If you have legacy Yii 1.1 code that you want to use together with Yii 2.0, please refer to +the [Using Yii 1.1 and 2.0 Together](extend-using-v1-v2.md) section. diff --git a/docs/guide/intro-yii.md b/docs/guide/intro-yii.md index 1c97908026..41c1e4aa15 100644 --- a/docs/guide/intro-yii.md +++ b/docs/guide/intro-yii.md @@ -2,8 +2,8 @@ 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 considered as the acronym for **Yes It Is**! +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**! What is Yii Best for? @@ -22,17 +22,17 @@ How does Yii Compare with Other Frameworks? organization based on this pattern. - Yii takes the philosophy that code should be written in a simple yet elegant way. It will never try to over-design things mainly for the purpose of following some design pattern. -- Yii is a full-stack framework providing many proven and ready-to-use features, such as query builders - and ActiveRecord supporting relational and NoSQL databases, RESTful API development support, multi-tier - caching support, etc. +- Yii is a full-stack framework providing many proven and ready-to-use features, such as: query builders + and ActiveRecord, for both relational and NoSQL databases; RESTful API development support; multi-tier + caching support; and more. - Yii is extremely extensible. You can customize or replace nearly every piece of core code. You can also - take advantage of its solid extension architecture, use or develop redistributable extensions. + take advantage of its solid extension architecture, to use or develop redistributable extensions. - High performance is always a primary goal of Yii. Yii is not a one-man show, it is backed up by a [strong core developer team][] as well as a large community -with many professionals who are constantly contributing to the development of Yii. The Yii developer team -is keeping a close eye on the latest trends of Web development and the best practices and features -found in other frameworks and projects. They are being carefully incorporated into the core framework and exposed +with many professionals constantly contributing to the development of Yii. The Yii developer team +keeps a close eye on the latest trends of Web development, 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 exposed via simple and elegant interfaces. [strong core developer team]: http://www.yiiframework.com/about/ @@ -40,9 +40,8 @@ via simple and elegant interfaces. Yii Versions ------------ -Yii has two major versions available currently: 1.1 and 2.0. Version 1.1 is the old generation and is -currently under maintenance mode. Version 2.0 is a complete rewrite of Yii by adopting the latest -technologies and protocols, such as Composer, PSR, namespaces, traits, etc. Version 2.0 represents the latest +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 complete rewrite of Yii, adopting the latest +technologies and protocols, including Composer, PSR, namespaces, traits, and so forth. Version 2.0 represents the latest generation of the framework and will receive our main development efforts in the next few years. This guide is mainly about version 2.0. @@ -50,11 +49,10 @@ This guide is mainly about version 2.0. Requirements and Prerequisites ------------------------------ -Yii 2.0 requires PHP 5.4.0 or above. You may find out more detailed requirements for individual features -by running the requirement checker included in every release. +Yii 2.0 requires PHP 5.4.0 or above. You can find more detailed requirements for individual features +by running the requirement checker included in every Yii release. Using Yii requires basic knowledge about object-oriented programming (OOP), as Yii is a pure OOP-based framework. -Yii 2.0 also makes use of the latest features of PHP, such as [namespaces](http://www.php.net/manual/en/language.namespaces.php), -[traits](http://www.php.net/manual/en/language.oop5.traits.php). Understanding these concepts will help -you pick up Yii 2.0 more easily. +Yii 2.0 also makes use of the latest features of PHP, such as [namespaces](http://www.php.net/manual/en/language.namespaces.php) and [traits](http://www.php.net/manual/en/language.oop5.traits.php). Understanding these concepts will help +you more easily pick up Yii 2.0. diff --git a/docs/guide/output-assets.md b/docs/guide/output-assets.md index 74ce909f7d..298655c86d 100644 --- a/docs/guide/output-assets.md +++ b/docs/guide/output-assets.md @@ -1,7 +1,7 @@ Managing assets =============== -> Note: This chapter is under development. +> Note: This section is under development. An asset in Yii is a file that is included into the page. It could be CSS, JavaScript or any other file. The framework provides many ways to work with assets from basics such as adding `