Merge pull request #2 from oat-sa/develop

Develop

.github/workflows/build.yaml

@@ -0,0 +1,48 @@
+name: Build
+
+on: push
+
+jobs:
+  build:
+    runs-on: ubuntu-20.04
+
+    strategy:
+      fail-fast: false
+      matrix:
+        php: [7.2, 7.3, 7.4]
+        coverage: ["true"]
+        include:
+        - php: 8.0
+          coverage: "false" # PHPUnit 8.5.14 doesn't support code coverage under PHP 8
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v2
+
+    - name: Setup PHP & Composer
+      uses: shivammathur/setup-php@v2
+      with:
+        php-version: ${{ matrix.php }}
+        tools: composer:v2
+
+    - name: Install dependencies
+      run: composer install --no-interaction --no-suggest
+
+    - name: PHPUnit
+      env:
+        COVERAGE: ${{ matrix.coverage }}
+      run: |
+        [ $COVERAGE = "true" ] \
+          && mkdir -p build/logs && ./vendor/bin/phpunit --coverage-clover build/logs/clover.xml \
+          || ./vendor/bin/phpunit
+
+    - name: Psalm
+      run: |
+        ./vendor/bin/psalm --shepherd
+    
+    - name: Coveralls
+      if: ${{ matrix.coverage == 'true' }}
+      env:
+        COVERALLS_REPO_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      run: |
+        ./vendor/bin/php-coveralls -v

.gitignore

@@ -1,6 +1,6 @@
-composer.phar
+/build/
 /vendor/
-
-# Commit your application's lock file https://getcomposer.org/doc/01-basic-usage.md#commit-your-composer-lock-file-to-version-control
-# You may choose to ignore a library lock file http://getcomposer.org/doc/02-libraries.md#lock-file
-# composer.lock
+/.idea/
+.phpunit.result.cache
+composer.phar
+composer.lock

CHANGELOG.md

