[TASK] Introduce Examples and means for rendering Verification Buttons

ReadMe.md

@@ -0,0 +1,59 @@
+# SkillDisplay PHP ToolKit
+
+## About SkillDisplay
+The European SkillDisplay is a web portal created by the NPO Verein Business Angels and allows Learners worldwide to claim verification for their skills on a European level. The skills are based on industry certifications which are broken down into dependent skills by the certification authorities themselves.
+
+You can find more information at: https://www.skilldisplay.eu
+
+## About the PHP ToolKit
+The PHP Toolkit is designed to help you connecting your own PHP application with SkillDisplay functionality. Examples:
+- You write a blog and let people track what they learned with the help of your article
+- You have an exam system want to grant Skill verification to users based on the results
+- You have a task system and want to award Skill verification on completion of a task
+
+## Verification Types
+### Self-Verifications
+Self-Verifications are a users way to say "I can do this". This is like writing it in a resumée, but instead of an arbitrary text the claim is put into context of Skills on European level.
+
+You'll want to include Self-Verification in your application for all matters of self-study. (Completing a tech article, Progressing in a Tutorial, etc.)
+ 
+### External Verifications
+ These Verifications require a second party - a person or organization who is tasked with verifying Skills of users in a specific context.
+ - Automatic Educational-Verification: Grant skill verification via an exam system in a school, an automated review after a coaching, etc.
+ - Business-Verification: Grant skill verification via a task system or project management tool which tracks work completed by employees
+ - Certification: Grant skill certification via a test system for official Certification exams
+
+## Requirements
+In order to work with the PHP Toolkit you need the following:
+### Rendering of Verification Links and/or Buttons
+If you don't want to automate the process of skill verification for users and just want to render links they can follow to manually request verification you do not need any special settings.
+
+Included examples:
+- Render verification buttons in the SkillDisplay design (src/Example/NoSettingsRequired/RenderVerificationButtons.php)
+- Render verification links without a design if you want to use a custom look (src/Example/NoSettingsRequired/RenderCustomVerificationLinks.php)
+
+### Automatic Self-Verifications
+ In order to implement Self-Verification for Skills you need:
+ - An API Key
+ 
+ Obtaining an API Key is easy. Just write us an E-Mail to [partners@skilldisplay.eu], and let us know your use-case. We'll then send you an API Key.
+ 
+Included examples:
+- grant automatic Self-Verification of a skill to a user for whom you know the SkillDisplay E-Mail Account  (src/Example/APIKeyRequired/AutoGrantSelfVerification.php)
+  
+ ### Automatic External-Verification
+
+ In order to implement these types of Verification for Skills you need:
+ - An API Key
+ - A VerifierID
+ - A Verifier secret key
+ 
+ We grant a VerifierID and a Verifier secret key to our partners.
+ - Business Representatives: https://www.skilldisplay.eu/en/platform-guide/skilldisplay-for-business-persons/
+ - Educators: https://www.skilldisplay.eu/en/platform-guide/skilldisplay-for-educators/
+ - Certifiers: https://www.skilldisplay.eu/en/platform-guide/skilldisplay-for-certifiers/
+
+Included examples:
+- grant automatic Business-Verification of a skill to a user for whom you know the SkillDisplay E-Mail Account (src/Example/FullSettingsRequired/AutoGrantBusinessVerification.php)
+
+ [partners@skilldisplay.eu]:(mailto:partners@skilldisplay.eu?subject=APIKey)

composer.json

@@ -6,7 +6,7 @@
     "autoload": {
         "files": [ "src/Constants/VerificationTypes.php" ],
         "psr-4": {
-            "SkillDisplay\\APIToolKit\\": "src/"
+            "SkillDisplay\\PHPToolKit\\": "src/"
         }
     }
 }

src/Configuration/Settings.php

@@ -1,13 +1,14 @@
 <?php
 
