Upgrading

Errors, Models and Lists

Every 5xx response still raises ApiServerException, whatever its body, and transport failures raise the same exception classes as before. These responses and calls behave differently now:

ApiBadResponseException, ApiServerException and the other Api* exceptions now extend the new ApiConnectionException, which extends FilesException, so code that catches them needs no change.

The message of an exception for an HTTP error response now names the request, as in The GET request failed with HTTP 404 Not Found (not-found)., instead of repeating the HTTP client's message with the start of the response body. Read the API's own error message with getError().

A method that returns a model, such as create(), find() or update(), now raises ApiBadResponseException when the response is not a JSON object, where earlier releases returned an empty model. save() then leaves the object as it was, instead of replacing its attributes and returning true. A list response that is not a JSON array, or an entry of a list of models that is not a JSON object, raises it too.

update() now also refreshes the object it is called on with the saved attributes, and still returns them as a separate model.

A method without parameters, such as ApiKey::findCurrent(), now uses its options, such as api_key and workspace_id, for its request, where earlier releases sent them as request parameters.

An auto-paginated list method now reads the next page's cursor from X-Files-Cursor-Next whenever the response has that header, and from X-Files-Cursor otherwise, and follows a cursor of 0. A list that returns a cursor it already sent raises ApiBadResponseException instead of requesting pages without end. List methods that page with a cursor also have page counterparts, such as Folder::listForPage(); see Pagination.

Credentials and Parameters

An api_key option, given to a model object or a method, now takes the place of a session set with Files::setSessionId() as well as the API key set with Files::setApiKey(); earlier releases sent that session instead. A session_id option is still used before an api_key option, and without either the configured session is still used before the configured API key. An option that PHP reads as false, such as null, '' or '0', is ignored, as before.

A request given a session_id or api_key option no longer also sends an X-FilesAPI-Auth or X-FilesAPI-Key header of its headers option, in any letter case. Without such an option, the headers option is sent as before. Creating a session still sends no API key of the SDK's own; given an api_key option, it no longer sends the configured session either.

A TransferJob's api_key, session_id and workspace_id options still replace the job's copy of those settings whenever they are given, null and false included. A job's api_key that PHP reads as true now also takes the place of the session the job copied from Files::setSessionId(), unless the job is given such a session_id as well. A transfer's own options choose as a request's options do.

A model method now raises InvalidParameterException, before it sends anything, for an integer, string or array parameter given false, or another empty value of the wrong type such as '' for an integer, where earlier releases sent it. A required parameter other than a boolean that is missing or empty still raises MissingParameterException. A required boolean parameter now accepts false, including from the model object's own attribute, and a boolean parameter raises InvalidParameterException for an array or object.

Upgrading to Files.com PHP SDK 2.0? Learn about namespace changes for exception classes to comply with PSR-4 and PSR-12 standards.

In Version 2.0, the Files.com PHP SDK was updated to comply with both the PSR-12 coding standard and the PSR-4 autoloading standard. No new classes were added or any existing classes removed, but some were moved to comply with the PSR-4 standard. If a client of the sdk references the moved classes, the client code will need to be updated to reference the new location of these classes.

Exception Classes

The affected classes were primarily Exception classes. Exceptions were moved into their own namespace (and source files).

The following table shows the classes that were changed for compliance

Base Exceptions

The Base exception were moved from the \Files namespace to the \Files\Exception namespace.

Examples of Base Exceptions Classes moved.

BadRequest Exceptions

The BadRequest group of exceptions were moved from the \Files\BadRequest namespace to the \Files\Exception\BadRequest namespace.

Example of BadRequest Classes moved.

NotAuthenticated Exceptions

The NotAuthenticated group of exceptions were moved from the \Files\NotAuthenticated namespace to the \Files\Exception\NotAuthenticated namespace.

Example of NotAuthenticated Classes moved.

NotAuthorized Exceptions

The NotAuthorized group of exceptions were moved from the \Files\NotAuthorized namespace to the \Files\Exception\NotAuthorized namespace.

Example of NotAuthorized Classes moved.

NotFound Exceptions

The NotFound group of exceptions were moved from the \Files\NotFound namespace to the \Files\Exception\NotFound namespace.

Example of NotFound Classes moved.

ProcessingFailure Exceptions

The ProcessingFailure group of exceptions were moved from the \Files\ProcessingFailure namespace to the \Files\Exception\ProcessingFailure namespace.

Example of ProcessingFailure Classes moved.

RateLimited Exceptions

The ProcessingFailure group of exceptions were moved from the \Files\RateLimited namespace to the \Files\Exception\RateLimited namespace.

Example of RateLimited Classes moved.

ServiceUnavailable Exceptions

The ServiceUnavailable group of exceptions were moved from the \Files\ServiceUnavailable namespace to the \Files\Exception\ServiceUnavailable namespace.

Example of ServiceUnavailable Classes moved.

SiteConfiguration Exceptions

The SiteConfiguration group of exceptions were moved from the \Files\SiteConfiguration namespace to the \Files\Exception\SiteConfiguration namespace.

Example of SiteConfiguration Classes moved.