This document lists the breaking changes in the FIFA Connect ID PHP SDK 7.0 compared to 6.1, and in the bundled Connect Service Bus PHP SDK 4.0 compared to 3.0. Each change comes with the simplest way to address it.

Sections 1 and 2 describe changes that affect every integration using the SDK as described in its documentation. Section 3 describes changes that affect only custom setups: custom timeouts, direct use of the classes generated from the API specification, and custom XML serializers.


For typical integrations already running a compatible PHP version, we expect the required code changes to take hours rather than days. The actual effort will depend on the extent of customisation and testing required.


Why this upgrade is necessary

FIFA Connect ID PHP SDK 7.0 and the bundled Connect Service Bus PHP SDK 4.0 move integrations away from an outdated PHP baseline and modernise their dependencies. The previous SDK supported PHP 7.1+, but PHP 7.x has reached end of life and no longer receives official security fixes. Continuing to run an integration on these versions increases exposure to unpatched vulnerabilities and the associated risks to data confidentiality, integrity and service availability.

The upgrade introduces breaking changes because the new SDK versions use updated dependencies and interfaces, as well as stricter model validation. Integrations must adapt to these changes to use the new SDK versions on PHP 8.2 or higher. The release also adds protection for sensitive parameters in stack traces. These changes provide a more maintainable foundation for future updates; the migration steps below explain how to adapt and validate your integration before PRODUCTION deployment.

What we expect on your side

  • PHP 8.2 or higher. The SDK is tested with PHP 8.5. PHP 7.x is no longer supported.
  • PHP extensions: mbstring, openssl, simplexml, sqlite3, libxml, dom, xmlwriter. The curl and json extensions are no longer required by the SDK.
  • Composer: "fifaconnectid/php-sdk": "^7.0.0". Your project must accept the SDK's dependencies: guzzlehttp/guzzle ^7.15.2, guzzlehttp/psr7 ^2.12.3 and psr/log ^2.0 || ^3.0. If your project pins psr/log 1.x or Guzzle 6, upgrade them first.
  • Logger: a PSR-3 logger compatible with psr/log 2.x or 3.x, e.g. Monolog 2.x or newer.
  • Code you own: all required properties of model objects are set before they are passed to the SDK (see section 1.3).
  • Before PRODUCTION: run your tests against a UAT environment (Beta or Pre-Production).

Most integrations that use only RegistrationFacade, FifaConnectIdClient and the listener need these changes at most: the PHP upgrade, the logger and the model properties.


No action needed:

  • Parameters with a null default value are declared as nullable (e.g. ?EnvironmentSettings $settings = null). Calls do not change.
  • Sensitive parameters (client secret, private key and password, access token) are marked with #[\SensitiveParameter], so they are hidden in stack traces.
  • PHP 8 deprecations and warnings were fixed.

1. Connect ID SDK

1.1 PHP version and dependencies

6.17.0
PHP7.1+8.2+
HTTPcURL (ext-curl)Guzzle 7
psr/log1.x2.x or 3.x
pear/xml_serializerrequiredremoved
phpseclib/phpseclibrequiredremoved
ext-json, ext-curlrequiredremoved
ext-mbstring, ext-xmlwriter–required

Remedy:

{
  "require": {
    "php": "^8.2",
    "fifaconnectid/php-sdk": "^7.0.0"
  }
}

If you added pear/xml_serializer or phpseclib/phpseclib only because the SDK needed them, remove them from your composer.json file.

1.2 Logger (psr/log 2.x / 3.x)

psr/log 1.x is no longer supported. With psr/log 3.x, a logger written for psr/log 1.x fails to load because its method declarations do not match the interface.

Remedy: update the method declarations. This one works with both psr/log 2.x and 3.x:

// 6.1
class MyLogger extends \Psr\Log\AbstractLogger
{
    public function log($level, $message, array $context = array())
    {
        // ...
    }
}

// 7.0
class MyLogger extends \Psr\Log\AbstractLogger
{
    public function log($level, string|\Stringable $message, array $context = []): void
    {
        // ...
    }
}

Alternatively, pass an existing PSR-3 logger (e.g. Monolog) to the SDK directly.

1.3 Typed model properties

The model classes in the Fifa\ConnectId\Sdk\Api\Model namespace are now generated with OpenAPI Generator and declare PHP types. See documentation chapter "1.6 Typed Model Properties" for details.

Situation6.17.0
Reading a required property that was not setreturns nullTypeError
Passing null to a required property's setteracceptedTypeError
Passing a value of a wrong type (e.g. a string date to a \DateTime setter, a numeric string to an int setter)acceptedTypeError
Passing null to a setter of an optional property that cannot be null in the service (e.g. FindOrganisationsRequestType::setNumberOfResults(), OrganisationLocalType::setLogo())acceptedInvalidArgumentException
Passing a value that is too short (e.g. an empty string) or an invalid email addressaccepted by the setter, rejected by the serviceInvalidArgumentException
Passing a value out of range or an unknown enum value (e.g. status)InvalidArgumentExceptionInvalidArgumentException (unchanged)
// Required property
$address->getTown();            // not set   6.1: null       7.0: TypeError
$address->setTown(null);        //           6.1: accepted   7.0: TypeError
$address->setTown('');          //           6.1: accepted   7.0: InvalidArgumentException

// Optional property: null means "no value", an empty string is a value
$organisation->setEmail(null);  //           6.1: accepted   7.0: accepted
$organisation->setEmail('');    //           6.1: accepted   7.0: InvalidArgumentException

// Optional property that cannot be null in the service
$organisation->setLogo(null);   //           6.1: accepted   7.0: InvalidArgumentException