-namespace SkillDisplay\APIToolKit\Configuration;
+namespace SkillDisplay\PHPToolKit\Configuration;
 
 class Settings{
 
     private string $user_secret = '';
     private string $apiKey = '';
     private int $verifierID = 0;
-    private string $verificationURL = '';
+    private string $APIUrl = '';
+    private string $mySkillDisplayUrl = '';
 
     /**
      * @return int
@@ -36,9 +37,17 @@ class Settings{
     /**
      * @return string
      */
-    public function getVerificationURL(): string
+    public function getAPIUrl(): string
     {
-        return $this->verificationURL;
+        return $this->APIUrl;
+    }
+
+    /**
+     * @return string
+     */
+    public function getMySkillDisplayUrl(): string
+    {
+        return $this->mySkillDisplayUrl;
     }
 
     /**
@@ -46,14 +55,15 @@ class Settings{
      * @param string $apiKey API Key to allow the application to use the endpoint
      * @param int $verifierID ID of the Verifier entry, necessary for Educational-Verification, Business-Verification or Certification
      * @param string $user_secret Secret Key of the Verifier - necessary for Educational-Verification, Business-Verification or Certification
-     * @param string|null $verificationURL URL of the SkillDisplay instance - usually this will be the public one on skilldisplay.eu
+     * @param string|null $domain URL of the SkillDisplay instance - usually this will be the public one on skilldisplay.eu
      */
-    public function __construct(string $apiKey, int $verifierID = 0, string $user_secret = '', string $verificationURL = null)
+    public function __construct(string $apiKey, int $verifierID = 0, string $user_secret = '', string $domain = null)
     {
         $this->apiKey = $apiKey;
         $this->verifierID = $verifierID;
         $this->user_secret = $user_secret;
-        $this->verificationURL = (is_null($verificationURL)) ? 'https://dev.skilldisplay.eu/api/v1/verification/create' : $verificationURL;
+        $this->APIUrl = (is_null($domain)) ? 'https://www.skilldisplay.eu' : 'https://'.$domain;
+        $this->mySkillDisplayUrl = (is_null($domain)) ? 'https://my.skilldisplay.eu' : 'https://my.'.$domain;
     }
 }
 

src/Example/APIKeyRequired/AutoGrantSelfVerification.php

@@ -0,0 +1,12 @@
+<?php
+
+namespace SkillDisplay\PHPToolKit\Example\APIKeyRequired;
+
+require '../../../vendor/autoload.php';
+require '../Includes/ExampleSettings.php';
+
+use SkillDisplay\PHPToolKit\Verification\Issuer;
+
+// Automatically grant a Self-Verification (e.g.: after completing a Learning Chapter) if the SkillDisplay username is known
+$myVerificationTool = new Issuer($mySettings);
+$myVerificationTool->issueVerification(193,'--skilldisplay-user-email--', VERIFICATION_SELF);

src/Example/FullSettingsRequired/AutoGrantBusinessVerification.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace SkillDisplay\PHPToolKit\Example\APIKeyRequired;
+
+require '../../../vendor/autoload.php';
+require '../Includes/ExampleSettings.php';
+
+use SkillDisplay\PHPToolKit\Verification\Issuer;
+
+// Automatically grant a Business-Verification (e.g.: after completing an exam) if the SkillDisplay username is known
+// In order to grant an Educational Verification you just need to exchange the constant to VERIFICATION_EDUCATIONAL
+// (your Verifier Account needs the according permissions)
+$myVerificationTool = new Issuer($mySettings);
+$myVerificationTool->issueVerification(193,'--skilldisplay-user-email--', VERIFICATION_BUSINESS);

src/Example/Includes/ExampleSettings.php

@@ -0,0 +1,12 @@
+<?php
+
+use SkillDisplay\PHPToolKit\Configuration\Settings;
+
+// In order to make the examples in the folders "APIKeyRequied" and "FullSettingsRequired" work, insert your settings here
+// Check the ReadMe.md in order to find out how to obtain an APIKey and or Verifier Credentials
+$mySettings = new Settings(
+    '---YOUR-API-KEY---',
+    0,
+    '',
+    'www.skilldisplay.eu'
+);

