Merge pull request #43 from cultuurnet/rc-1.0

Release candidate for version 1.0

.github/pull_request_template.md

@@ -0,0 +1,18 @@
+### Added
+
+-
+
+### Changed
+
+-
+
+### Removed
+
+-
+
+### Fixed
+
+-
+
+---
+Ticket: https://jira.uitdatabank.be/browse/...

.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on: push
+
+jobs:
+    build:
+
+        runs-on: ubuntu-latest
+        strategy:
+            matrix:
+                php-versions: ['7.1', '7.2', '7.3', '7.4']
+        name: PHP ${{ matrix.php-versions }}
+        steps:
+            - uses: actions/checkout@v2
+
+            - name: Install PHP
+              uses: shivammathur/setup-php@v2
+              with:
+                  php-version: ${{ matrix.php-versions }}
+                  ini-values: xdebug.mode=coverage
+                  extensions: intl
+                  tools: composer:v1
+
+            - name: Check PHP Version
+              run: php -v
+
+            - name: Validate composer.json
+              run: composer validate
+
+            - name: Install dependencies
+              run: composer install --no-progress --no-suggest
+
+            - name: Run Phing
+              run: composer run-script phing

.gitignore

@@ -1,3 +1,4 @@
 vendor
 build
-coverage
+coverage
+composer.lock

README.md

@@ -0,0 +1,96 @@
+# search-v3
+
+This PHP library allows you to integrate with publiq's Search API3.
+
+Full API documentation: https://documentatie.uitdatabank.be/content/search_api_3/latest/start.html <br />
+Getting an API key: https://projectaanvraag.uitdatabank.be
+
+## Usage
+
+Set up a Guzzle client with a URL and API key for the test environment of Search API3 like this:
+
+```php
+$httpClient = new GuzzleHttp\Client([
+    'base_uri' => 'https://search-test.uitdatabank.be/',
+    'headers' => [
+        'X-Api-Key' => 'YOUR_API_KEY_FOR_TEST_ENV',
+    ],
+]);
+```
+
+Then, set up the search-v3 `SearchClient` like this:
+
+```php
+$searchClient = new CultuurNet\SearchV3\SearchClient(
+    $httpClient, // HTTP client set up in the previous step
+    new CultuurNet\SearchV3\Serializer() // Built-in serializer to deserialize the JSON responses
+);
+```
+
+You can then perform searches like this:
+
+```php
+$searchQuery = new \CultuurNet\SearchV3\SearchQuery();
+$events = $searchClient->searchEvents($searchQuery); // Search events
+$places = $searchClient->searchPlace($searchQuery); // Search places
+$offers = $searchClient->searchOffers($searchQuery); // Search both events + places
+```
+
+The results are an instance of `\CultuurNet\SearchV3\ValueObjects\PagedCollection`, which supports the following methods:
+
+```php
+// Get pagination info
+$events->getItemsPerPage();
+$events->getTotalItems();
+
+// Get the search results, as instances of CultuurNet\SearchV3\ValueObjects\Event
+// and CultuurNet\SearchV3\ValueObjects\Place
+$events->getMember()->getItems();
+
+// Get the facet results as an instance of CultuurNet\SearchV3\ValueObjects\FacetResults
+$events->getFacets();
+```
+
+To customize your search, you can configure `\CultuurNet\SearchV3\SearchQuery` like this:
+
+```php
+$searchQuery = new \CultuurNet\SearchV3\SearchQuery();
+
+// Embed the JSON-LD of the search results, instead of only the ID and type.
+$searchQuery->setEmbed(true);
+
+// Set the number of which result to fetch first. Defaults to 0.
+// If the first page had a limit of 30 for example, and you want to get the results of the second page, set the start to
+// 30. (So the start is always the limit multiplied by the page number you want to get, starting with 0.)
+$searchQuery->setStart(0);
+
+// Set the max amount of results to return per page.
+$searchQuery->setLimit(30);
+
+// Add a sort (see SAPI3 docs for possible fields to sort on)
+$searchQuery->addSort('created', 'ASC');
+
+// Remove a sort
+$searchQuery->removeSort('created');
+
+// Add a search parameter (see src/Parameter for all options)
+$searchQuery->addParameter(
+    new CultuurNet\SearchV3\Parameter\AudienceType(
+        CultuurNet\SearchV3\Parameter\AudienceType::AUDIENCE_EDUCATION
+    )
+);
+
+// Remove a search parameter (see src/Parameter for all options)
+$searchQuery->removeParameter(
+    new CultuurNet\SearchV3\Parameter\AudienceType(
+        CultuurNet\SearchV3\Parameter\AudienceType::AUDIENCE_EDUCATION
+    )
+);
+```
+
+Some parameters allow multiple options and can be added more than once:
+```php
+$searchQuery->addParameter(new CultuurNet\SearchV3\Parameter\Label('foo'));
+$searchQuery->addParameter(new CultuurNet\SearchV3\Parameter\Label('bar'));
+// Will return only results that have both labels.
+```