@@ -0,0 +1,8 @@
+CHANGELOG
+=========
+
+0.1.0
+-----
+
+* Added [submission review service](https://www.imsglobal.org/spec/lti-sr/v1p0) message builder
+* Added documentation

README.md

@@ -1,2 +1,59 @@
-# lib-lti1p3-submission-review
-PHP library for LTI 1.3 Submission Review implementations as platforms and / or as tools. 
+# <img src="doc/images/logo/logo.png" width="40" height="40"> [TAO](https://www.taotesting.com/) - LTI 1.3 Submission Review Library
+
+[![Latest Version](https://img.shields.io/github/tag/oat-sa/lib-lti1p3-submission-review.svg?style=flat&label=release)](https://github.com/oat-sa/lib-lti1p3-submission-review/tags)
+[![License GPL2](http://img.shields.io/badge/licence-GPL%202.0-blue.svg)](http://www.gnu.org/licenses/gpl-2.0.html)
+[![Build Status](https://github.com/oat-sa/lib-lti1p3-submission-review/actions/workflows/build.yaml/badge.svg?branch=main)](https://github.com/oat-sa/lib-lti1p3-submission-review/actions)
+[![Tests Coverage Status](https://coveralls.io/repos/github/oat-sa/lib-lti1p3-submission-review/badge.svg?branch=main)](https://coveralls.io/github/oat-sa/lib-lti1p3-submission-review?branch=main)
+[![Psalm Level Status](https://shepherd.dev/github/oat-sa/lib-lti1p3-submission-review/level.svg)](https://shepherd.dev/github/oat-sa/lib-lti1p3-submission-review)
+[![Packagist Downloads](http://img.shields.io/packagist/dt/oat-sa/lib-lti1p3-submission-review.svg)](https://packagist.org/packages/oat-sa/lib-lti1p3-submission-review)
+
+> PHP library for [LTI 1.3 Submission Review Service](https://www.imsglobal.org/spec/lti-sr/v1p0) implementations as [platforms and / or as tools](http://www.imsglobal.org/spec/lti/v1p3/#platforms-and-tools), based on [LTI 1.3 Core library](https://github.com/oat-sa/lib-lti1p3-core).
+
+# Table of contents
+
+- [TAO LTI 1.3 PHP framework](#tao-lti-13-php-framework)
+- [IMS](#ims)
+- [Installation](#installation)
+- [Documentation](#documentation)
+- [Tests](#tests)
+
+## TAO LTI 1.3 PHP framework
+
+This library is part of the [TAO LTI 1.3 PHP framework](https://oat-sa.github.io/doc-lti1p3/).
+
+## IMS
+
+You can find below [IMS](https://www.imsglobal.org/) related information.
+
+### Related specifications
+
+- [IMS LTI Submission Review Service](https://www.imsglobal.org/spec/lti-sr/v1p0)
+- [IMS LTI 1.3 Core](http://www.imsglobal.org/spec/lti/v1p3)
+- [IMS Security](https://www.imsglobal.org/spec/security/v1p0)
+
+## Installation
+
+```console
+$ composer require oat-sa/lib-lti1p3-submission-review
+```
+
+## Documentation
+
+You can find below the library documentation, presented by topics.
+
+### Quick start
+
+- how to [configure the underlying LTI 1.3 Core library](https://github.com/oat-sa/lib-lti1p3-core#quick-start)
+
+### Messages
+
+- how to [implement the submission review message workflow (as platform and / or tool)](doc/message/submission-review-workflow.md)
+
+## Tests
+
+To run tests:
+
+```console
+$ vendor/bin/phpunit
+```
+**Note**: see [phpunit.xml.dist](phpunit.xml.dist) for available test suites.

composer.json

@@ -0,0 +1,31 @@
+{
+    "name": "oat-sa/lib-lti1p3-submission-review",
+    "description": "OAT LTI 1.3 Submission Review Library",
+    "type": "library",
+    "license": "GPL-2.0-only",
+    "require": {
+        "ext-json": "*",
+        "php": ">=7.2.0",
+        "oat-sa/lib-lti1p3-core": "^6.3"
+    },
+    "require-dev": {
+        "phpunit/phpunit": "^8.5.14",
+        "php-coveralls/php-coveralls": "^2.4",
+        "psalm/plugin-phpunit": "^0.15.1",
+        "vimeo/psalm": "^4.6"
+    },
+    "autoload": {
+        "psr-4": {
+            "OAT\\Library\\Lti1p3SubmissionReview\\": "src/"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "OAT\\Library\\Lti1p3SubmissionReview\\Tests\\": "tests/",
+            "OAT\\Library\\Lti1p3Core\\Tests\\": "vendor/oat-sa/lib-lti1p3-core/tests/"
+        }
+    },
+    "config": {
+        "sort-packages": true
+    }
+}

doc/message/submission-review-workflow.md

@@ -0,0 +1,171 @@
+# Submission Review Message Workflow
+
+> How to [perform secured submission review message interactions](https://www.imsglobal.org/spec/lti-sr/v1p0), between platforms and tools.
+
+## Workflow
+
+You can find below a submission review message workflow diagram, with steps numbers:
+
+![Submission Review Workflow](../images/submission-review-workflow.png)
+
+Each step will be detailed below, from both platform and tool perspectives.
+
+## Table of contents
+
+- [1 - Platform side: LtiSubmissionReviewRequest message generation](#1---platform-side-ltisubmissionreviewrequest-message-generation)
+- [2 - Tool side: LtiSubmissionReviewRequest message handling](#2---tool-side-ltisubmissionreviewrequest-message-handling)
+
+## 1 - Platform side: LtiSubmissionReviewRequest message generation
+
+You can find below required steps to generate a LtiSubmissionReviewRequest message, needed only if you're acting as a platform.
+
+### Create the message
+
+As a platform, you can create a [LtiSubmissionReviewRequest message](https://www.imsglobal.org/spec/lti-sr/v1p0) for a tool within the context of a registration.
+
+Platforms can drive the tool behaviour on submission review interactions by providing [claims](https://www.imsglobal.org/spec/lti-sr/v1p0#ltisubmissionreviewrequest-claims) in this message.
+
+You can use the [SubmissionReviewLaunchRequestBuilder](../../src/Message/Launch/Builder/SubmissionReviewLaunchRequestBuilder.php) to create the message:
+
+```php
+<?php
+
+use OAT\Library\Lti1p3Core\Message\Payload\Claim\AgsClaim;
+use OAT\Library\Lti1p3Core\Message\Payload\Claim\ForUserClaim;
+use OAT\Library\Lti1p3Core\Registration\RegistrationRepositoryInterface;
+use OAT\Library\Lti1p3SubmissionReview\Message\Launch\Builder\SubmissionReviewLaunchRequestBuilder;
+
+// Create mandatory submission review claims
+$agsClaim = new AgsClaim(...);
+$forUserClaim = new ForUserClaim(...);
+
+// Create a builder instance
+$builder = new SubmissionReviewLaunchRequestBuilder();
+
+// Get related registration of the launch
+/** @var RegistrationRepositoryInterface $registrationRepository */
+$registration = $registrationRepository->find(...);
+
+// Build LtiSubmissionReviewRequest message
+$message = $builder->buildSubmissionReviewLaunchRequest(
+    $agsClaim,                                                     // [required] AGS claim
+    $forUserClaim,                                                 // [required] for_user claim
+    $registration,                                                 // [required] related registration
+    'loginHint',                                                   // [required] login hint that will be used afterwards by the platform to perform authentication
+    'http://tool.com/submission-review',                           // [optional] tool url where to send the LtiSubmissionReviewRequest message (if none provided will use default tool launch url)
+    null,                                                          // [optional] will use the registration default deployment id, but you can pass a specific one
+    ['http://purl.imsglobal.org/vocab/lis/v2/membership#Learner'], // [optional] roles
+    ['myCustomClaim' => 'myCustomValue']                           // [optional] supplementary claims if needed
+);
+```
+
+Since [AGS line items can be coupled to LTI resource links](https://www.imsglobal.org/spec/lti-sr/v1p0#coupled-line-item-0), you can also use the `buildLtiResourceLinkSubmissionReviewLaunchRequest()` method to ease the message creation: 
+
+```php
+<?php
+
+use OAT\Library\Lti1p3Core\Message\Payload\Claim\AgsClaim;
+use OAT\Library\Lti1p3Core\Message\Payload\Claim\ForUserClaim;
+use OAT\Library\Lti1p3Core\Registration\RegistrationRepositoryInterface;
+use OAT\Library\Lti1p3Core\Resource\LtiResourceLink\LtiResourceLink;
+use OAT\Library\Lti1p3SubmissionReview\Message\Launch\Builder\SubmissionReviewLaunchRequestBuilder;
+
+// Create a resource link
+$resourceLink = new LtiResourceLink('resourceLinkIdentifier');
+
+// Create mandatory submission review claims
+$agsClaim = new AgsClaim(...);
+$forUserClaim = new ForUserClaim(...);
+
+// Create a builder instance
+$builder = new SubmissionReviewLaunchRequestBuilder();
+
+// Get related registration of the launch
+/** @var RegistrationRepositoryInterface $registrationRepository */
+$registration = $registrationRepository->find(...);
+
+// Build LtiSubmissionReviewRequest message
+$message = $builder->buildLtiResourceLinkSubmissionReviewLaunchRequest(
+    $resourceLink,                                                 // [required] resource link
+    $agsClaim,                                                     // [required] AGS claim
+    $forUserClaim,                                                 // [required] for_user claim
+    $registration,                                                 // [required] related registration
+    'loginHint',                                                   // [required] login hint that will be used afterwards by the platform to perform authentication
+    'http://tool.com/submission-review',                           // [optional] tool url where to send the LtiSubmissionReviewRequest message (if none provided will use default tool launch url)
+    null,                                                          // [optional] will use the registration default deployment id, but you can pass a specific one
+    ['http://purl.imsglobal.org/vocab/lis/v2/membership#Learner'], // [optional] roles
+    ['myCustomClaim' => 'myCustomValue']                           // [optional] supplementary claims if needed
+);
+```
+
+### Launch the message
+
+As a result of the build, you get a [LtiMessageInterface](../../src/Message/LtiMessageInterface.php) instance that has to be used in the following ways:
+
+```php
+<?php
+
+use OAT\Library\Lti1p3Core\Message\LtiMessageInterface;
+
+/** @var LtiMessageInterface $message */
+
+// Main message properties you can use as you want to offer the launch to the platform users
+echo $message->getUrl();                // url of the launch
+echo $message->getParameters()->all();  // array of parameters of the launch
+
+// Or use those helpers methods to ease the launch interactions
+echo $message->toUrl();                // url with launch parameters as query parameters
+echo $message->toHtmlLink('click me'); // HTML link, where href is the output url
+echo $message->toHtmlRedirectForm();   // HTML hidden form, with possibility of auto redirection
+```
+
+### Implement OpenId Connect launch flow
+
+Like any platform originating message, when the LtiSubmissionReviewRequest message is launched, an [OIDC flow](https://www.imsglobal.org/spec/security/v1p0/#platform-originating-messages) will start between the tool and the platform.
+
+The underlying core library offers everything you need to securely implement this flow, as documented in the [platform originating messages documentation](https://github.com/oat-sa/lib-lti1p3-core/blob/master/doc/message/platform-originating-messages.md).
+
+## 2 - Tool side: LtiSubmissionReviewRequest message handling
+
+You can find below required steps to handle a LtiSubmissionReviewRequest message, needed only if you're acting as a tool.
+
+### Validate the message 
+
+As a tool, you'll receive an HTTP request containing the [LtiSubmissionReviewRequest message](https://www.imsglobal.org/spec/lti-sr/v1p0), generated by the platform, received after OIDC flow completion.
+
+You can use the [ToolLaunchValidator](https://github.com/oat-sa/lib-lti1p3-core/blob/master/src/Message/Launch/Validator/ToolLaunchValidator.php) to validate it:
+
+```php
+<?php
+
+use OAT\Library\Lti1p3Core\Message\Launch\Validator\Tool\ToolLaunchValidator;
+use OAT\Library\Lti1p3Core\Registration\RegistrationRepositoryInterface;
+use OAT\Library\Lti1p3Core\Security\Nonce\NonceRepositoryInterface;
+use Psr\Http\Message\ServerRequestInterface;
+
+/** @var RegistrationRepositoryInterface $registrationRepository */
+$registrationRepository = ...
+
+/** @var NonceRepositoryInterface $nonceRepository */
+$nonceRepository = ...
+
+/** @var ServerRequestInterface $request */
+$request = ...
+
+// Create the validator
+$validator = new ToolLaunchValidator($registrationRepository, $nonceRepository);
+
+// Perform validation
+$result = $validator->validatePlatformOriginatingLaunch($request);
+
+if (!$result->hasError()) {
+    // You can access the related AGS line item
+    $lineItemUrl = $result->getPayload()->getAgs()->getLineItemUrl();
+
+    // You can access the user details for whom is done the submission review
+    $user = $result->getPayload()->getForUser();
+
+    // Then implement your logic to handle the LtiSubmissionReviewRequest message and offer submission review
+}
+```
+**Note**: more details about platform originating messages on tool side validation can be found in the [platform originating messages documentation](https://github.com/oat-sa/lib-lti1p3-core/blob/master/doc/message/platform-originating-messages.md#4---tool-side-launch-validation).

phpunit.xml.dist

@@ -0,0 +1,25 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!-- https://phpunit.de/manual/current/en/appendixes.configuration.html -->
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="http://schema.phpunit.de/8.5/phpunit.xsd"
+         backupGlobals="false"
+         colors="true"
+>
+
+    <php>
+        <env name="TEST_KEYS_ROOT_DIR" value="file://vendor/oat-sa/lib-lti1p3-core/tests/Resource/Key/RSA" />
+    </php>
+
+    <testsuites>
+        <testsuite name="Unit">
+            <directory>tests/Unit</directory>
+        </testsuite>
+    </testsuites>
+
+    <filter>
+        <whitelist processUncoveredFilesFromWhitelist="true">
+            <directory>src</directory>
+        </whitelist>
+    </filter>
+</phpunit>

psalm.xml.dist

@@ -0,0 +1,25 @@
+<?xml version="1.0"?>
+<psalm
+        autoloader="vendor/autoload.php"
+        errorLevel="3"
+        hideExternalErrors="true"
+        useDocblockTypes="false"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xmlns="https://getpsalm.org/schema/config"
+        xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"
+>
+    <projectFiles>
+        <directory name="src"/>
+        <ignoreFiles>
+            <directory name="doc"/>
+            <directory name="tests"/>
+            <directory name="vendor"/>
+        </ignoreFiles>
+    </projectFiles>
+    <mockClasses>
+        <class name="PHPUnit\Framework\MockObject\MockObject"/>
+    </mockClasses>
+    <plugins>
+        <pluginClass class="Psalm\PhpUnitPlugin\Plugin"/>
+    </plugins>
+</psalm>