src/Example/NoSettingsRequired/RenderCustomVerificationLinks.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace SkillDisplay\PHPToolKit\Example\NoSettingsRequired;
+
+require '../../../vendor/autoload.php';
+
+// We don't need an APIKey or Verifier Credentials, just create some empty settings
+use SkillDisplay\PHPToolKit\Configuration\Settings;
+use SkillDisplay\PHPToolKit\Verification\Link;
+
+$mySettings = new Settings('none');
+
+// we want to create a link for "Choosing a secure password" and style it ourselves
+// A click on a link created this way will trigger the Verification interface on the SkillDisplay platform.
+// The user will be invited to choose a verifier for the according level and submit a request for skill verification which can be granted or denied.
+$myLink = new Link($mySettings, 7);
+
+echo <<<LINK
+    <a href="{$myLink->getVerificationLink(VERIFICATION_SELF)}" target="_blank">Self-Verification Link</a><br />
+LINK;
+
+echo <<<LINK
+    <a href="{$myLink->getVerificationLink(VERIFICATION_EDUCATIONAL)}" target="_blank">Educational-Verification Link</a><br />
+LINK;
+
+echo <<<LINK
+    <a href="{$myLink->getVerificationLink(VERIFICATION_BUSINESS)}" target="_blank">Business-Verification Link</a><br />
+LINK;
+
+echo <<<LINK
+    <a href="{$myLink->getVerificationLink(VERIFICATION_CERTIFICATION)}" target="_blank">Certification Link</a><br />
+LINK;

src/Example/NoSettingsRequired/RenderVerificationButtons.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace SkillDisplay\PHPToolKit\Example\NoSettingsRequired;
+
+require '../../../vendor/autoload.php';
+
+// We don't need an APIKey or Verifier Credentials, just create some empty settings
+use SkillDisplay\PHPToolKit\Configuration\Settings;
+use SkillDisplay\PHPToolKit\Verification\Link;
+
+$mySettings = new Settings('none');
+
+// we want to create Verification Buttons styled in the standard SkillDisplay Design for "Choosing a secure password"
+// A click on a link created this way will trigger the Verification interface on the SkillDisplay platform.
+// The user will be invited to choose a verifier for the according level and submit a request for skill verification which can be granted or denied.
+$myLink = new Link($mySettings, 7);
+
+echo $myLink->getVerificationButton(VERIFICATION_SELF);
+echo '<br /><br />';
+echo $myLink->getVerificationButton(VERIFICATION_EDUCATIONAL);
+echo '<br /><br />';
+echo $myLink->getVerificationButton(VERIFICATION_BUSINESS);
+echo '<br /><br />';
+echo $myLink->getVerificationButton(VERIFICATION_CERTIFICATION);

src/Example/VerificationGrantExample.php

@@ -1,18 +0,0 @@
-<?php
-
-namespace SkillDisplay\APIToolKit\Example;
-
-require '../../vendor/autoload.php';
-
-use SkillDisplay\APIToolKit\Configuration\Settings;
-use SkillDisplay\APIToolKit\Verification\Issuer;
-
-$mySettings = new Settings(
-    '---YOUR-API-KEY---',
-    0,
-    '',
-    ''
-);
-
-$myVerificationTool = new Issuer($mySettings);
-$myVerificationTool->issueVerification(193,'--skilldisplay-user-email--', VERIFICATION_SELF);

src/Verification/Issuer.php

@@ -1,13 +1,14 @@
 <?php
 
-namespace SkillDisplay\APIToolKit\Verification;
+namespace SkillDisplay\PHPToolKit\Verification;
 
 use GuzzleHttp\Psr7\Request;
 use Psr\Http\Message\ResponseInterface;
-use SkillDisplay\APIToolKit\Configuration\Settings;
+use SkillDisplay\PHPToolKit\Configuration\Settings;
 
 class Issuer {
     private Settings $settings;
+    private string $apislug = '/api/v1/verification/create';
 
     /***
      * @param int $skillID ID of the Skill or SkillSet
@@ -57,7 +58,7 @@ class Issuer {
         $client = new \GuzzleHttp\Client();
         $request = new Request(
             'POST',
-            $this->settings->getVerificationURL(),
+            $this->settings->getAPIUrl() . $this->apislug,
             array(
                 'Content-Type' => 'application/json',
                 'x-api-key' => $this->settings->getApiKey()