build.xml

@@ -34,7 +34,7 @@
     </target>
 
     <target name="coding-standards">
-        <exec command="vendor/bin/phpcs --config-set installed_paths vendor/escapestudios/symfony2-coding-standard"
+        <exec command="vendor/bin/phpcs"
               passthru="true"/>
         <phpcodesniffer
                 standard="phpcs-ruleset.xml"

composer.json

@@ -5,12 +5,8 @@
   "license": "Apache-2.0",
   "authors": [
     {
-      "name": "Nils Destoop",
-      "email": "nils.destoop@wunderkraut.com"
-    },
-    {
-      "name": "Stijn Swaanen",
-      "email": "stijn.swaanen@publiq.be"
+      "name": "publiq vzw",
+      "email": "info@publiq.be"
     }
   ],
   "minimum-stability": "dev",
@@ -25,15 +21,14 @@
     "guzzlehttp/guzzle": "~6.0",
     "jms/serializer": "~1.9",
     "simple-bus/jms-serializer-bridge": "^1.0",
-    "indigophp/doctrine-annotation-autoload": "^0.1.0",
-    "jwage/purl": "^0.0.10"
+    "indigophp/doctrine-annotation-autoload": "^0.1.0"
   },
   "require-dev": {
-    "escapestudios/symfony2-coding-standard": "~2.0",
-    "phpunit/phpunit": "~5.7",
+    "phpunit/phpunit": "~7.5",
     "squizlabs/php_codesniffer": "2.6.1",
-    "phing/phing": "~2.10",
-    "satooshi/php-coveralls": "~0.7",
-    "mikey179/vfsstream": "~1.6.2"
+    "phing/phing": "~2.10"
+  },
+  "scripts": {
+    "phing": "./vendor/bin/phing test"
   }
 }

src/Parameter/AbstractDateParameter.php

@@ -2,27 +2,29 @@
 
 namespace CultuurNet\SearchV3\Parameter;
 
