同步英文文档，已对存在中文文档进行同步

Author: mpandar

billing.md

@@ -10,12 +10,13 @@
 - [Resuming A Subscription](#resuming-a-subscription)
 - [Checking Subscription Status](#checking-subscription-status)
 - [Handling Failed Payments](#handling-failed-payments)
+- [Handling Other Stripe Webhooks](#handling-other-stripe-webhooks)
 - [Invoices](#invoices)
 
 <a name="introduction"></a>
 ## Introduction
 
-Laravel Cashier provides an expressive, fluent interface to [Stripe's](https://stripe.com) subscription billing services. It handles almost all of the boilerplate subscription billing code you are dreading writing. In addition to basic subscription management, Cashier can handle coupons, swapping subscription, subscription "quantites", cancellation grace periods, and even generate invoice PDFs.
+Laravel Cashier provides an expressive, fluent interface to [Stripe's](https://stripe.com) subscription billing services. It handles almost all of the boilerplate subscription billing code you are dreading writing. In addition to basic subscription management, Cashier can handle coupons, swapping subscription, subscription "quantities", cancellation grace periods, and even generate invoice PDFs.
 
 <a name="configuration"></a>
 ## Configuration
@@ -32,7 +33,7 @@ Next, register the `Laravel\Cashier\CashierServiceProvider` in your `app` config
 
 #### Migration
 
-Before using Cashier, we'll need to add several columns to your database. Don't worry, you can use the `cashier:table` Artisan command to create a migration to add the necessary column. Once the migration has been created, simply run the `migrate` command.
+Before using Cashier, we'll need to add several columns to your database. Don't worry, you can use the `cashier:table` Artisan command to create a migration to add the necessary column. For example, to add the column to the users table use `php artisan cashier:table users`. Once the migration has been created, simply run the `migrate` command.
 
 #### Model Setup
 
@@ -70,14 +71,24 @@ If you would like to apply a coupon when creating the subscription, you may use
 	     ->withCoupon('code')
 	     ->create($creditCardToken);
 
-The `subscription` method will automatically create the Stripe subscription, as well as update your database with Stripe customer ID and other relevant billing information.
+The `subscription` method will automatically create the Stripe subscription, as well as update your database with Stripe customer ID and other relevant billing information. If your plan has a trial configured in Stripe, the trial end date will also automatically be set on the user record.
 
-If your plan has a trial period, make sure to set the trial end date on your model after subscribing:
+If your plan has a trial period that is **not** configured in Stripe, you must set the trial end date manually after subscribing:
 
 	$user->trial_ends_at = Carbon::now()->addDays(14);
 
 	$user->save();
 
+### Specifying Additional User Details
+
+If you would like to specify additional customer details, you may do so by passing them as second argument to the `create` method:
+
+	$user->subscription('monthly')->create($creditCardToken, [
+		'email' => $email, 'description' => 'Our First Customer'
+	]);
+
+To learn more about the additional fields supported by Stripe, check out Stripe's [documentation on customer creation](https://stripe.com/docs/api#create_customer).
+
 <a name="no-card-up-front"></a>
 ## No Card Up Front
 
@@ -110,12 +121,12 @@ Sometimes subscriptions are affected by "quantity". For example, your applicatio
 	$user->subscription()->increment();
 
 	// Add five to the subscription's current quantity...
-	$user->subscription()->increment(5)
+	$user->subscription()->increment(5);
 
 	$user->subscription->decrement();
 
 	// Subtract five to the subscription's current quantity...
-	$user->subscription()->decrement(5)
+	$user->subscription()->decrement(5);
 
 <a name="cancelling-a-subscription"></a>
 ## Cancelling A Subscription
@@ -183,6 +194,13 @@ The `everSubscribed` method may be used to determine if the user has ever subscr
 		//
 	}
 
+The `onPlan` method may be used to determine if the user is subscribed to a given plan based on its ID:
+
+	if ($user->onPlan('monthly'))
+	{
+		//
+	}
+
 <a name="handling-failed-payments"></a>
 ## Handling Failed Payments
 
@@ -192,16 +210,16 @@ What if a customer's credit card expires? No worries - Cashier includes a Webhoo
 
 That's it! Failed payments will be captured and handled by the controller. The controller will cancel the customer's subscription after three failed payment attempts. The `stripe/webhook` URI in this example is just for example. You will need to configure the URI in your Stripe settings.
 
-If you have additional Stripe webhook events you would like to handle, simply extend the Webhook controller:
+<a name="handling-other-stripe-webhooks"></a>
+## Handling Other Stripe Webhooks
+
+If you have additional Stripe webhook events you would like to handle, simply extend the Webhook controller. Your method names should correspond to Cashier's expected convention, specifically, methods should be prefixed with `handle` and the name of the Stripe webhook you wish to handle. For example, if you wish to handle the `invoice.payment_succeeded` webhook, you should add a `handleInvoicePaymentSucceeded` method to the controller.
 
 	class WebhookController extends Laravel\Cashier\WebhookController {
 
-		public function handleWebhook()
+		public function handleInvoicePaymentSucceeded($payload)
 		{
-			// Handle other events...
-
-			// Fallback to failed payment check...
-			return parent::handleWebhook();
+			// Handle The Event
 		}
 
 	}

cn/releases.md

@@ -38,7 +38,7 @@ Laravel Cashier是一个简单的、富于表现力的库，它用来管理条
 
 Artisan的“queue:work”命令现在支持“--daemon”选项，它用来启动一个“守护进程模式”的工人，这个模式使得工人在不需要重启框架的情况下继续工作。这会显著的减少CPU的使用率，其代价只是使得应用程序的部署过程稍显复杂。
 
-在队列文档（/docs/queue#daemon-queue-workers）里能找到更多的队列工人相关的信息。
+在队列文档（/docs/queues#daemon-queue-workers）里能找到更多的队列工人相关的信息。
 
 ### 邮件API驱动
 

cn/upgrade.md

@@ -20,6 +20,8 @@ Laravel 4.2需要PHP 5.4.0或更高版本。
 
 这个设置可以用来控制Laravel加密功能使用默认密钥。
 
+> **Note:** In Laravel 4.2, the default cipher is `MCRYPT_RIJNDAEL_128` (AES), which is considered to be the most secure cipher. Changing the cipher back to `MCRYPT_RIJNDAEL_256` is required to decrypt cookies/values that were encrypted in Laravel <= 4.1
+
 ### 软删除模型现在的使用特性
 
 如果你正在使用软删除模型，“softDeletes”属性已经被删除了。现在你应该使用“SoftDeletingTrait”属性，像下面这样：
@@ -40,6 +42,8 @@ Laravel 4.2需要PHP 5.4.0或更高版本。
 
 所有软删除操作的API保持不变。
 
+> **Note:** The `SoftDeletingTrait` can not be applied on a base model. It must be used on an actual model class.
+
 ### 重命名的视图/分页环境
 
 如果你直接的引用了“Illuminate\View\Environment”类或“Illuminate\Pagination\Environment”类，升级你的代码，用“Illuminate\View\Factory”和“Illuminate\Pagination\Factory”来替代。原来的两个类已经被重命名,以更好地反映其功能。
@@ -50,6 +54,12 @@ Laravel 4.2需要PHP 5.4.0或更高版本。
 
 	abstract public function getPageLinkWrapper($url, $page, $rel = null);
 
+### Iron.Io Queue Encryption
+
+If you are using the Iron.io queue driver, you will need to add a new `encrypt` option to your queue configuration file:
+
+    'encrypt' => true
+
 <a name="upgrade-4.1.29"></a>
 ## 从小于等于4.1.x升级到4.1.29 
 

commands.md

@@ -129,6 +129,15 @@ If your command is registered in the application [IoC container](/docs/ioc), you
 
 	Artisan::resolve('binding.name');
 
+#### Registering Commands In A Service Provider
+
+If you need to register commands from within a service provider, you should call the `commands` method from the provider's `boot` method, passing the [IoC container](/docs/ioc) binding for the command:
+
+	public function boot()
+	{
+		$this->commands('command.binding');
+	}
+
 <a name="calling-other-commands"></a>
 ## Calling Other Commands
 

contributing.md

@@ -1,3 +1,3 @@
 # Contribution Guidelines
 
-If you are submitting documentation for the **current stable release**, submit it to the corresponding branch. For example, documentation for Laravel 4.1 would be submitted to the `4.1` branch. Documentation intended for the next release of Laravel should be submitted to the `master` branch.
+If you are submitting documentation for the **current stable release**, submit it to the corresponding branch. For example, documentation for Laravel 4.2 would be submitted to the `4.2` branch. Documentation intended for the next release of Laravel should be submitted to the `master` branch.

controllers.md

@@ -140,6 +140,11 @@ The `controller` method accepts two arguments. The first is the base URI the con
 		{
 			//
 		}
+		
+		public function anyLogin()
+		{
+			//
+		}
 
 	}
 
@@ -195,6 +200,23 @@ By default, all resource controller actions have a route name; however, you can
 	Route::resource('photo', 'PhotoController',
 					array('names' => array('create' => 'photo.build')));
 
+#### Handling Nested Resource Controllers
+
+To "nest" resource controllers, use "dot" notation in your route declaration:
+
+	Route::resource('photos.comments', 'PhotoCommentController');
+
+This route will register a "nested" resource that may be accessed with URLs like the following: `photos/{photoResource}/comments/{commentResource}`.
+
+	class PhotoCommentController extends BaseController {
+
+		public function show($photoId, $commentId)
+		{
+			//
+		}
+
+	}
+
 #### Adding Additional Routes To Resource Controllers
 
 If it becomes necessary for you to add additional routes to a resource controller beyond the default resource routes, you should define those routes before your call to `Route::resource`:

eloquent.md

@@ -7,6 +7,7 @@
 - [Soft Deleting](#soft-deleting)
 - [Timestamps](#timestamps)
 - [Query Scopes](#query-scopes)
+- [Global Scopes](#global-scopes)
 - [Relationships](#relationships)
 - [Querying Relations](#querying-relations)
 - [Eager Loading](#eager-loading)
@@ -373,6 +374,70 @@ Then pass the parameter into the scope call:
 
 	$users = User::ofType('member')->get();
 
+<a name="global-scopes"></a>
+## Global Scopes
+
+Sometimes you may wish to define a scope that applies to all queries performed on a model. In essence, this is how Eloquent's own "soft delete" feature works. Global scopes are defined using a combination of PHP traits and an implementation of `Illuminate\Database\Eloquent\ScopeInterface`.
+
+First, let's define a trait. For this example, we'll use the `SoftDeletingTrait` that ships with Laravel:
+
+	trait SoftDeletingTrait {
+
+		/**
+		 * Boot the soft deleting trait for a model.
+		 *
+		 * @return void
+		 */
+		public static function bootSoftDeletingTrait()
+		{
+			static::addGlobalScope(new SoftDeletingScope);
+		}
+
+	}
+
+If an Eloquent model uses a trait that has a method matching the `bootNameOfTrait` naming convention, that trait method will be called when the Eloquent model is booted, giving you an opportunity to register a global scope, or do anything else you want. A scope must implement `ScopeInterface`, which specifies two methods: `apply` and `remove`.
+
+The `apply` method receives an `Illuminate\Database\Eloquent\Builder` query builder object, and is responsible for adding any additional `where` clauses that the scope wishes to add. The `remove` method also receives a `Builder` object and is responsible for reversing the action taken by `apply`. In other words, `remove` should remove the `where` clause (or any other clause) that was added. So, for our `SoftDeletingScope`, the methods look something like this:
+
+	/**
+	 * Apply the scope to a given Eloquent query builder.
+	 *
+	 * @param  \Illuminate\Database\Eloquent\Builder  $builder
+	 * @return void
+	 */
+	public function apply(Builder $builder)
+	{
+		$model = $builder->getModel();
+
+		$builder->whereNull($model->getQualifiedDeletedAtColumn());
+	}
+
+	/**
+	 * Remove the scope from the given Eloquent query builder.
+	 *
+	 * @param  \Illuminate\Database\Eloquent\Builder  $builder
+	 * @return void
+	 */
+	public function remove(Builder $builder)
+	{
+		$column = $builder->getModel()->getQualifiedDeletedAtColumn();
+
+		$query = $builder->getQuery();
+
+		foreach ((array) $query->wheres as $key => $where)
+		{
+			// If the where clause is a soft delete date constraint, we will remove it from
+			// the query and reset the keys on the wheres. This allows this developer to
+			// include deleted model in a relationship result set that is lazy loaded.
+			if ($this->isSoftDeleteConstraint($where, $column))
+			{
+				unset($query->wheres[$key]);
+
+				$query->wheres = array_values($query->wheres);
+			}
+		}
+	}
+
 <a name="relationships"></a>
 ## Relationships
 
@@ -835,6 +900,18 @@ You will often need to insert new related models. For example, you may wish to i
 
 In this example, the `post_id` field will automatically be set on the inserted comment.
 
+If you need to save multiple related models:
+
+	$comments = array(
+		new Comment(array('message' => 'A new comment.')),
+		new Comment(array('message' => 'Another comment.')),
+		new Comment(array('message' => 'The latest comment.'))
+	);
+
+	$post = Post::find(1);
+
+	$post->comments()->saveMany($comments);
+
 ### Associating Models (Belongs To)
 
 When updating a `belongsTo` relationship, you may use the `associate` method. This method will set the foreign key on the child model:
@@ -1069,7 +1146,7 @@ Mutators are declared in a similar fashion:
 <a name="date-mutators"></a>
 ## Date Mutators
 
-By default, Eloquent will convert the `created_at`, `updated_at`, and `deleted_at` columns to instances of [Carbon](https://github.com/briannesbitt/Carbon), which provides an assortment of helpful methods, and extends the native PHP `DateTime` class.
+By default, Eloquent will convert the `created_at` and `updated_at` columns to instances of [Carbon](https://github.com/briannesbitt/Carbon), which provides an assortment of helpful methods, and extends the native PHP `DateTime` class.
 
 You may customize which fields are automatically mutated, and even completely disable this mutation, by overriding the `getDates` method of the model:
 

events.md

@@ -110,14 +110,7 @@ Using the `queue` and `flush` methods, you may "queue" an event for firing, but
 
 	Event::queue('foo', array($user));
 
-#### Registering An Event Flusher
-
-	Event::flusher('foo', function($user)
-	{
-		//
-	});
-
-Finally, you may run the "flusher" and flush all queued events using the `flush` method:
+You may run the "flusher" and flush all queued events using the `flush` method:
 
 	Event::flush('foo');
 

extending.md

@@ -85,7 +85,7 @@ Extending Laravel with a custom session driver is just as easy as extending the
 
 ### Where To Extend The Session
 
-Session extensions need to be registered differently than other extensions like Cache and Auth. Since sessions are started very early in the request-lifecycle, registering the extensions in a `start` file will happen be too late. Instead, a [service provider](/docs/ioc#service-providers) will be needed. You should place your session extension code in the `register` method of your service provider, and the provider should be placed **below** the default `Illuminate\Session\SessionServiceProvider` in the `providers` configuration array.
+Session extensions need to be registered differently than other extensions like Cache and Auth. Since sessions are started very early in the request-lifecycle, registering the extensions in a `start` file will happen too late. Instead, a [service provider](/docs/ioc#service-providers) will be needed. You should place your session extension code in the `register` method of your service provider, and the provider should be placed **below** the default `Illuminate\Session\SessionServiceProvider` in the `providers` configuration array.
 
 ### Writing The Session Extension
 
@@ -139,13 +139,19 @@ Let's take a look at the `UserProviderInterface`:
 	interface UserProviderInterface {
 
 		public function retrieveById($identifier);
+		public function retrieveByToken($identifier, $token);
+		public function updateRememberToken(UserInterface $user, $token);
 		public function retrieveByCredentials(array $credentials);
 		public function validateCredentials(UserInterface $user, array $credentials);
 
 	}
 
 The `retrieveById` function typically receives a numeric key representing the user, such as an auto-incrementing ID from a MySQL database. The `UserInterface` implementation matching the ID should be retrieved and returned by the method.
 
+The `retrieveByToken` function retrieves a user by their unique `$identifier` and "remember me" `$token`, stored in a field `remember_token`. As with with previous method, the `UserInterface` implementation should be returned.
+
+The `updateRememberToken` method updates the `$user` field `remember_token` with the new `$token`. The new token can be either a fresh token, assigned on successfull "remember me" login attempt, or a null when user is logged out.
+
 The `retrieveByCredentials` method receives the array of credentials passed to the `Auth::attempt` method when attempting to sign into an application. The method should then "query" the underlying persistent storage for the user matching those credentials. Typically, this method will run a query with a "where" condition on `$credentials['username']`. **This method should not attempt to do any password validation or authentication.**
 
 The `validateCredentials` method should compare the given `$user` with the `$credentials` to authenticate the user. For example, this method might compare the `$user->getAuthPassword()` string to a `Hash::make` of `$credentials['password']`.

mail.md

@@ -28,7 +28,7 @@ To use the Mailgun driver, set the `driver` option to `mailgun` in your `app/con
 
 #### Mandrill Driver
 
-To use the Mailgun driver, set the `driver` option to `mandrill` in your `app/config/mail.php` configuration file. Next, create an `app/config/services.php` configuration file if one does not already exist for your project. Verify that it contains the following options:
+To use the Mandrill driver, set the `driver` option to `mandrill` in your `app/config/mail.php` configuration file. Next, create an `app/config/services.php` configuration file if one does not already exist for your project. Verify that it contains the following options:
 
 	'mandrill' => array(
 		'secret' => 'your-mandrill-key',

pagination.md

@@ -22,6 +22,8 @@ There are several ways to paginate items. The simplest is by using the `paginate
 
 	$users = DB::table('users')->paginate(15);
 
+> **Note:** Currently, pagination operations that use a `groupBy` statement cannot be executed efficiently by Laravel. If you need to use a `groupBy` with a paginated result set, it is recommended that you query the database manually and use `Paginator::make`.
+
 #### Paginating An Eloquent Model
 
 You may also paginate [Eloquent](/docs/eloquent) models:
@@ -101,7 +103,7 @@ This method call will generate URLs that look something like this:
 <a name="converting-to-json"></a>
 ## Converting To JSON
 
-The `Paginator` class implements the `Illuminate\Support\Contracts\JsonableInterface` contract and exposes the `toJson` method. You can may also convert a `Paginator` instance to JSON by returning it from a route. The JSON'd form of the instance will include some "meta" information such as `total`, `current_page`, `last_page`, `from`, and `to`. The instance's data will be available via the `data` key in the JSON array.
+The `Paginator` class implements the `Illuminate\Support\Contracts\JsonableInterface` contract and exposes the `toJson` method. You may also convert a `Paginator` instance to JSON by returning it from a route. The JSON'd form of the instance will include some "meta" information such as `total`, `current_page`, `last_page`, `from`, and `to`. The instance's data will be available via the `data` key in the JSON array.
 
 <a name="custom-presenters"></a>
 ## Custom Presenters