Skip to content

Migration from 3.x to 4.x

Jump to bottom
Jonathan VUILLEMIN edited this page Feb 24, 2021 · 63 revisions

Table of contents

New features

You can find below the list of new features offered by version 4.x.

PHP 8 support

Version 4.x refreshed it's code and 3rd party library dependencies to provide PHP 8 compatibility, but also kept PHP 7.2 as minimal version to still allow this library usage in legacy systems.

See dependencies list for details.

New keys / algorithms handling

Before version 4.x, the library was made to set up the security algorithm on application level.

Now with version 4.x:

  • the KeyInterface allows you to configure the security algorithm per declared key (default: RS256)
  • the KeyChainFactoryInterface allows now configuration on key chain level (default: RS256)

For example:

<?php

use OAT\Library\Lti1p3Core\Security\Key\KeyChainFactory;
use OAT\Library\Lti1p3Core\Security\Key\KeyInterface;
use OAT\Library\Lti1p3Core\Security\Key\Key;

// Single key with configurable algorithm
$key = new Key('content', 'secret', KeyInterface::ALG_RS512);

// Key chain with configurable algorithm
$keyChain = (new KeyChainFactory)->create(
    '1',                                // [required] identifier (used for JWT kid header)
    'mySetName',                        // [required] key set name (for grouping)
    'file://home/user/.ssh/id_rsa.pub', // [required] public key (file or content)
    'file://home/user/.ssh/id_rsa',     // [optional] private key (file or content)
    'test',                             // [optional] private key passphrase (if existing)
     KeyInterface::ALG_RS256            // [optional] algorithm (default: RS256)
);

List of available algorithms:

  • ES256/384/512
  • HS256/384/512
  • RS256/384/512

New JWT handling

Before version 4.x, the library relied directly on lcobucci/jwt 3rd party library for JWT handling.

Now, version 4.x provides an abstration layer to work with JWT (avoids breaking changes risks), built on top of those new interfaces:

You can find an usage example of those components in the library JWT flow integration test.

In version 4.x, all top level compoments (for messages and services) now rely on those interfaces, and use by default implementations provided by the library, to avoid breaking changes in your code.

Breaking changes

Globally, top level classes of the library and their usage did not change, ensuring the migration to the version 4.x to be straightforward.

But version 4.x introduce some breaking changes on lower layers, due to the introduction of the new internal collections, as detailed below for each impacted component.

LTI message parameters handling

Manipulating LTI message parameters changed from (in 3.x):

<?php

use OAT\Library\Lti1p3Core\Message\LtiMessageInterface;

/** @var LtiMessageInterface $message */
$message->getParameters();                       // returns array of parameters
$message->hasParameter('something');             // returns bool
$message->getParameter('something', 'default');  // returns parameter value or 'default'
$message->getMandatoryParameter('something');    // throws exception when not found

to (in 4.x):

<?php

use OAT\Library\Lti1p3Core\Message\LtiMessageInterface;

/** @var LtiMessageInterface $message */
$message->getParameters();                               // returns CollectionInterface (iterable)
$message->getParameters()->all();                        // returns array of parameters
$message->getParameters()->count();                      // returns number of parameters
$message->getParameters()->has('something');             // returns bool
$message->getParameters()->get('something', 'default');  // returns parameter value or 'default'
$message->getParameters()->getMandatory('something');    // throws exception when not found

LTI message payload tokens handling

Manipulating LTI message payload tokens changed from (in 3.x):

<?php

use OAT\Library\Lti1p3Core\Message\Payload\LtiMessagePayloadInterface;

/** @var LtiMessagePayloadInterface $payload */
$payload->getToken()->getClaims();              // returns array of claims
$payload->getToken()->hasClaim('something');    // returns bool
$payload->getToken()->getClaim('something');    // returns claim value or thow exception when not found

to (in 4.x):

<?php

use OAT\Library\Lti1p3Core\Message\Payload\LtiMessagePayloadInterface;

/** @var LtiMessagePayloadInterface $payload */
$payload->getToken()->getClaims();                              // returns CollectionInterface (iterable)
$payload->getToken()->getClaims()->all();                       // returns array of claims
$payload->getToken()->getClaims()->count();                     // returns number of claims
$payload->getToken()->getClaims()->has('something');            // returns bool
$payload->getToken()->getClaims()->get('something', 'default'); // returns claim value or 'default'
$payload->getToken()->getClaims()->getMandatory('something');   // throws exception when not found

// token headers are also available as collection
$payload->getToken()->getHeaders()->all();                      // returns array of headers
$payload->getToken()->getHeaders()->count();                    // returns number of headers
$payload->getToken()->getHeaders()->has('something');           // returns bool
...

Resource properties handling

Manipulating resource properties changed from (in 3.x):

<?php

use OAT\Library\Lti1p3Core\Resource\ResourceInterface;

/** @var ResourceInterface $resource */
$resource->getProperties();                      // returns array of properties
$resource->hasProperty('something');             // returns bool
$resource->getProperty('something', 'default');  // returns property value or 'default'

to (in 4.x):

<?php

use OAT\Library\Lti1p3Core\Resource\ResourceInterface;

/** @var ResourceInterface $resource */
$resource->getProperties();                                // returns CollectionInterface (iterable)
$resource->getProperties()->all();                         // returns array of properties
$resource->getProperties()->has('something');              // returns bool
$resource->getProperties()->get('something', 'default');   // returns property value or 'default'
$resource->getProperties()->getMandatory('something');     // throws exception when not found

User identity additional properties handling

Manipulating user identity additional properties changed from (in 3.x):

<?php

use OAT\Library\Lti1p3Core\User\UserIdentityInterface;

/** @var UserIdentityInterface $user */
$user->getAdditionalProperties();                       // returns array of properties
$user->getAdditionalProperty('something', 'default');   // returns property value or 'default'

to (in 4.x):

<?php

use OAT\Library\Lti1p3Core\User\UserIdentityInterface;

/** @var UserIdentityInterface $user */
$user->getAdditionalProperties();                                // returns CollectionInterface (iterable)
$user->getAdditionalProperties()->all();                         // returns array of properties
$user->getAdditionalProperties()->has('something');              // returns bool
$user->getAdditionalProperties()->get('something', 'default');   // returns property value or 'default'
$user->getAdditionalProperties()->getMandatory('something');     // throws exception when not found
Clone this wiki locally