Initial Code

Author: vixducis

.gitignore

@@ -0,0 +1 @@
+/vendor/

CHANGELOG.md

@@ -0,0 +1,58 @@
+# Informat API Wrapper
+PHP client library for the Informat school software API. This client allows you to 
+- Fetch students
+- Fetch registration
+- Create new preregistrations
+
+## Usage
+The library is built on 3 main 'layers':
+- The `Informat` class, which is instantiated with your client ID and secret.
+- Directories, which are logical groups of api calls. These can be obtained by function calls on the `Informat` class.
+- API calls, these can be instantiated by function calls on the directories.
+
+The code below is a quick example of how you can fetch students
+```php
+use Koba\Informat\Informat;
+use Koba\Informat\Scopes\AllScopesStrategy;
+
+$informat = new Informat(
+    'your-client-id',
+    'your-client-secret',
+    new AllScopesStrategy('000001', '000002', '000003'),
+);
+
+ $informat
+    ->students()
+    ->getStudents('000001')
+    ->send();
+```
+This will return an array of `Student` objects, which has typed (and documented) properties.
+
+### Scopes
+Creating the `Informat` object can be done fairly easily as demonstrated above. The scopes paramete might need some extra explanation.
+
+In the example above you see we pass an `AllScopesStrategy` object to the constructor. This is a way to let the API client know which scopes we want to request, which directly impacts which API calls you will be authorized to execute. The library supplies the `AllScopesStrategy`, which will request all possible scopes and the `SpecificScopesStrategy`, which allows you to specify the scopes that will be requested. Both require you to pass the institute numbers for all schools you wnat to access as parameters. The latter might be desirable if your client isn't authorized for all scopes or you want to limit the functionality for security reasons.
+
+You can also create your own scope strategy by implementing the `ScopeStrategyInterface`.
+
+### Calls
+There are a couple of 'rules' that should be followed when managing calls
+- When creating a call using a function on a directory, all required parameters for the API call need to be passed to the function. The institute number will always be the first parameter as it is required for all API calls.
+- All optional paremeters can be set using setters on the API call.
+- Setters on the API calls returns the call itself, which means you can easily chain them together.
+- An API call will always be executed with the `send` method.
+
+An example to illustrate these points:
+```php
+$informat
+    ->students()
+    ->getStudent(
+        '000001', // institute number
+        'bd26bb65-f54a-488d-866b-e1f9927d6be5' // student id
+    )
+    ->setReferenceDate(new DateTime())
+    ->send();
+```
+
+### Advanced
+The `Informat` object has some advanced setup options. You can pass an `AccessTokenManagerInterface` object, which allows you to implement your own access token caching solution. The rest of the constructor can be used to pass a [psr-18](https://www.php-fig.org/psr/psr-18/) client interface and [psr-17](https://www.php-fig.org/psr/psr-17/) HTTP response factories. If these options are omitted, the library will autodiscover any suitable implementations. If your project doesn't currently have one, you could take a look at [Guzzle 7](https://docs.guzzlephp.org/en/stable/).

CONTRIBUTING.md

@@ -0,0 +1,31 @@
+{
+    "name": "koba/informat-php-client",
+    "description": "A PHP wrapper for the informat API",
+    "type": "library",
+    "license": "MIT",
+    "authors": [
+        {
+            "name": "Wouter Henderickx",
+            "email": "[email protected]"
+        }
+    ],
+    "require": {
+        "php": "^8.1.0",
+        "psr/http-client-implementation": "*",
+        "psr/http-factory-implementation": "*",
+        "php-http/discovery": "^1.19"
+    },
+    "autoload": {
+        "psr-4": {
+            "Koba\\Informat\\": "src/Informat/"
+        }
+    },
+    "require-dev": {
+        "phpstan/phpstan": "^1.10"
+    },
+    "config": {
+        "allow-plugins": {
+            "php-http/discovery": true
+        }
+    }
+}

README.md

@@ -0,0 +1,4 @@
+parameters:
+	level: 9
+	paths:
+		- src

composer.json

@@ -0,0 +1,58 @@
+<?php
+
+namespace Koba\Informat\AccessToken;
+
+class AccessToken
+{
+    protected int $created_at;
+
+    public function __construct(
+        protected string $accessToken,
+        protected int $expiresIn,
+        ?int $created_at = null
+    ) {
+        $this->created_at = $created_at ?? time();
+    }
+
+    /**
+     * Returns whether the access token has expired.
+     */
+    public function expired(): bool
+    {
+        return (time() - $this->created_at) > $this->expiresIn;
+    }
+
+    /**
+     * Returns the actual bearer token you need to include in request headers.
+     */
+    public function getAccessToken(): string
+    {
+        return $this->accessToken;
+    }
+
+    /**
+     * Returns the timestamp on which the access token was created.
+     */
+    public function getCreatedAt(): int
+    {
+        return $this->created_at;
+    }
+
+    /**
+     * Returns the number of seconds after which the access token expires,
+     * starting from the creation date of the token.
+     */
+    public function getExpiresIn(): int
+    {
+        return $this->expiresIn;
+    }
+
+    /**
+     * String transformation, just returns the bearer token.
+     * @return string 
+     */
+    public function __toString()
+    {
+        return $this->getAccessToken();
+    }
+}

phpstan.neon

@@ -0,0 +1,60 @@
+<?php
+
+namespace Koba\Informat\AccessToken;
+
+use Koba\Informat\Exceptions\AccessTokenException;
+use Koba\Informat\Scopes\ScopeStrategyInterface;
+use Psr\Http\Client\ClientInterface;
+use Psr\Http\Message\RequestFactoryInterface;
+use Psr\Http\Message\StreamFactoryInterface;
+
+class AccessTokenFetcher
+{
+    public function __construct(
+        protected string $clientId,
+        protected string $clientSecret,
+        protected ScopeStrategyInterface $scopeStrategy,
+        protected ClientInterface $httpClient,
+        protected RequestFactoryInterface $requestFactory,
+        protected StreamFactoryInterface $streamFactory
+    ) {
+    }
+
+    public function fetch(): AccessToken
+    {
+        $request = $this->requestFactory
+            ->createRequest(
+                'post',
+                'https://www.identityserver.be/connect/token'
+            )
+            ->withAddedHeader('Content-Type', 'application/x-www-form-urlencoded')
+            ->withBody($this->streamFactory->createStream(
+                http_build_query([
+                    'client_id' => $this->clientId,
+                    'client_secret' => $this->clientSecret,
+                    'scope' => implode(' ', $this->scopeStrategy->getScopes()),
+                    'grant_type' => 'client_credentials'
+                ])
+            ));
+
+        $response = $this->httpClient->sendRequest($request);
+        if ($response->getStatusCode() !== 200) {
+            throw new AccessTokenException('Fetching access token failed.');
+        }
+
+        $decoded = json_decode(
+            $response->getBody()->getContents(),
+            true
+        );
+
+        if (
+            is_array($decoded)
+            && array_key_exists('access_token', $decoded)
+            && array_key_exists('expires_in', $decoded)
+        ) {
+            return new AccessToken($decoded['access_token'], $decoded['expires_in']);
+        }
+
+        throw new AccessTokenException('Invalid access token');
+    }
+}

src/Informat/AccessToken/AccessToken.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace Koba\Informat\AccessToken;
+
+class AccessTokenManager implements AccessTokenManagerInterface
+{
+    protected ?AccessToken $accessToken = null;
+    protected AccessTokenFetcher $accessTokenFetcher;
+
+    public function getAccessToken(): AccessToken
+    {
+        if ($this->accessToken === null || $this->accessToken->expired()) {
+            $this->accessToken = $this->accessTokenFetcher->fetch();
+        }
+
+        return $this->accessToken;
+    }
+
+    public function setAccessTokenFetcher(AccessTokenFetcher $fetcher): self
+    {
+        $this->accessTokenFetcher = $fetcher;
+        return $this;
+    }
+}

src/Informat/AccessToken/AccessTokenFetcher.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace Koba\Informat\AccessToken;
+
+interface AccessTokenManagerInterface
+{
+    /** Should return a valid, non-expired access token */
+    public function getAccessToken(): AccessToken;
+    public function setAccessTokenFetcher(AccessTokenFetcher $fetcher): self;
+}