php/yii2
1
0
Fork 0
mirror of https://github.com/yiisoft/yii2.git synced 2025-11-17 14:57:23 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' of git://github.com/yiisoft/yii2 into guide-pl

Browse Source
This commit is contained in:
Bizley
2015-08-30 15:28:40 +02:00
parent 415c1d0573 5a5df19f0c
commit df2f6ceba9
43 changed files with 455 additions and 366 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/guide/db-dao.md
View File

@@ -365,7 +365,7 @@ the changes made by the queries prior to that failed query in the transaction.
### Specifying Isolation Levels <span id="specifying-isolation-levels"></span>
Yii also supports setting [isolation levels] for your transactions. By default, when starting a new transaction,
it will use the isolation level set by your database system. You can override the default isolation level as follows,
it will use the default isolation level set by your database system. You can override the default isolation level as follows,
```php
$isolationLevel = \yii\db\Transaction::REPEATABLE_READ;
@@ -429,13 +429,15 @@ try {
try {
$db->createCommand($sql2)->execute();
$innerTransaction->commit();
} catch (Exception $e) {
} catch (\Exception $e) {
$innerTransaction->rollBack();
throw $e;
}
$outerTransaction->commit();
} catch (Exception $e) {
} catch (\Exception $e) {
$outerTransaction->rollBack();
throw $e;
}
```

74
docs/guide/db-migrations.md
View File

