Add support for custom interaction type and their attributes (#107)

README.md

@@ -1,3 +1,4 @@
+
 # PHP API Client for Matej recommendation engine
 
 [![Latest Stable Version](https://img.shields.io/packagist/v/lmc/matej-client.svg?style=flat-square)](https://packagist.org/packages/lmc/matej-client)
@@ -8,7 +9,7 @@
 
 This library requires PHP 7.1+. However, we provide also PHP 5.6-compatible version [`matej-client-php5`](https://github.com/lmc-eu/matej-client-php5).
 
-Please note the PHP 5.6 version is just transpiled copy of this library - examples, pull requests, issues, changelog etc. are placed in this repository.
+Please note that the PHP 5.6 version is just transpiled copy of this library - examples, pull requests, issues, changelog etc. are placed in this repository.
 
 ## Installation
 
@@ -41,8 +42,7 @@ $ composer require lmc/matej-client php-http/curl-client guzzlehttp/psr7 # use l
 
 ## Usage
 
-To start using Matej you will need your account id (database name) and secret API key - both of them must be obtained
-from LMC R&D team.
+To start using Matej you will need your account id (database name) and secret API key - both of them must be obtained from LMC R&D team.
 
 First create an instance of `Matej` object:
 ```php
@@ -61,7 +61,7 @@ Once finished with building the request, use `send()` method to execute it and r
 ```php
 $response = $matej->request()
     ->events()
-    ->addInteraction(\Lmc\Matej\Model\Command\Interaction::purchase('user-id', 'item-id'))
+    ->addInteraction(\Lmc\Matej\Model\Command\Interaction::withItem('purchases', 'user-id', 'item-id'))
     ->addUserMerge(...)
     ...
     ->send();
@@ -155,7 +155,7 @@ $matej = new Matej('accountId', 'apikey');
 $response = $matej->request()
     ->events()
     // Add interaction between user and item
-    ->addInteraction(Interaction::purchase('user-id', 'item-id'))
+    ->addInteraction(Interaction::withItem('purchases', 'user-id', 'item-id'))
     ->addInteractions([/* array of Interaction objects */])
     // Update item data
     ->addItemProperty(ItemProperty::create('item-id', ['valid_from' => time(), 'title' => 'Title']))
@@ -183,7 +183,7 @@ $matej = new Matej('accountId', 'apikey');
 
 $response = $matej->request()
     ->recommendation(UserRecommendation::create('user-id', 'test-scenario'))
-    ->setInteraction(Interaction::purchase('user-id', 'item-id')) // optional
+    ->setInteraction(Interaction::withItem('purchases', 'user-id', 'item-id')) // optional
     ->setUserMerge(UserMerge::mergeInto('user-id', 'source-id')) // optional
     ->send();
 
@@ -232,7 +232,7 @@ $recommendations = $response->getRecommendation()->getData();
 // }
 ```
 
-You can further modify which items will be reccomended by providing boosting rules. Priority of items matching the
+You can further modify which items will be recommended by providing boosting rules. Priority of items matching the
 MQL `$criteria` will be multiplied by the value of `multiplier`:
 
 ```php
@@ -277,7 +277,7 @@ $recommendedItems = $response->getRecommendation()->getData();
 ```
 
 If you don't specify any response properties, Matej will return an array of `stdClass` instances, which contain only `item_id` property.
-If you do request at least one response property, you don't need to metion `item_id`, as Matej will always return it regardless of the
+If you do request at least one response property, you don't need to mention `item_id`, as Matej will always return it regardless of the
 properties requested.
 
 If you request an unknown property, Matej will return a `BAD REQUEST` with HTTP status code `400`.
@@ -296,7 +296,7 @@ $matej = new Matej('accountId', 'apikey');
 
 $response =  $matej->request()
     ->sorting(Sorting::create('user-id', ['item-id-1', 'item-id-2', 'item-id-3']))
-    ->setInteraction(Interaction::purchase('user-id', 'item-id')) // optional
+    ->setInteraction(Interaction::withItem('purchases', 'user-id', 'item-id')) // optional
     ->setUserMerge(UserMerge::mergeInto('user-id', 'source-id')) // optional
     ->send();
 
@@ -342,7 +342,7 @@ $response = $matej->request()
 
 ### A/B Testing support
 `Recommendation` and `Sorting` commands support optional A/B testing of various models. This has to be set up in Matej first,
-but once available, you can specify which model you want to use when requesting recommendations or sortings.
+but once available, you can specify which model you want to use when requesting recommendations or sorting.
 
 This is available for `recommendation`, `sorting` and `campaign` requests:
 
@@ -373,7 +373,7 @@ $response = $matej->request()
 
 If you don't provide any model name, the request will be sent without it, and Matej will use default model for your instance.
 
-Typically, you'd select a random sample of users, to which you'd present recommendations and sortings from second model. This way, implementation
+Typically, you'd select a random sample of users, to which you'd present recommendations and sorting from second model. This way, implementation
 in your code should look similar to this:
 
 ```php

UPGRADE-3.0.md

@@ -1,13 +1,19 @@
+
 # Upgrading from 2.x to 3.0
 
-API client release 2.0 contains few backward incompatible changes.
+API client release 3.0 contains few backward incompatible changes.
 
 This guide will help you upgrade your codebase.
 
-## `UserRecommendation::create()` now accepts only `$user_id` and `$scenario` 
-`UserReccomentation::create()` accepts only two argumens: `$user_id` and `$scenario`.
-Both are arguments are required. Reccomendation command can be further parametrized
-using fluent API.
+## `UserRecommendation::create()` now accepts only `$userId` and `$scenario` 
+`UserReccomentation::create()` accepts only two arguments: `$user_id` and `$scenario`.
+
+Both arguments are required. 
+
+All other arguments can be now set using new setters and are optional:
+- `setCount(int $count)`
+- `setRotationRate(float $rotationRate)`
+- `setRotationTime(int $rotationTime)`
 
 #### Before
 ```php
@@ -29,4 +35,76 @@ $recommendation = UserRecommendation::create('user-id', 'scenario');
 $recommendation->setCount(5);
 $recommendation->setRotationRate(1.0);
 $recommendation->setRotationTime(3600);
+```
+
+## `Interaction` now accepts interaction type as parameter
+Matej now allows configuration of custom interaction types and interaction attributes.
+
+At the same time, it allows specifying interaction item using item alias instead
+of item ID. For that reason we removed static constructor methods for creating specific interaction types - `Interaction::detailView`, `Interaction::purchase`, `Interaction::bookmark` and `Interaction::rating`.
+
+We replaced them with constructors for creating Interaction based on `$itemId` or `$itemIdAlias`:
+
+```php
+Interaction::withItem(
+	string $interactionType,
+	string $userId,
+	string $itemId,
+	int $timestamp = null
+```
+
+```php
+Interaction::withAliasedItem(
+	string $interactionType,
+	string $userId,
+	array $itemIdAlias,
+	int $timestamp = null):
+```
+
+The first argument is always a string representing interaction type. Consult the table bellow to find out the correct value to fill in:
+
+| Before: constructor method   | After: argument $interactionType |
+|------------------------------|----------------------------------|
+| `Interaction::detailView`    | `"detailviews"`                  |
+| `Interaction::purchase`      | `"purchases"`                    |
+| `Interaction::bookmark`      | `"bookmarks"`                    |
+| `Interaction::rating`        | `"ratings"`                      |
+
+> To request new interaction types, please contact Matej support.
+
+#### Before
+```php
+$interaction = Interaction::bookmark('user-id', 'item_id', time());
+```
+
+#### After
+```php
+$interaction = Interaction::withItem('bookmarks', 'user-id', 'item_id', time());
+```
+> Argument `$timestamp` remains optional.
+
+## `Interaction` command supports custom attributes
+Interactions now support custom attributes. These can be added using fluent API
+methods `setAttribute()` and `setAttributes()`.
+
+Argument `value` was removed from constructor methods and has to be set using new attribute methods. Its real name might have change as well. For example, for interaction type `bookmarks`, it was renamed to `stars`.
+
+**Attribute `context` is no longer supported and was removed.**
+
+#### Before
+```php
+$interaction = Interaction::rating('user-id', 'item_id', 0.5);
+```
+
+#### After
+```php
+$interaction = Interaction::create('ratings', 'user-id', 'item_id')
+				->setAttribute('stars', 0.5)
+```
+
+which is equivalent to
+
+```php
+$interaction = Interaction::create('ratings', 'user-id', 'item_id')
+$interaction->setAttribute('stars', 0.5)
 ```

phpstan.neon

@@ -4,8 +4,6 @@ parameters:
           path: tests/
         - message: '#Parameter .+ of class Lmc\\Matej\\Matej constructor expects string#'
           path: tests/integration/IntegrationTestCase.php
-        - message: '#Parameter .+ of function forward_static_call_array#'
-          path: tests/unit/Model/Command/InteractionTest.php
         - message: '#Parameter \#4 \$body of method Http\\Message\\RequestFactory::createRequest\(\) expects#'
           path: src/Http/RequestManager.php
         - '#Unsafe usage of new static\(\)#'