README

Laravel (5.1+) 的 Twilio 端口

安装

将包添加到你的 composer.json 文件中，并运行 composer update

{
  "require": {
  	...
    "j42/laravel-twilio": "dev-master"
  }
}

然后将服务提供者和外观添加到 config/app.php

	'J42\LaravelTwilio\LaravelTwilioServiceProvider',

...

	'Twilio'		  => 'J42\LaravelTwilio\LaravelTwilioFacade'

配置

通过运行 php artisan config:publish j42/laravel-twilio 生成包配置文件，并调整相关字段

	return [

		'key'	=> 'YOURAPIKEY',						// Public key
		'token'	=> 'YOURSECRETTOKEN',					// Private key
		'from'	=> '9999999999',						// Default From Address 
		'twiml'	=> 'https://yourdomain.com/base_path',	// TWIML Hosted Base Path

		// Default Features When Requesting Numbers (override via `numbersNear` method)
		'features'	=> [
	    	'SmsEnabled'	=> true,
	    	'VoiceEnabled'	=> false,
	    	'MmsEnabled'	=> false,
	    ]

	];

电话验证

由于电话验证是一个非常常见的用例，我创建了一个简单的流程来自动化这个过程。

此包自动安装以下路由（允许 GET 或 POST 请求）

/twilio/verify

请求令牌

向 /twilio/verify 发起 HTTP GET 或 POST 请求，并带有以下参数

• phone 电话号码（解析为字符串）
• method ('sms' 或 'call')

数字令牌设置在 cookie 中，有效期为 2 分钟。

返回

	// Get token (method can be either 'sms' or 'call')
	file_get_contents('<yourdomain>/twilio/verify?phone=0000000000&method=sms');
	
	/* 
		{
			status: 'success',
			data: {
				phone: '0000000000',	// User's phone
				status: 'queued'		// Twilio response status
			}
		}
	*/

验证令牌

向 /twilio/verify/ 发起 HTTP GET 或 POST 请求，并带有以下参数

• code 用户输入的数字代码

如果验证正确，将返回完整的对象

	// Verify token
	file_get_contents('/twilio/verify?code=00000');
	
	/*
		{
			status: 'success',
			data: {
				code: '00000',			// Initial Generated Code
				number: '0000000000',	// User's phone
				valid: true
			}
		}
	*/

验证后（成功）

一旦确认了代码，验证数据将通过 Cookie 可用，有效期为 5 分钟。对 /twilio/verify 的 HTTP 请求（无论是否带参数）将返回

	file_get_contents('/twilio/verify');
	
	/*
		{
			status: 'success',
			data: {
				code: '00000',			// Initial Generated Code
				number: '0000000000',	// User's phone
				valid: true
			}
		}
	*/

高级用法

有时你可能需要在你的控制器中处理额外的逻辑。通过包含一个方便的接口，这变得很容易。

定义路由覆盖（根据你的喜好选择，或两者都选择）

	\Route::any('twilio/verify', [
		'uses'	=> 'YourController@verify'
	]);

	\Route::any('api/twilio/verify', [
		'uses'	=> 'YourController@verify'
	]);

创建你的控制器，扩展 J42\LaravelTwilio\TwilioVerify

	use J42\LaravelTwilio\TwilioVerify;

	class TwilioController extends TwilioVerify {

		// Verify Phone
		public function verify() {
			
			// Your pre-verification logic

			// Magic
			// You can include an optional message instead of the default, if you want.
			// If you do this PLEASE make sure you include `{code}` somewhere so that the user sees the verification code
			// Without this token present in a custom message, they won't receive their confirmation token.
			$response = parent::verify($message);

			// Your post-verification logic
			// $this->phone === Cookie::get('twilio::phone') === json_decode($response)['data']

			return $response;

		}

	}

根据需要定义你的功能，确保调用 parent::verify(); 来处理默认事件。如果你需要直接访问 cookie，可以通过以下方式： Cookie::get('twilio::phone')。

SMS

如何与 Twilio 的基于 REST 的 SMS 方法交互。

####发送 SMS

Twilio::sms([
	// From (optional -- if unsupplied, will be taken from default Config::get('twilio::config.from'))
	'from'		=> '<your twilio #>'
	// Array of recipients
	'to'		=> ['19999999999'],
	// Text Message
	'message'	=> 'Contents of the text message go here'
]);

呼叫

如何与 Twilio 的基于 REST 的呼叫发起方法交互。

####通过 TWIML 端点发起呼叫

Twilio::call([
	// From (optional -- if unsupplied, will be taken from default Config::get('laravel-twilio::from'))
	'from'		=> '<your twilio #>'
	// Array of recipients
	'to'		=> ['19999999999'],
	// Relative path to twiml document/endpoint (combined with Config::get('laravel-twilio::twiml') to form an absolute URL endpoint)
	// You could also specify an abslute URL (http:// or https:// which would not be modified)
	'twiml'		=> 'twilio/verify/twiml'
]);

// Response Statuses:
// QUEUED, RINGING, IN-PROGRESS, COMPLETED, FAILED, BUSY or NO_ANSWER.

请求本地号码

你也可以通过 SDK 客户端中可用的任何属性请求本地号码（用于 'from' 字段）。 目前仅限美国。如果你想适应这个（欢迎 fork），你可以通过将 geoList 参数抽象到配置文件中轻松地做到这一点。

numbersNear 接受 3 个参数

• conditions 数组，条件来自 Twilio 文档
• features 数组，所需功能（SmsEnabled、VoiceEnabled、MmsEnabled）或 null（使用配置中的默认值）
• buy int，自动购买并配置到账户的号码数量

// Near Area Code (With MMS Capability) + Buy 2
Twilio::numbersNear([ 'AreaCode' => '415' ], ['MmsEnabled' => true], 2);	

// Near Another Phone #
Twilio::numbersNear([ 
	'NearNumber' => '415XXXXXX',	// Other Number
	'Distance'	 => '50'			// Miles (optional, default: 25)
]);

// Near A City (any combination allowed)
Twilio::numbersNear([ 
	'InRegion'		=> 'CA',		// State/Region/Province Code
	'InPostalCode'	=> '90017'		// Postal code?
]);

// Near Lat/Long Coordinates
Twilio::numbersNear([
	'NearLatLong'	=> '37.840699,-122.461853',
	'Distance'		=> '50'
]);

// ... you get the idea.  Most fields can be mixed and matched arbitrarily, but if you are wondering, test it out for yourself!

通过正则表达式

一个匹配电话号码的模式。有效的字符是 '' 和 [0-9a-zA-Z]。'<'em>' 字符将匹配任何单个数字。请参阅下面的示例 2 和示例 3。

// By Regex 
// Valid characters are '*' and [0-9a-zA-Z]. The '*' character will match any single digit. 

Twilio::numbersNear([ 'Contains' => 'J42' ]);			// Matches String
Twilio::numbersNear([ 'Contains' => '510555****' ]);	// Matches Pattern

// Purchase Phone Numbers

Twilio::buyNumber('4151111111');	// Valid as a single request
Twilio::buyNumber([
	'4151111111',
	'4152222222'
]);									// Or an array

// Including a configuration is recommended, but optional
Twilio::buyNumber([
	'4151111111',
	'4152222222'
], [
	'VoiceUrl'		=> 'myendpoint',
	'SmsUrl'		=> 'mysmsendpoint',
	'VoiceMethod'	=> 'GET'
]);

// Associate a # with a new TWIML endpoint

Twilio::update(Twilio::buyNumber('4151111111'), [
	'VoiceUrl'	=> '<new twiml endpoint>'
]);