TypeError extends Error, not Exception, so catch (Exception $e) does not catch it. Use catch (Throwable $e) where model objects are built from data you do not control.

Other changes to the model classes:

  • swaggerTypes() was renamed to openAPITypes().
  • The get<Property>AllowableValues() methods are now static. Calling them on an instance still works.

1.4 Response details of failed requests

FifaConnectIdException and FifaConnectServiceBusSdkException (and the exceptions extending them, e.g. InvalidClientDataException, MessageNotFoundException, TooManyRequestsException, UnauthorizedException) no longer have getResponseHeaders(), getResponseBody() and getResponseObject(). The details are available in the HttpException returned by getPrevious().

Remedy:

use Fifa\ConnectServiceBus\Sdk\Exception\HttpException;

// 6.1
catch (FifaConnectIdException | FifaConnectServiceBusSdkException $e) {
    $body = $e->getResponseBody();
}

// 7.0
catch (FifaConnectIdException | FifaConnectServiceBusSdkException $e) {
    $httpException = $e->getPrevious();
    if ($httpException instanceof HttpException) {
        $body = $httpException->getResponseBody();
    }
}

1.5 Listener: errors thrown by message handlers

Previously, an Error (e.g. a TypeError) thrown by a message handler stopped the listener. Now it is handled like an exception: it is logged, the message is unlocked and processed again later, and after a series of unsuccessful attempts the message is moved to the dead-letter queue.

ServiceBusExceptionEvent is still raised with Exception instances only. Errors are logged, but not passed to its handlers.

2. Connect Service Bus SDK (bundled, version 4.0)

The Connect Service Bus SDK is bundled with the Connect ID SDK in lib/FifaConnectServiceBusSdk (namespace Fifa\ConnectServiceBus\Sdk). These changes also apply if you use it on its own ("fifaconnectservicebus/php-sdk": "^4.0.0").

2.1 PHP version and dependencies

Same as section 1.1 and section 1.2: PHP 8.2+, Guzzle 7, psr/log 2.x or 3.x. phpseclib was removed; encryption uses the openssl extension.

3. Custom implementations

These changes affect you only if you set custom timeouts, use the classes generated from the API specification directly, or build your own XML serializers.

3.1 Timeout setters renamed

The SDK no longer calls cURL directly, so the cURL-specific names were changed. This applies to Fifa\ConnectId\Sdk\Environment\EnvironmentInterface and to Fifa\ConnectServiceBus\Sdk\Environment\EnvironmentInterface.

6.17.0
setCurlTimeout(int $seconds)setTimeout(int $seconds)
setCurlConnectionTimeout($seconds)setConnectionTimeout(int $seconds)

Remedy:

// 6.1
$environment = Environment::Integration()
    ->setCurlTimeout(300)
    ->setCurlConnectionTimeout(60);

// 7.0
$environment = Environment::Integration()
    ->setTimeout(300)
    ->setConnectionTimeout(60);

3.2 Low-level API classes (only if used directly)

These changes affect you only if you use the classes generated from the API specification directly, instead of FifaConnectIdClient or RegistrationFacade.

  • Boolean query parameters (e.g. $force) take bool instead of the strings 'true' / 'false'.
  • Fifa\ConnectId\Sdk\Api\Configuration no longer has the cURL settings (setCurlTimeout, setCurlConnectTimeout).
  • ApiException::getResponseHeaders() returns an array (string[][]) instead of a string.
  • ApiClientConfiguration::setAccessToken() is declared as setAccessToken(string $accessToken): static.
  • Fifa\ConnectId\Sdk\Api\ApiClient was removed. The classes in Fifa\ConnectId\Sdk\Api\Resource (e.g. PersonApi, OrganisationApi) take a Guzzle client and a Configuration instead of ApiClient. getApiClient() and setApiClient() were removed.

Remedy: instead of creating the classes in Fifa\ConnectId\Sdk\Api\Resource yourself, get them from the environment:

// 6.1
$personApi = new Resource\PersonApi(new ApiClient($configuration));
$personApi->personAddRegistrationsByForce($request, 'true', $actor);

// 7.0
$personApi = $environment->getPersonApiResource($clientCredentials);
$personApi->personAddRegistrationsByForce($request, true, $actor);

3.3 XML serialization (only if you build your own serializers)

pear/xml_serializer was replaced with Fifa\ConnectId\Sdk\Util\Serialization\ObjectXmlSerializer. The XML generated by PersonLocalXmlSerializer and the TMS serializers is identical to the XML generated by 6.1, so no action is needed if you use them.

  • The XML_SERIALIZER_OPTION_* constants are no longer defined by the SDK, and CommonXmlSerializerConfiguration::buildOptions() returns the ObjectXmlSerializer::OPTION_* options.
  • ValidatingXmlSerializer and ValidatingXmlSerializerBase take any object with serialize($data) and getSerializedData() methods. Your own XML_Serializer instance is still accepted.
  • Serialization of a value that cannot be written as XML throws XmlSerializationException, with the original error available in getPrevious().

Remedy:

// 6.1
$serializer = new XML_Serializer();
$serializer->setOptions(CommonXmlSerializerConfiguration::buildOptions('PersonLocal', [
    XML_SERIALIZER_OPTION_TAGMAP => $tagMap,
]));

// 7.0
$serializer = new ObjectXmlSerializer();
$serializer->setOptions(CommonXmlSerializerConfiguration::buildOptions('PersonLocal', [
    ObjectXmlSerializer::OPTION_TAGMAP => $tagMap,
]));