Merge pull request #29 from mpandar/master

同步了部分英文文档

Author: 王赛

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/facades.md

@@ -114,6 +114,7 @@ Facades（一种设计模式，通常翻译为外观模式）提供了一个"sta
 
 下面你会找到所有的facade以及其包含的类。这是一个非常有用的工具，可以根据给定的facade快速定位到API文档。适用于[IoC 绑定](/docs/ioc) 的也同时给出了其key。
 
+
 Facade  |  Class  |  IoC Binding
 ------------- | ------------- | -------------
 App  |  [Illuminate\Foundation\Application](http://laravel.com/api/4.2/Illuminate/Foundation/Application.html)  | `app`
@@ -154,10 +155,9 @@ SSH  |  [Illuminate\Remote\RemoteManager](http://laravel.com/api/4.2/Illuminate/
 SSH (Instance)  |  [Illuminate\Remote\Connection](http://laravel.com/api/4.2/Illuminate/Remote/Connection.html)  |
 URL  |  [Illuminate\Routing\UrlGenerator](http://laravel.com/api/4.2/Illuminate/Routing/UrlGenerator.html)  |  `url`
 Validator  |  [Illuminate\Validation\Factory](http://laravel.com/api/4.2/Illuminate/Validation/Factory.html)  |  `validator`
-Validator (Instance)  |  [Illuminate\Validation\Validator](http://laravel.com/api/4.2/Illuminate/Validation/Validator.html)
+Validator (Instance)  |  [Illuminate\Validation\Validator](http://laravel.com/api/4.2/Illuminate/Validation/Validator.html) |
 View  |  [Illuminate\View\Factory](http://laravel.com/api/4.2/Illuminate/View/Factory.html)  |  `view`
 View (Instance)  |  [Illuminate\View\View](http://laravel.com/api/4.2/Illuminate/View/View.html)  |
 
 
-
 译者：mpandar（马胜盼）

cn/homestead.md

@@ -15,6 +15,8 @@ Laravel Homestead是一个官方的、预封装的Vagrant“箱子”，它提
 
 Homestead能运行在所有的Windows、Mac和Linux上，它包含了Nginx、PHP 5.5、MySQL、Postgres、Redis、Memcached和你开发神奇的Laravel应用程序需要的所有其它软件。
 
+Homestead is currently built and tested using Vagrant 1.6.
+
 <a name="included-software"></a>
 ## 包含的软件
 
@@ -108,7 +110,7 @@ Homestead能运行在所有的Windows、Mac和Linux上，它包含了Nginx、PHP
 
 ### 添加额外站点
 
-一旦你的Homestead环境被分配并运行，你可能想为Laravel应用程序添加额外的Nginx站点。在一个Homestead环境中，你可以按意愿运行尽可能多的Laravel应用程序。有两种方法可以做到这一点。首先，你可以简单的添加站点到“Homestead.yaml”文件里，先对箱子执行“vagrant destroy”命令，然后再执行“vagrant up”命令。
+一旦你的Homestead环境被分配并运行，你可能想为Laravel应用程序添加额外的Nginx站点。在一个Homestead环境中，你可以按意愿运行尽可能多的Laravel应用程序。有两种方法可以做到这一点。首先，你可以简单的添加站点到“Homestead.yaml”文件里，先对箱子执行“vagrant destroy”命令，然后再执行“vagrant provision”命令。
 
 或者，你可以使用Homestead环境里的“serve”脚本。想使用“serve”脚本，先SSH到Homestead环境并运行下面的命令：
 

cn/installation.md

@@ -36,7 +36,7 @@ Composer 安装完成后，下载[最新版Laravel框架](https://github.com/lar
 
 Laravel 框架对系统环境有如下要求：
 
-- PHP >= 5.3.7
+- PHP >= 5.4
 - MCrypt PHP 扩展
 
 从 PHP 5.5 版本开始，针对某些操作系统的安装包需要你自己手工安装 PHP 的 JSON 扩展模块。如果你使用的是 Ubuntu，可以通过,  `apt-get install php5-json` 命令直接安装。

cn/quick.md

@@ -1,11 +1,13 @@
 # Laravel 快速入门
 
 - [安装](#installation)
+- [本地开发环境](#local-development-environment)
 - [路由](#routing)
 - [创建视图](#creating-a-view)
 - [创建迁移](#creating-a-migration)
 - [Eloquent ORM](#eloquent-orm)
 - [显示数据](#displaying-data)
+- [部署应用](#deploying-your-application)
 
 <a name="installation"></a>
 ## 安装
@@ -42,6 +44,20 @@ Typically, you may use a web server such as Apache or Nginx to serve your Larave
 
 After installing the framework, take a glance around the project to familiarize yourself with the directory structure. The `app` directory contains folders such as `views`, `controllers`, and `models`. Most of your application's code will reside somewhere in this directory. You may also wish to explore the `app/config` directory and the configuration options that are available to you.
 
+<a name="local-development-environment"></a>
+## Local Development Environment
+
+In the past, configuring a local PHP development environment on your machine was a headache. Installing the proper version of PHP, required extensions, and other needed components is time consuming and confusing. Instead, consider using [Laravel Homestead](/docs/homestead). Homestead is a simple virtual machine designed for Laravel and [Vagrant](http://vagrantup.com). Since the Homestead Vagrant box is pre-packaged with all of the software you need to build robust PHP applications, you can create a virtualized, isolated development environment in seconds. Here is a list of some of the goodies included with Homestead:
+
+- Nginx
+- PHP 5.5
+- MySQL
+- Redis
+- Memcached
+- Beanstalk
+
+Don't worry, even though "virtualized" sounds complicated, it's painless. VirtualBox and Vagrant, which are Homestead's two dependencies, both include simple, graphical installers for all popular operating systems. Check out the [Homestead documentation](/docs/homestead) to get started.
+
 <a name="routing"></a>
 ## Routing
 
@@ -171,3 +187,10 @@ Now that we have made the `users` available to our view, we can display them lik
 You may be wondering where to find our `echo` statements. When using Blade, you may echo data by surrounding it with double curly braces. It's a cinch. Now, you should be able to hit the `/users` route and see the names of your users displayed in the response.
 
 This is just the beginning. In this tutorial, you've seen the very basics of Laravel, but there are so many more exciting things to learn. Keep reading through the documentation and dig deeper into the powerful features available to you in [Eloquent](/docs/eloquent) and [Blade](/docs/templates). Or, maybe you're more interested in [Queues](/docs/queues) and [Unit Testing](/docs/testing). Then again, maybe you want to flex your architecture muscles with the [IoC Container](/docs/ioc). The choice is yours!
+
+<a name="deploying-your-application"></a>
+## Deploying Your Application
+
+One of Laravel's goals is to make PHP application development enjoyable from download to deploy, and [Laravel Forge](https://forge.laravel.com) provides a simple way to deploy your Laravel applications onto blazing fast servers. Forge can configure and provision servers on DigitalOcean, Linode, Rackspace, and Amazon EC2. Like Homestead, all of the latest goodes are included: Nginx, PHP 5.5, MySQL, Postgres, Redis, Memcached, and more. Forge "Quick Deploy" can even deploy your code for you each time you push changes out to Github or Bitbucket!
+
+On top of that, Forge can help you configure queue workers, SSL, Cron jobs, sub-domains, and more. For more information, visit the [Forge website](https://forge.laravel.com).

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/templates.md

@@ -0,0 +1,181 @@
+# 模板
+
+- [控制器布局](#controller-layouts)
+- [Blade模板](#blade-templating)
+- [Blade模板控制结构](#other-blade-control-structures)
+- [扩展Blade](#extending-blade)
+
+<a name="controller-layouts"></a>
+## 控制器布局
+
+
+在Laravel框架中使用模板的一种方法就是通过控制器布局。通过在控制器中指定`layout`属性，指定的视图就会被创建，并作为默认数据，在actions中返回。
+
+#### 在控制器中定义布局（Layouts）
+
+	class UserController extends BaseController {
+
+		/**
+		 * The layout that should be used for responses.
+		 */
+		protected $layout = 'layouts.master';
+
+		/**
+		 * Show the user profile.
+		 */
+		public function showProfile()
+		{
+			$this->layout->content = View::make('user.profile');
+		}
+
+	}
+
+<a name="blade-templating"></a>
+## Blade模板
+
+Blade是Laravel框架下的一个简单但又强大的模板引擎。 不同于控制器布局，Blade模板引擎由 _模板继承_ 和 _模板片段_ 驱动。所有的Blade模板文件必须使用 `.blade.php` 文件扩展名。
+
+#### 定义一个Blade布局
+
+	<!-- Stored in app/views/layouts/master.blade.php -->
+
+	<html>
+		<body>
+			@section('sidebar')
+				This is the master sidebar.
+			@show
+
+			<div class="container">
+				@yield('content')
+			</div>
+		</body>
+	</html>
+
+#### 使用一个Blade布局
+
+	@extends('layouts.master')
+
+	@section('sidebar')
+		@parent
+
+		<p>This is appended to the master sidebar.</p>
+	@stop
+
+	@section('content')
+		<p>This is my body content.</p>
+	@stop
+
+注意视图中片段只是简单的替换其`extend`的Blade布局中相应片段。通过在模板片段中使用`@parent`指令，布局的内容可以包含一个子视图，这样你就可以在布局片段中添加诸如侧边栏、底部信息等内容。
+
+有时候，有些片段可能不能确定被定义了，你可以使用`@yield`结构给出一个默认值。如下，第二个值即是默认值。
+
+	@yield('section', 'Default Content');
+
+<a name="other-blade-control-structures"></a>
+## 其他 Blade模板 控制结构
+
+#### 输出数据
+
+	Hello, {{{ $name }}}.
+
+	The current UNIX timestamp is {{{ time() }}}.
+
+#### 检测是否存在后输出数据
+
+有时，你可能希望输出一个变量，但又不能确定这个变量是否被设置。直接点，你可能想这么做：
+
+	{{{ isset($name) ? $name : 'Default' }}}
+
+然而，除了写一个三目运算符，Blade有如下简写方法：
+
+	{{{ $name or 'Default' }}}
+
+#### 显示带有大括号的文本
+
+如果你想显示带有大括号的字符串，你可以在文本前放`@`符号，这样会忽略Blade解析行为
+
+	@{{ This will not be processed by Blade }}
+
+当然，用户提供的全部字符串都应该都被转义（主要对html标签，利用htmlentities编码转义）。如果想转义输出，你可以使用三个大括号语法：
+
+	Hello, {{{ $name }}}.
+
+如果不希望数据被转义，可以使用双大括号语法：
+
+	Hello, {{ $name }}.
+
+> **注意：** 一定要小心输出的用户提供的内容。使用三个大括号的语法能够直接输出内容中的HTML标签。
+
+#### If标签
+
+	@if (count($records) === 1)
+		I have one record!
+	@elseif (count($records) > 1)
+		I have multiple records!
+	@else
+		I don't have any records!
+	@endif
+
+	@unless (Auth::check())
+		You are not signed in.
+	@endunless
+
+#### 循环
+
+	@for ($i = 0; $i < 10; $i++)
+		The current value is {{ $i }}
+	@endfor
+
+	@foreach ($users as $user)
+		<p>This is user {{ $user->id }}</p>
+	@endforeach
+
+	@while (true)
+		<p>I'm looping forever.</p>
+	@endwhile
+
+#### 包含子视图
+
+	@include('view.name')
+
+你也可以传递数组数据到被包含的视图
+
+	@include('view.name', array('some'=>'data'))
+
+#### 覆盖片段
+
+默认的，片段是附加在先前存在的片段上，如果想覆盖一个片段的全部，可以使用`overwrite`标签
+
+	@extends('list.item.container')
+
+	@section('list.item.content')
+		<p>This is an item of type {{ $item->type }}</p>
+	@overwrite
+
+#### 输出多语言
+
+	@lang('language.line')
+
+	@choice('language.line', 1);
+
+#### 注释
+
+	{{-- This comment will not be in the rendered HTML --}}
+
+<a name="extending-blade"></a>
+## 扩展Blade
+
+Blade允许用户定义自己的控制结构。当一个Blade文件被编译后，会调用用户自定义的扩展，用来处理视图内容，从简单的`str_replace`操作，到很复杂的表达式，总之，你可以做任何事情。
+
+Blade的编译器附带了帮助函数`createMatcher`和`createPlainMatcher`，这两个函数可以生成自定义指令。
+
+`createPlainMatcher`函数主要用于没有参数传递的指令，类似`@endif`和`@stop`，而`createMatcher`则用于那些有参数传递的指令。
+
+下面的例子创建`@datetime($var)`指令，它只是简单的对`$var`调用`->format()`方法：
+
+	Blade::extend(function($view, $compiler)
+	{
+		$pattern = $compiler->createMatcher('datetime');
+
+		return preg_replace($pattern, '$1<?php echo $2->format('m/d/Y H:i'); ?>', $view);
+	});