5.x Migration Guide

This is an upgrade guide for moving from 4.x to 5.x versions of the twilio-php helper library.

Namespaces

The new library takes advantage of modern PHP namespaces for proper auto-loading. This means classes are no longer prepended by "Services_" or contain long class names.

use \Twilio\Rest\Client;

Accessing Resources

// Old
$feedback = $client->account->calls('CA123xxx')->getFeedback();

// New
$feedback = $client->api->v2010->account->calls('CA123xxxx')->feedback()->fetch();
// OR
$feedback = $client->calls('CA123xxxx')->feedback()->fetch();

The new library makes Twilio API subdomains (Lookups, Conversations, Monitor, etc.) first-class citizens. You can now also pin your interactions to the Twilio API to specific versions of that API (so here, ->v2010 ensures we always talk to the 2010-04-01 version of the API). This allows you to migrate portions of your code to future versions independently without having to do a full upgrade when you update the library.

You'll also notice you have to call fetch at the end to get the actual instance of a Call. This is because ->calls('CAxxx') returns a "Context", which we can then fetch to retrieve an "Instance", with all of it's properties attached. This allows for better network efficiency and makes it more clear when the library is actually performing HTTP interactions.

$workspace = $client->taskrouter->workspaces('WSxxx') //=> <WorkspaceContext ...>
$workspace->fetch(); //=> <WorkspaceInstance status='active'...>

Arguments

In the old library, arguments for action methods were very inconsistent. For example, you would create a Call like so:

$call = $client->account->calls->create('+12223334444', '+14443332222', 'https://example.com');

But you would create a Message using an array:

$message = $client->account->messages->create(array('To' => '+12335554444', 'From' => '+13344445555', 'Body' => 'hello'));

In 5.x, all resources are consistent. They all use positional arguments for required parameters, and array() objects for optionals and conditionals:

$message = $client->messages->create(
    '+12335554444',
    array(
        'from' => '+13344445555',
        'body' => 'hello'
    )
);

Listing Resources

There are now 2 ways to get a list of resources: read and stream.

• read returns an array that contains the Instances of resources.

$client->api->messages->read(); //=> [#<MessageInstance ..>, #<MessageInstance ..>, ...]

• stream returns an Iterator that can be used in a foreach, it efficiently pages the list of resources for you and will pass limit amount of instances to the block (or every resource in the entire list, if no limit is set).

foreach ($client->calls->stream() as $call) {
  print($call->sid);
}

Paging

The library now automatically handles paging for you! In both list and stream, you can specify the amount of instances you want to grab (limit), the maximum size you want each page fetch to be (page_size), and the maximum amount of pages to fetch (page_limit). The library will then handle the rest for you (as efficiently as possible)!

$calls = $client->calls->read(array('limit' => 1000));
$calls->length; // 1000

Configurable HTTP Client

You can now plug your own HTTP client into the client! Just make a wrapper that conforms to the Twilio\Http\HttpClient interface. Then, pass an initialized object into the client:

$customClient = new MyCustomClient();
$client = new Client('ACxxx', 'AUTHTOKEN', array('httpClient' => customClient));

Exceptions

Getting the HTTP status of a RestException now uses the method getStatusCode instead of the old getStatus.

try {
  $message = $client->messages->create('+12335554444', array('from' => '+13344445555','body' => 'hello'));
} catch (RestException $e) {
  echo $e->getStatusCode();
}