Skip to content

Latest commit

 

History

History
680 lines (489 loc) · 19.8 KB

UPGRADE.md

File metadata and controls

680 lines (489 loc) · 19.8 KB
Raw

Upgrade Guide

MAJOR version bumps will have upgrade notes posted here.

[2023-03-08] 6.x.x to 7.x.x

Twilio Php Helper Library’s major version 7.0.1 is now available. We ensured that you can upgrade to Php helper Library 7.0.1 version without any breaking changes. Behind the scenes Php Helper is now auto-generated via OpenAPI with this release. This enables us to rapidly add new features and enhance consistency across versions and languages.

[2020-04-15] 6.2.x to 6.3.x

CHANGED - Optional header parameters added to Authy endpoints

Custom headers are now supported in twilio-php. The addition of these optional parameters have caused a breaking change to the read, page, and stream functions for Entity, Service, and Factor resources. These functions now expect an array of optional parameters as the first argument.

6.2.x

<? 
use Twilio\Rest\Client;
$twilio = new Client();

$entities = $twilio->authy->v1->services("ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
                              ->entities
                              ->read(20);

6.3.x

<? 
use Twilio\Rest\Client;
$twilio = new Client();

$entities = $twilio->authy->v1->services("ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
                              ->entities
                              ->read([], 20);

[2020-02-19] 5.x.x to 6.x.x

Overview

Version 6.x.x is the first version that officially drops support for Php versions 5.5, 5.6, 7.0, and 7.1.

Removal and updates to support removing Php versions 5.5, 5.6, 7.0, and 7.1:

CHANGED - Added Return and Parameter Types

A TypeError may now be thrown if you pass an incompatible type into a php helper library function or if you depend on an incompatible return type from a Php helper library function.

[2017-09-28] 5.1x.x to 5.15.x

CHANGED - Body parameter on Chat Message creation is no longer required.

Rationale

This was changed to add support for sending media in Chat messages, users can now either provide a body or a media_sid.

5.1x.x

<?php

use Twilio\Rest\Client;

$client = new Client();
$client->chat->v2->service('IS123')->channel('CH123')->message->create("this is the body");

5.15.x

<?php

use Twilio\Rest\Client;

$client = new Client();
$client->chat->v2->service('IS123')->channel('CH123')->message->create(array("body"=>"this is the body"));

[2017-05-22] 5.9.x to 5.10.x

CHANGED - Rename room Recordings resource to RoomRecordings to avoid class name conflict (backwards incompatible).

[2017-03-03] 5.5.x to 5.6.x

CHANGED - Removed end of life Sandbox Resource

5.5.x

<?php

use Twilio\Rest\Client;

$client = new Client();
$client->api->v2010->sandbox->read();

5.6.x

Not Supported.

Rationale

The Sandbox resource has been removed from the API and is no longer supported.

CHANGED - Accounts property on Client now references Accounts subdomain

5.5.x

<?php

use Twilio\Rest\Client;

$client = new Client();
// Access api.twilio.com/2010-04-01/Accounts
$client->accounts->read();

5.6.x

<?php

use Twilio\Rest\Client;

$client = new Client();
// Access accounts.twilio.com/v1
$client->accounts;
// Access new PublicKeys resource
$client->accounts->credentials->publicKey->read();

// Access api.twilio.com/2010-04-01/Accounts
$client->api->v2010->accounts->read();

Rationale

accounts.twilio.com is now publicly available, following our convention of accessing subdomains of twilio via client->{subdomain} we replaced the shortcut to 2010 Accounts with a reference to the new Accounts subdomain. 2010 Accounts are still accessible the long way client->api->v2010->accounts or client->api->accounts.

CHANGED - Chat Messages listing methods now take options array as first parameter

5.5.x

<?php

use Twilio\Rest\Client;

$client = new Client();
$client->chat->messages->read(10); // limit to 10 messages

5.6.x

<?php

use Twilio\Rest\Client;

$client = new Client();
$client->chat->messages->read(array(), 10); // limit to 10 messages
$client->chat->messages->read(array(
    "order" => "asc"
), 10); // limit to 10 messages and filter by order

Rationale

Options arrays are placed at the beginning of the function signature if the resource accepts optional params and is ommited if the resource does not accept any. Chat messages previously did not accept any optional params and now do.

[2017-02-01] 5.4.x to 5.5.x

CHANGED - Removed uri field from Pricing Phone Number Countries resource

  • the uri property on this object has been removed and is no longer returned by the api.
  • the url property is still present and unchanged and should be used instead of the uri property.

Rationale

This corrects a oversight in our code generation, new style resources such as this use url and links properties while legacy resources use uri and subresource_uris. Previously we were incorrectly returning both uri and url.

CHANGED - Use DateTime objects for dates and remove unsupported date query param filters

  • Listing some resources and filtering by StartDate<, StartDate>, EndDate<, and EndDate> will no longer work.
  • Filtering by StartDate and EndDate will continue to work, these dates are inclusive.
  • StartDate and EndDate params are now DateTime objects rather than strings. They will automcatically be converted to UTC timezone, the original DateTime object will not be modified.

Affected Resources

  • All Account Usage Record Resources (Last Month, This Month, Yesterday, All Time, Monthly, Yearly, Today, Daily).
  • Monitor Alerts, Events.
  • Taskrouter All Statistics endpoints (Workspace, TaskQueues, Workers...), Workspace Events.
  • Call Feedback Summaries.

5.4.x

<?php

use Twilio\Rest\Client;

$client = new Client();
$client->usage->records->read(array(
    "StartDate" => "1999-09-07",
    "EndDate<" => "2000-01-01"      // Allowed but would have had no effect.
));

5.5.x

<?php

use Twilio\Rest\Client;

$startDate = new DateTime("now", new DateTimeZone("America/Los_Angeles"));
$endDate = clone $startDate;
$endDate->add(new DateInterval("P2D")); // Add 2 days

$client = new Client();
$client->usage->records->read(array(
    "StartDate" => $startDate,
    "EndDate" => $endDate
));

// Passing strings will still work
$client->usage->records->read(array(
    "StartDate" => "1999-09-07" // OK
));

Rationale

Not serializing API Dates into DateTimes was an oversight initially, removing library support for date inequality filters (ie StartDate> etc) brings the library into alignment with the API behavior. Only select resources on our 2010 API support date inequalities, date inequalities were included on unsupported resources mistakenly and that functionality would never have worked anyways.

CHANGED - Chat Members and Channels List Takes Optional Parameters

  • Reading members of channel and listing channels now takes an array of options as is its first argument.
  • Affects the read, stream, and page methods of MemberList.

5.4.x

<?php

use Twilio\Rest\Client;

$client = new Client();
$client->chat->v1->services('IS123')->channels('CH123')->members->read(10);
$client->chat->v1->services('IS123')->channels->read(10);

5.5.x

<?php

use Twilio\Rest\Client;

$client = new Client();
$client->chat->v1->services('IS123')->channels('CH123')->members->read(array(), 10);
$client->chat->v1->services('IS123')->channels->read(array(), 10);
$client->chat->v1->services('IS123')->channels('CH123')->members->read(array('type' => 'public'), 10);

CHANGED - Remove ability to update type on Twilio Chat Channels

5.5.x

<?php

use Twilio\Rest\Client;

$client = new Client();
$client->chat->v1->services('IS123')->channels('CH123')->update(array('type'=>'public'));

5.5.x

Not Supported

Rationale

Make library consistent with public API, changing channel type was never supported and wouldnt have worked in previous versions anyways.

CHANGED - Chat Message Body parameter is no longer required on updates

  • Updating a message body no longer requires passing the body directly and is not required.

5.4.x

<?php

use Twilio\Rest\Client;

$client = new Client();
$client->chat->v1->services('IS123')->channels('CH123')->messages('IM123')->update('new body', array());

5.5.x

<?php

use Twilio\Rest\Client;

$client = new Client();
$client->chat->v1->services('IS123')->channels('CH123')->messages('IM123')->update(array('body' => 'new body'));

Rationale

This is a correction for what the API actually expects.

CHANGED - Taskrouter Activity demote some parameters to be optional

  • Updating a taskrouter activity now optionally takes a friendlyName parameter (was previously required).
  • Creating a taskrouter activity now optionally takes a available parameter (was previously required).
  • Creating a taskrouter task now optional takes workflowSid and attributes (were both previously required).

5.4.x

<?php

use Twilio\Rest\Client;

$client = new Client();
$client->taskrouter->v1->workspaces('WS123')->activities('WA123')->update('new friendly name');
$client->taskrouter->v1->workspaces('WS123')->activities->create('new friendly name', true);
$client->taskrouter->v1->workspaces('WS123')->tasks->create('attributes', 'WW123', array('timeout' => 10));

5.5.x

<?php

use Twilio\Rest\Client;

$client = new Client();
$client->taskrouter->v1->workspaces('WS123')->activities('WA123')->update(array('friendlyName' => 'new friendly name'));
$client->taskrouter->v1->workspaces('WS123')->activities->create('new friendly name', array('available' => true));
$client->taskrouter->v1->workspaces('WS123')->tasks->create(array(
    'attributes' => 'attributes',
    'workflowSid' => 'WW123',
    'timeout' => 10
));

Rationale

This is a correction for what the API actually expects.

CHANGED - Taskrouter Task list no longer filterable by TaskChannel

  • Previous version incorrectly allowed setting a taskChannel on a TaskReadOptions object, this is no longer supported.

Rationale

This is a correction for what the API actually allows. Previous versions allowed this to be set but it would not have had any effect.

CHANGED - Rename getStatistics to getTaskQueueStatistics method on Taskrouter TaskQueues

5.4.x

<?php

use Twilio\Rest\Client;

$client = new Client();

// Get statistics for a single task queue
$taskQueue = $client->taskrouter->v1->workspaces('WS123')->taskQueues('WQ123')->fetch();
$taskQueueStatistics = $taskQueue->getStatistics();

// Get statistics for all task queues
$client->taskrouter->v1->workspaces('WS123')->taskQueues->getStatistics();

5.5.x

<?php

use Twilio\Rest\Client;

$client = new Client();

// Get statistics for a single task queue
$taskQueue = $client->taskrouter->v1->workspaces('WS123')->taskQueues('WQ123')->fetch();
$taskQueueStatistics = $taskQueue->getTaskQueueStatistics();

// Get statistics for all task queues
$client->taskrouter->v1->workspaces('WS123')->taskQueues->getTaskQueuesStatistics();

Rationale

There was a naming conflict between TaskQueueStatistics and TaskQueuesStatistics. Both were trying to generate methods named getStatistics.

CHANGED - MMS Message Body parameter is now required on updates

  • Updating a message body now requires passing the body directly and is required.

5.4.x

<?php

use Twilio\Rest\Client;

$client = new Client();
$client->api->v2010->accounts('AC123')->messages('MM123')->update(array('body' => ''));

5.5.x

<?php

use Twilio\Rest\Client;

$client = new Client();
$client->api->v2010->accounts('AC123')->messages('MM123')->update('');

Rationale

This is used to redact a message body and the api expects the body parameter to be present, allowing this to be an optional parameter was an oversight.

CHANGED - Queues now require friendlyName parameter on creation

  • Updating a message body now requires passing the body directly and is required.

5.4.x

<?php

use Twilio\Rest\Client;

$client = new Client();
$client->api->v2010->accounts('AC123')->queues('QU123')->create(array('friendlyName' => 'Test'));

5.5.x

<?php

use Twilio\Rest\Client;

$client = new Client();
$client->api->v2010->accounts('AC123')->queues('QU123')->create('Test', array());

Rationale

This was made to enforce consistency with the API, the API will return a 400 if a friendlyName is not provided.

[2016-09-15] 5.3.x to 5.4.x

CHANGED - IP Messaging / Chat Roles Update

  • RoleInstance::update(string $friendlyName, string[] $permission) to RoleInstance::update(string[] $permission)
  • RoleContext::update(string $friendlyName, string[] $permission) to RoleContext::update(string[] $permission)

5.3.x

<?php

use Twilio\Rest\Client;

$client = new Client();
$client->chat->services('IS123')->roles('RL123')->update('Example Role', array('permission'));

5.4.x

<?php

use Twilio\Rest\Client;

$client = new Client();
$client->chat->services('IS123')->roles('RL123')->update(array('permission'));

Rationale

Role Updates do not support updating the friendlyName.

CHANGED - Page Load Exception

  • Page::processResponse(Response $response) throws DeserializeException to Page::processResponse(Response $response) throws RestException

5.3.x

<?php

use Twilio\Rest\Client;
use Twilio\Exceptions\DeserializeException;

$client = new Client();

try {
    $calls = $client->calls->read();
} catch (DeserializeException $e) {
    echo("Error reading: {$e->getMessage()}");
}

5.4.x

<?php

use Twilio\Rest\Client;
use Twilio\Exceptions\RestException;

$client = new Client();

try {
    $calls = $client->calls->read();
} catch (RestException $e) {
    echo("Error reading: {$e->getMessage()}");
}

Alternatively

<?php

use Twilio\Rest\Client;
use Twilio\Exceptions\TwilioException;

$client = new Client();

try {
    $calls = $client->calls->read();
} catch (TwilioException $e) {
    echo("Error reading: {$e->getMessage()}");
}

Rationale

Exceptions were improved to include more information about what went wrong. The Page class that is used by read and stream was missed, this bring Page up to parity with other exceptions.

The Exception class was changed to reflect that the failure is not in processing the response (Deserialization) but that the response is invalid (Rest).

[2015-08-30] 5.2.x to 5.3.x

CHANGED - SIP Credential Update

  • CredentialInstance::update(string $username, string $password) to CredentialInstance::update(array|CredentialOptions $options)
  • CredentialContext::update(string $username, string $password) to CredentialContext::update(array|CredentialOptions $options)

5.2.x

<?php

use Twilio\Rest\Client;

$client = new Client();
$client->sip->credentialLists('CL123')->credentials('CA123')->update('username', 'password');

5.3.x

<?php

use Twilio\Rest\Client;

$client = new Client();
$client->sip->credentialLists('CL123')->credentials('CA123')->update(array(
    'password' => 'password'
));

Rationale

Credential Updates only supported Updating the password and it is an optional parameter.

CHANGED - Chat/IP Messaging Role Creation

5.2.x

<?php

use Twilio\Rest\Client;

$client = new Client();
$client->chat->v1->services('IS123')->users->create('identity', 'RL123');

5.3.x

<?php

use Twilio\Rest\Client;

$client = new Client();
$client->chat->v1->services('IS123')->users->create('identity', array(
    'roleSid' => 'RL123'
));

Rationale

As the Chat product has evolved, we have added a default Role sid to User creation making the parameter optional.

[2016-08-29] 5.1.x to 5.2.x

CHANGED - Conference Participant Update

  • ParticipantInstance::update(boolean $muted) to ParticipantInstance::update(array|ParticipantOptions $options)
  • ParticipantContext::update(boolean $muted) to ParticipantContext::update(array|ParticipantOptions $options)

5.1.x

<?php

use Twilio\Rest\Client;

$client = new Client();
$client->conferences('CF123')->participants('CA123')->update(true);

5.2.x

<?php

use Twilio\Rest\Client;

$client = new Client();
$client->conferences('CF123')->participants('CA123')->update(array(
    'muted' => true,
));

Rationale

Conference Participants actually support a wider range of mutations than the 5.1.x library supported. Mute was incorrectly marked as a required property when it is actually optional. This change allows the library to provide support for the full range of mutation options.

Option Definition
hold Specifying true will hold the participant, while false will un-hold.
holdUrl The 'HoldUrl' attribute lets you specify a URL for music that plays when a participant is held. The URL may be an MP3, a WAV or a TwiML document that uses or .
holdMethod Specify GET or POST, defaults to POST
muted Specifying true will mute the participant, while false will un-mute. Anything other than true or false is interpreted as false.

Full documentation

CHANGED - Taskrouter Workflow Create

  • WorkflowList::create(string $friendlyName, string $configuration, string $assignmentCallbackUrl, array|WorkflowOptions $options) to WorkflowList::create(string $friendlyName, string $configuration, array|WorkflowOptions $options)

5.1.x

<?php

use Twilio\Rest\Client;

$client = new Client();
$client->taskrouter->workspaces('WS123')->workflows->create(
    'My New Workflow',
    '{...}',
    'http://assignment-callback-url.com'
);

5.2.x

<?php

use Twilio\Rest\Client;

$client = new Client();
$client->taskrouter->workspaces('WS123')->workflows->create(
    'My New Workflow',
    '{...}',
    array(
        'assignmentCallbackUrl' => 'http://assignment-callback-url.com',
    )
);

Rationale

When Taskrouter was first released all workflows had to communicate reservations back to a server for handling. As the product has matured a capable JavaScript SDK has been released that can handle reservations. This change allows one to use Taskrouter without an assignmentCallbackUrl instead using the client events to handle reservations.

Full documentation