Merge pull request #2 from Ticketpark/v2

Author: sprain

.github/workflows/tests.yml renamed to .github/workflows/ci.yml

@@ -1,18 +1,86 @@
 # Ticketpark PHP API Client
 
-A basic api client to consume the Ticketpark REST API.
+[![Build Status](https://github.com/Ticketpark/php-api-client/actions/workflows/ci.yml/badge.svg)](https://github.com/sprain/php-swiss-qr-bill/actions)
+
+
+A PHP client to consume the Ticketpark REST API.
 
 ## Installation
 
-Simply add this library to your composer.json:
+Add this library to your composer.json:
 
 ```
 composer require ticketpark/php-api-client
 ```
 
 ## Usage
-See example.php
+
+Also see `example.php`.
+
+### Getting data (GET)
+
+```php
+<?php
+
+include('vendor/autoload.php');
+
+$client = new \Ticketpark\ApiClient\TicketparkApiClient('yourApiKey', 'yourApiSecret');
+$client->setUserCredentials('[email protected]', 'yourPassword');
+
+$response = $client->get('/events/', ['maxResults' => 2]);
+
+if ($response->isSuccessful()) {
+    $data = $response->getContent();
+}
+```
+
+### Creating data (POST)
+
+```php
+<?php
+
+include('vendor/autoload.php');
+
+$client = new \Ticketpark\ApiClient\TicketparkApiClient('yourApiKey', 'yourApiSecret');
+$client->setUserCredentials('[email protected]', 'yourPassword');
+
+$response = $client->post('/events/', [
+    'host' => 'yourHostPid',
+    'name' => 'Some great event',
+    'currency' => 'CHF'
+]);
+
+if ($response->isSuccessful()) {
+    $pidOfNewEvent = $response->getGeneratedPid();
+    
+    // if you created a collection of records, the response will contain a link instead
+    // that can be used to fetch the data of the newly generated records.
+    //
+    // $path = $response->getGeneratedListLink();
+    // $newResponse = $client->get($path);
+}
+```
+
+### Updating data (PATCH)
+
+```php
+<?php
+
+include('vendor/autoload.php');
+
+$client = new \Ticketpark\ApiClient\TicketparkApiClient('yourApiKey', 'yourApiSecret');
+$client->setUserCredentials('[email protected]', 'yourPassword');
+
+$response = $client->patch('/events/yourEventPid', [
+    'name' => 'Some changed event name'
+]
+
+if ($response->isSuccessful()) {
+    // Data was successfully updated
+}
+```
+
 
 ## User credentials
-Get in touch with us to get your user credentials:
-[tech@ticketpark.ch](mailto:[email protected]), [www.ticketpark.ch](http://www.ticketpark.ch)
+Get in touch with us to get your user credentials:<br>
+[support@ticketpark.ch](mailto:support@ticketpark.ch)

.travis.yml

@@ -3,8 +3,8 @@
     "description": "A PHP client to use the Ticketpark API",
     "type": "library",
     "require": {
-        "php": ">=8.1",
-        "kriswallsmith/buzz": "^0.15.0"
+        "php": "^8.1|^8.2",
+        "guzzlehttp/guzzle": "^6.5|^7.5"
     },
     "license": "MIT",
     "authors": [
@@ -23,6 +23,7 @@
     "require-dev": {
         "phpunit/phpunit": "^9.6",
         "rector/rector": "^0.18.3",
-        "friendsofphp/php-cs-fixer": "^3.27"
+        "friendsofphp/php-cs-fixer": "^3.27",
+        "phpspec/prophecy": "^1.17"
     }
 }

README.md

@@ -12,24 +12,21 @@
 //     With frequent requests, re-using tokens results in less api requests than using user credentials only.
 //
 // $client->setAccessToken('someAccessTokenString');
-// or $client->setAccessTokenInstance(new AccessToken($string, $expiration));
 // $client->setRefreshToken('someRefreshToken');
-// or $client->setRefreshTokenInstance($string, $expiration);
 
 // 3. Execute the desired command
-$response = $client->get('/events/', array('maxResults' => 2));
+$response = $client->get('/events/', ['maxResults' => 2]);
 
 // 4. Handle the response
-//    It is an instance of Buzz\Message\Response
 if ($response->isSuccessful()) {
-    print "<strong>Request successful!</strong><br>";
-    $events = json_decode($response->getContent(), true);
+    print "Request successful!\n\n";
 
+    $events = $response->getContent();
     foreach($events as $event) {
-        print $event['name']."<br>";
+        print $event['name']."\n";
     }
 }
 
-// 5. Get the tokens and store them to use them again later on
+// 5. Recommended: Get the tokens and store them to use them again later on
 $myAccessToken  = $client->getAccessToken();
 $myRefreshToken = $client->getRefreshToken();

composer.json

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ticketpark\ApiClient\Exception;
+
+class HttpRequestException extends \Exception
+{
+}

example.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ticketpark\ApiClient\Exception;
+
+class HttpTimeOutException extends \Exception
+{
+}

lib/ApiClient/Exception/HttpRequestException.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ticketpark\ApiClient\Exception;
+
+class UnexpectedResponseException extends \Exception
+{
+}

lib/ApiClient/Exception/HttpTimeOutException.php

@@ -0,0 +1,116 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ticketpark\ApiClient\Http;
+
+use GuzzleHttp\Client as GuzzleClient;
+use GuzzleHttp\Exception\ClientException;
+use GuzzleHttp\Exception\ConnectException;
+use GuzzleHttp\Psr7\Response as GuzzleResponse;
+use Ticketpark\ApiClient\Exception\HttpRequestException;
+use Ticketpark\ApiClient\Exception\HttpTimeOutException;
+
+final class Client implements ClientInterface
+{
+    private readonly GuzzleClient $guzzle;
+
+    public function __construct()
+    {
+        $this->guzzle = new GuzzleClient();
+    }
+
+    public function head(string $url, array $headers): Response
+    {
+        return $this->execute('head', $url, $headers);
+    }
+
+    public function get(string $url, array $headers): Response
+    {
+        return $this->execute('get', $url, $headers);
+    }
+
+    public function post(string $url, string $content, array $headers): Response
+    {
+        return $this->execute('post', $url, $headers, $content);
+    }
+
+    public function postForm(string $url, array $formData, array $headers): Response
+    {
+        return $this->execute('post', $url, $headers, null, $formData);
+    }
+
+    public function patch(string $url, string $content, array $headers): Response
+    {
+        return $this->execute('patch', $url, $headers, $content);
+    }
+
+    public function delete(string $url, array $headers): Response
+    {
+        return $this->execute('delete', $url, $headers);
+    }
+
+    private function execute(
+        string $method,
+        string $url,
+        array $headers = [],
+        string $content = null,
+        array $formData = []
+    ): Response {
+        try {
+            $guzzleResponse = $this->doExecute(
+                $method,
+                $url,
+                $headers,
+                $content,
+                $formData
+            );
+
+        } catch (ConnectException $e) {
+            if (str_contains($e->getMessage(), 'cURL error 28')) {
+                throw new HttpTimeOutException();
+            }
+
+        } catch (ClientException $e) {
+            /** @var GuzzleResponse $response */
+            $guzzleResponse = $e->getResponse();
+
+        } catch (\Exception $e) {
+            throw new HttpRequestException($e->getMessage());
+        }
+
+        return new Response(
+            $guzzleResponse->getStatusCode(),
+            (string) $guzzleResponse->getBody(),
+            $guzzleResponse->getHeaders()
+        );
+    }
+
+    private function doExecute(
+        string $method,
+        string $url,
+        array $headers,
+        ?string $content,
+        array $formData
+    ): GuzzleResponse {
+        $requestData = [
+            'headers' => $headers,
+            'timeout' => 30
+        ];
+
+        if ($formData) {
+            $requestData['form_params'] = $formData;
+        } else {
+            $requestData['body'] = $content;
+        }
+
+        /** @var GuzzleResponse $response */
+        $guzzleResponse = $this->guzzle->request(
+            $method,
+            $url,
+            $requestData
+        );
+
+        return $guzzleResponse;
+    }
+}

lib/ApiClient/Exception/UnexpectedResponseException.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ticketpark\ApiClient\Http;
+
+interface ClientInterface
+{
+    public function head(string $url, array $headers): Response;
+
+    public function get(string $url, array $headers): Response;
+
+    public function post(string $url, string $content, array $headers): Response;
+
+    public function postForm(string $url, array $formData, array $headers): Response;
+
+    public function patch(string $url, string $content, array $headers): Response;
+
+    public function delete(string $url, array $headers): Response;
+}