+use DateTimeInterface;
+use InvalidArgumentException;
+
 abstract class AbstractDateParameter extends AbstractParameter
 {
-    /**
-     * Formats the date.
-     * @param $date
-     * @return string
-     */
-    protected function formatDate($date)
+    final public function __construct(DateTimeInterface $dateTime)
     {
-        return $date->format(\DateTime::ATOM);
+        $this->value = $dateTime->format(DATE_ATOM);
     }
 
-    /**
-     * {@inheritdoc}
-     */
-    public function getValue()
+    public static function createFromAtomString(string $value): self
     {
-        if ($this->value instanceof \DateTime) {
-            return $this->formatDate($this->value);
-        } else {
-            return $this->value;
+        $dateTime = \DateTimeImmutable::createFromFormat(DATE_ATOM, $value);
+        if ($dateTime === false) {
+            throw new InvalidArgumentException('Could not parse ' . $value . ' as a date in the atom format');
         }
+        return new static($dateTime);
+    }
+
+    public static function wildcard(): self
+    {
+        $parameter = new static(new \DateTimeImmutable());
+        $parameter->value = '*';
+        return $parameter;
     }
 }

src/Parameter/AbstractParameter.php

@@ -4,13 +4,8 @@
 
 use CultuurNet\SearchV3\ParameterInterface;
 
-/**
- * Provides an abstract class for query parameters.
- * @package CultuurNet\SearchV3
- */
 abstract class AbstractParameter implements ParameterInterface
 {
-
     /**
      * The key to use in the query string
      * @var string
@@ -19,23 +14,22 @@ abstract class AbstractParameter implements ParameterInterface
 
     /**
      * The value to use.
-     * @var string
+     * @var string|array|integer|float|bool
      */
     protected $value;
 
-    /**
-     * {@inheritdoc}
-     */
-    public function getKey()
+    public function getKey(): string
     {
         return $this->key;
     }
 
-    /**
-     * {@inheritdoc}
-     */
     public function getValue()
     {
         return $this->value;
     }
+
+    public function allowsMultiple(): bool
+    {
+        return false;
+    }
 }

src/Parameter/AddressCountry.php

@@ -2,18 +2,9 @@
 
 namespace CultuurNet\SearchV3\Parameter;
 
-/**
- * Provides a parameters to search on addressCountry.
- */
-
-class AddressCountry extends AbstractParameter
+final class AddressCountry extends AbstractParameter
 {
-
-    /**
-     * AddressCountry constructor.
-     * @param $addressCountry
-     */
-    public function __construct($addressCountry)
+    public function __construct(string $addressCountry)
     {
         $this->value = $addressCountry;
         $this->key = 'addressCountry';

src/Parameter/AudienceType.php

@@ -2,21 +2,13 @@
 
 namespace CultuurNet\SearchV3\Parameter;
 
-/**
- * Provides a parameter to search on audienceType.
- */
-class AudienceType extends AbstractParameter
+final class AudienceType extends AbstractParameter
 {
+    public const AUDIENCE_EVERYONE = 'everyone';
+    public const AUDIENCE_MEMBERS = 'members';
+    public const AUDIENCE_EDUCATION = 'education';
 
-    const AUDIENCE_EVERYONE = 'everyone';
-    const AUDIENCE_MEMBERS = 'members';
-    const AUDIENCE_EDUCATION = 'education';
-
-    /**
-     * AudienceType constructor.
-     * @param $audienceType
-     */
-    public function __construct($audienceType)
+    public function __construct(string $audienceType)
     {
         $this->value = $audienceType;
         $this->key = 'audienceType';

src/Parameter/AvailableFrom.php

@@ -2,19 +2,7 @@
 
 namespace CultuurNet\SearchV3\Parameter;
 
-/**
- * Provides a parameter to search on availableFrom.
- */
-class AvailableFrom extends AbstractDateParameter
+final class AvailableFrom extends AbstractDateParameter
 {
-
-    /**
-     * AvailableFrom constructor.
-     * @param \DateTime|string $availableFrom
-     */
-    public function __construct($availableFrom)
-    {
-        $this->value = $availableFrom;
-        $this->key = 'availableFrom';
-    }
+    protected $key = 'availableFrom';
 }

src/Parameter/AvailableTo.php

@@ -2,19 +2,7 @@
 
 namespace CultuurNet\SearchV3\Parameter;
 
-/**
- * Provides a parameter to search on availableTo.
- */
-class AvailableTo extends AbstractDateParameter
+final class AvailableTo extends AbstractDateParameter
 {
-
-    /**
-     * AvailableTo constructor.
-     * @param \DateTime|string $availableTo
-     */
-    public function __construct($availableTo)
-    {
-        $this->value = $availableTo;
-        $this->key = 'availableTo';
-    }
+    protected $key = 'availableTo';
 }