@@ -2,9 +2,9 @@ Database Migration
==================
During the course of developing and maintaining a database-driven application, the structure of the database
being used evolves just like the source code does. For example, during the development of an application,
being used evolves just like the source code does. For example, during the development of an application,
a new table may be found necessary; after the application is deployed to production, it may be discovered
that an index should be created to improve the query performance; and so on. Because a database structure change
that an index should be created to improve the query performance; and so on. Because a database structure change
often requires some source code changes, Yii supports the so-called *database migration* feature that allows
you to keep track of database changes in terms of *database migrations* which are version-controlled together
with the source code.
@@ -14,7 +14,7 @@ The following steps show how database migration can be used by a team during dev
1. Tim creates a new migration (e.g. creates a new table, changes a column definition, etc.).
2. Tim commits the new migration into the source control system (e.g. Git, Mercurial).
3. Doug updates his repository from the source control system and receives the new migration.
4. Doug applies the migration to his local development database, thereby synchronizing his database
4. Doug applies the migration to his local development database, thereby synchronizing his database
to reflect the changes that Tim has made.
And the following steps show how to deploy a new release with database migrations to production:
@@ -47,7 +47,7 @@ To create a new migration, run the following command:
yii migrate/create <name>
```
The required `name` argument gives a brief description about the new migration. For example, if
The required `name` argument gives a brief description about the new migration. For example, if
the migration is about creating a new table named *news*, you may use the name `create_news_table`
and run the following command:
@@ -65,20 +65,32 @@ a migration class `m150101_185401_create_news_table` with the skeleton code:
```php
<?php
use yii\db\Schema;
use yii\db\Migration;
class m150101_185401_create_news_table extends Migration
{
public function up()
{
}
public function down()
{
echo "m101129_185401_create_news_table cannot be reverted.\n";
return false;
}
/*
// Use safeUp/safeDown to run migration code within a transaction
public function safeUp()
{
}
public function safeDown()
{
}
*/
}
```
@@ -91,7 +103,7 @@ class name is automatically generated in the format of `m<YYMMDD_HHMMSS>_<Name>`
In the migration class, you are expected to write code in the `up()` method that makes changes to the database structure.
You may also want to write code in the `down()` method to revert the changes made by `up()`. The `up()` method is invoked
when you upgrade the database with this migration, while the `down()` method is invoked when you downgrade the database.
The following code shows how you may implement the migration class to create a `news` table:
The following code shows how you may implement the migration class to create a `news` table:
```php
<?php
@@ -114,17 +126,16 @@ class m150101_185401_create_news_table extends Migration
{
$this->dropTable('news');
}
}
```
> Info: Not all migrations are reversible. For example, if the `up()` method deletes a row of a table, you may
not be able to recover this row in the `down()` method. Sometimes, you may be just too lazy to implement
not be able to recover this row in the `down()` method. Sometimes, you may be just too lazy to implement
the `down()`, because it is not very common to revert database migrations. In this case, you should return
`false` in the `down()` method to indicate that the migration is not reversible.
The base migration class [[yii\db\Migration]] exposes a database connection via the [[yii\db\Migration::db|db]]
property. You can use it to manipulate the database schema using the methods as described in
property. You can use it to manipulate the database schema using the methods as described in
[Working with Database Schema](db-dao.md#working-with-database-schema-).
Rather than using physical types, when creating a table or column you should use *abstract types*
@@ -138,16 +149,15 @@ into `int(11) NOT NULL AUTO_INCREMENT PRIMARY KEY`, while `TYPE_STRING` becomes
You can append additional constraints when using abstract types. In the above example, ` NOT NULL` is appended
to `Schema::TYPE_STRING` to specify that the column cannot be null.
> Info: The mapping between abstract types and physical types is specified by
> Info: The mapping between abstract types and physical types is specified by
the [[yii\db\QueryBuilder::$typeMap|$typeMap]] property in each concrete `QueryBuilder` class.
Since version 2.0.6 schema builder which provides more convenient way defining column schema was introduced so migration above
could be written like the following:
```php
<?php
use yii\db\Schema;
use yii\db\Migration;
class m150101_185401_create_news_table extends Migration
@@ -165,7 +175,6 @@ class m150101_185401_create_news_table extends Migration
{
$this->dropTable('news');
}
}
```
@@ -175,18 +184,18 @@ A list of all available methods for defining the column types is available in th
### Transactional Migrations <span id="transactional-migrations"></span>
While performing complex DB migrations, it is important to ensure each migration to either succeed or fail as a whole
so that the database can maintain integrity and consistency. To achieve this goal, it is recommended that you
so that the database can maintain integrity and consistency. To achieve this goal, it is recommended that you
enclose the DB operations of each migration in a [transaction](db-dao.md#performing-transactions-).
An even easier way of implementing transactional migrations is to put migration code in the `safeUp()` and `safeDown()`
An even easier way of implementing transactional migrations is to put migration code in the `safeUp()` and `safeDown()`
methods. These two methods differ from `up()` and `down()` in that they are enclosed implicitly in a transaction.
As a result, if any operation in these methods fails, all prior operations will be rolled back automatically.
In the following example, besides creating the `news` table we also insert an initial row into this table.
```php
<?php
use yii\db\Schema;
use yii\db\Migration;
class m150101_185401_create_news_table extends Migration
@@ -198,7 +207,7 @@ class m150101_185401_create_news_table extends Migration
'title' => $this->string()->notNull(),
'content' => $this->text(),
]);
$this->insert('news', [
'title' => 'test 1',
'content' => 'content 1',
@@ -213,7 +222,7 @@ class m150101_185401_create_news_table extends Migration
}
```
Note that usually when you perform multiple DB operations in `safeUp()`, you should reverse their execution order
Note that usually when you perform multiple DB operations in `safeUp()`, you should reverse their execution order
in `safeDown()`. In the above example we first create the table and then insert a row in `safeUp()`; while
in `safeDown()` we first delete the row and then drop the table.
@@ -225,12 +234,12 @@ in `safeDown()` we first delete the row and then drop the table.
### Database Accessing Methods <span id="db-accessing-methods"></span>
The base migration class [[yii\db\Migration]] provides a set of methods to let you access and manipulate databases.
You may find these methods are named similarly as the [DAO methods](db-dao.md) provided by the [[yii\db\Command]] class.
For example, the [[yii\db\Migration::createTable()]] method allows you to create a new table,
just like [[yii\db\Command::createTable()]] does.
You may find these methods are named similarly as the [DAO methods](db-dao.md) provided by the [[yii\db\Command]] class.
For example, the [[yii\db\Migration::createTable()]] method allows you to create a new table,
just like [[yii\db\Command::createTable()]] does.
The benefit of using the methods provided by [[yii\db\Migration]] is that you do not need to explicitly
create [[yii\db\Command]] instances and the execution of each method will automatically display useful messages
The benefit of using the methods provided by [[yii\db\Migration]] is that you do not need to explicitly
create [[yii\db\Command]] instances and the execution of each method will automatically display useful messages
telling you what database operations are done and how long they take.
Below is the list of all these database accessing methods:
@@ -276,18 +285,18 @@ yii migrate
```
This command will list all migrations that have not been applied so far. If you confirm that you want to apply
these migrations, it will run the `up()` or `safeUp()` method in every new migration class, one after another,
these migrations, it will run the `up()` or `safeUp()` method in every new migration class, one after another,
in the order of their timestamp values. If any of the migrations fails, the command will quit without applying
the rest of the migrations.
For each migration that has been successfully applied, the command will insert a row into a database table named
For each migration that has been successfully applied, the command will insert a row into a database table named
`migration` to record the successful application of the migration. This will allow the migration tool to identify
which migrations have been applied and which have not.
> Info: The migration tool will automatically create the `migration` table in the database specified by
the [[yii\console\controllers\MigrateController::db|db]] option of the command. By default, the database
is specified by the `db` [application component](structure-application-components.md).
Sometimes, you may only want to apply one or a few new migrations, instead of all available migrations.
You can do so by specifying the number of migrations that you want to apply when running the command.
For example, the following command will try to apply the next three available migrations:
@@ -331,7 +340,7 @@ Redoing migrations means first reverting the specified migrations and then apply
as follows:
```
yii migrate/redo # redo the last applied migration
yii migrate/redo # redo the last applied migration
yii migrate/redo 3 # redo the last 3 applied migrations
```
@@ -380,12 +389,12 @@ There are several ways to customize the migration command.
The migration command comes with a few command-line options that can be used to customize its behaviors:
* `interactive`: boolean (defaults to true), specifies whether to perform migrations in an interactive mode.
* `interactive`: boolean (defaults to true), specifies whether to perform migrations in an interactive mode.
When this is true, the user will be prompted before the command performs certain actions.
You may want to set this to false if the command is being used in a background process.
* `migrationPath`: string (defaults to `@app/migrations`), specifies the directory storing all migration
class files. This can be specified as either a directory path or a path [alias](concept-aliases.md).
* `migrationPath`: string (defaults to `@app/migrations`), specifies the directory storing all migration
class files. This can be specified as either a directory path or a path [alias](concept-aliases.md).
Note that the directory must exist, or the command may trigger an error.
* `migrationTable`: string (defaults to `migration`), specifies the name of the database table for storing
@@ -449,7 +458,8 @@ database. To achieve this goal, when implementing a migration class you should e
ID that the migration would use, like the following:
```php
use yii\db\Schema;
<?php
use yii\db\Migration;
class m150101_185401_create_news_table extends Migration

5
docs/guide/output-data-widgets.md
View File

@@ -603,3 +603,8 @@ echo GridView::widget([
> Note: This section is under development.
TBD
Further reading
---------------
- [Rendering Data in Yii 2 with GridView and ListView](http://www.sitepoint.com/rendering-data-in-yii-2-with-gridview-and-listview/) by Arno Slatius.

6
docs/guide/output-formatting.md
View File

@@ -40,6 +40,12 @@ echo Yii::$app->formatter->format('2014-01-01', 'date');
echo Yii::$app->formatter->format(0.125, ['percent', 2]);
```
> Note: The formatter component is designed to format values to be displayed for the end user. If you want
> to convert user input into machine readable format, or just format a date in a machine readable format,
> the formatter is not the right tool for that.
> To convert user input for date and number values you may use [[yii\validators\DateValidator]] and [[yii\validators\NumberValidator]]
> respectively. For simple conversion between machine readable date and time formats,
> the PHP [date()](http://php.net/manual/en/function.date.php)-function is enough.
## Configuring Formatter <span id="configuring-formatter"></span>

2
docs/guide/rest-controllers.md
View File

@@ -22,7 +22,7 @@ will be described in detail in the next few sections:
[[yii\rest\ActiveController]] in addition provides the following features:
* A set of commonly needed actions: `index`, `view`, `create`, `update`, `delete`, `options`;
* User authorization in regarding to the requested action and resource.
* User authorization in regard to the requested action and resource.
## Creating Controller Classes <span id="creating-controller"></span>

2
docs/guide/rest-quick-start.md
View File

@@ -185,7 +185,7 @@ For example, the URL `http://localhost/users?fields=id,email` will only return t
> Info: You may have noticed that the result of `http://localhost/users` includes some sensitive fields,
> such as `password_hash`, `auth_key`. You certainly do not want these to appear in your API result.
> You can and should filter out these fields as described in the [Response Formatting](rest-response-formatting.md) section.
> You can and should filter out these fields as described in the [Resources](rest-resources.md) section.
## Summary <span id="summary"></span>

17
docs/guide/structure-applications.md
View File

@@ -138,15 +138,16 @@ For example:
```
> Info: If a module ID is the same as an application component ID, the application component will be used during
the bootstrapping process. If you want to use the module instead, you may specify it using an anonymous function
like the following:
> the bootstrapping process. If you want to use the module instead, you may specify it using an anonymous function
> like the following:
>
> ```php
[
function () {
return Yii::$app->getModule('user');
},
]
```
> [
> function () {
> return Yii::$app->getModule('user');
> },
> ]
> ```
During the bootstrapping process, each component will be instantiated. If the component class

2
docs/guide/test-acceptance.md
View File

@@ -3,7 +3,7 @@ Acceptance Tests
> Note: This section is under development.
- http://codeception.com/docs/04-AcceptanceTests
- [Codeception Acceptance Tests](http://codeception.com/docs/03-AcceptanceTests)
Running basic and advanced template acceptance tests
----------------------------------------------------

2
docs/guide/test-fixtures.md
View File

@@ -108,7 +108,7 @@ In the above, we have shown how to define a fixture about a DB table. To define
Using Fixtures
--------------
If you are using [CodeCeption](http://codeception.com/) to test your code, you should consider using
If you are using [Codeception](http://codeception.com/) to test your code, you should consider using
the `yii2-codeception` extension which has built-in support for loading and accessing fixtures.
If you are using other testing frameworks, you may use [[yii\test\FixtureTrait]] in your test cases
to achieve the same goal.

4
docs/guide/test-functional.md
View File

@@ -3,9 +3,9 @@ Functional Tests
> Note: This section is under development.
- http://codeception.com/docs/05-FunctionalTests
- [Codeception Functional Tests](http://codeception.com/docs/04-FunctionalTests)
Running basic and advanced template functional tests
----------------------------------------------------
Please refer to instructions provided in `apps/advanced/tests/README.md` and `apps/basic/tests/README.md`.
Please refer to instructions provided in `apps/advanced/tests/README.md` and `apps/basic/tests/README.md`.