Merge branch 'develop'

Author: Bruno

.gitignore

@@ -4,3 +4,4 @@ composer.phar
 .DS_Store
 node_modules
 file.wav
+test.php

README.md

@@ -1,229 +1,35 @@
 # Recast.AI - SDK PHP
 
-[logo]: https://github.com/RecastAI/SDK-NodeJs/blob/master/misc/logo-inline.png "Recast.AI"
+[logo]: https://github.com/RecastAI/SDK-PHP/blob/develop/misc/logo-inline.png "Recast.AI"
 
 ![alt text][logo]
 
 Recast.AI official SDK in PHP
 
 ## Synospis
 
-This module is a PHP interface to the [Recast.AI](https://recast.ai) API. It allows you to make request to your bots
+This module is a wrapper around the [Recast.AI](https://recast.ai) API, and allows you to:
+* [build a bot](https://github.com/RecastAI/SDK-PHP/wiki/Build-your-bot)
+* [analyze your text](https://github.com/RecastAI/SDK-PHP/wiki/Analyse-text)
 
 ## Installation
 
 ```bash
 composer require recastai/sdk-php
 ```
 
-## Usage
+## Documentation
 
-
-```php
-<?php
-use client\Client;
-
-require 'client.php';
-
-$client = new Client(YOUR_TOKEN, YOUR_LANGUAGE);
-
-$res = $client->textRequest(YOUR_TEXT);
-YOUR_INTENT = $res->intent();
-// Do your code...
-
-?>
-```
+You can find the full documentation [here](https://github.com/RecastAI/SDK-PHP/wiki).
 
 ## Specs
 
-### Classes
-
-This module contains 4 classes, as follows:
-
-* Client is the client allowing you to make requests.
-* Response contains the response from [Recast.AI](https://recast.ai).
-* Entity represents an entity found by Recast.AI in your user's input.
-* RecastError is the error returned by the module.
-
-Don't hesitate to dive into the code, it's commented ;)
-
-## class Client
-
-The Client can be instanciated with a token and a language (both optional).
-
-```php
-$client = new Client(YOUR_TOKEN, YOUR_LANGUAGE);
-```
-
-__Your tokens:__
-
-[token]: https://github.com/RecastAI/SDK-NodeJs/blob/master/misc/recast-ai-tokens.png "Tokens"
-
-![alt text][token]
-
-*Copy paste your request access token from your bot's settings.*
-
-__Your language__
-
-```php
-$client = new Client(YOUR_TOKEN, 'en');
-```
-*The language is a lowercase 639-1 isocode.*
-
-## Text Request
-
-textRequest(text, options = { token: YOUR_TOKEN, language: YOUR_LANGUAGE, proxy: YOUR_URL_PROXY })
-
-If your pass a token or a language in the options parameter, it will override your default client language or token.
-You can pass a proxy url in the options if needed.
-
-```php
-$res = $client->textRequest(YOUR_TEXT);
-// Do your code...¯
-
-})
-```
-
-```php
-// With optional parameters
-
-$options = array('language' => 'YOUR_LANGUAGE', 'token' => 'YOUR_TOKEN');
-
-$res = $client->textRequest(YOUR_TEXT, $options);  
-
-// Do your code...
-
-```
-
-__If a language is provided:__ the language you've given is used for processing if your bot has expressions for it, else your bot's primary language is used.
-
-__If no language is provided:__ the language of the text is detected and is used for processing if your bot has expressions for it, else your bot's primary language is used for processing.
-
-## File Request
-
-fileRequest(file, callback, options = { token: YOUR_TOKEN, language: YOUR_LANGUAGE, proxy: YOUR_PROXY_URL })
-
-If your pass a token or a language in the options parameter, it will override your default client language or token.
-You can pass a proxy url in the options if needed.
-
-__file format: .wav__
-
-```php
-$res = $client->fileRequest('myFile.wav');
-
-// Do your code...
-
-})
-```
-
-```php
-$options = array('language' => 'en', 'token' => YOUR_TOKEN);
-
-$res = $client->fileRequest('myFile.wav', $options);
-  // Do your code...
-
-```
-
-__If a language is provided:__
-Your bot's primary language is used for processing as we do not provide language detection for speech.
-
-__If no language is provided:__
-The language you've given is used for processing if your bot has expressions for it, else your bot's primary language is used
-
-## class Response
-
-The Response is generated after a call to either fileRequest or textRequest.
-
-### Get the first detected intent
-
-| Method        | Params | Return                    |
-| ------------- |:------:| :-------------------------|
-| intent()      |        | the first detected intent |
-
-```php
-$res = $client->textRequest($text);
-$lol = $res->intent();
-
-if ($result->slug == 'weather') {
-  // Do your code...
-}
-
-```
-
-### Get one entity
-
-| Method        | Params        | Return                    |
-| ------------- |:-------------:| :-------------------------|
-| get(name)     | name: String  | the first Entity matched  |
-
-
-```php
-$res = $client->textRequest($text);
-
-$result = $res->get('location');
-
-```
-
-### Get all entities matching name
-
-| Method        | Params        | Return                    |
-| ------------- |:-------------:| :-------------------------|
-| all(name)     | name: String  | all the Entities matched  |
-
-
-```php
-$res = $client->textRequest($text);
-
-$lol = $res->all('location');
-
-```
-
-### Getters
-
-Each of the following methods corresponds to a Response attribute
-
-| Method      | Params | Return                                              |
-| ----------- |:------:| :---------------------------------------------------|
-| raw         |        | String: the raw unparsed json response              |
-| source      |        | String: the user input                              |
-| intents     |        | Array[object]: all the matched intents              |
-| sentences   |        | Array[Sentence]: all the detected sentences         |
-| version     |        | String: the version of the json                     |
-| timestamp   |        | String: the timestamp at the end of the processing  |
-| status      |        | String: the status of the response                  |
-| type        |        | String: the type of the response                    |
-
-
-## class Entity
-
-The Entity is generated by the Sentence constructor.
-
-### Getters
-
-Each of the following methods corresponds to a Response attribute
-
-| Attributes  | Description                                                   |
-| ----------- |:--------------------------------------------------------------|
-| name        | String: the name of the entity                                |
-| raw         | String: the unparsed json value of the entity                 |
-
-In addition to those methods, more attributes are generated depending of the nature of the entity.
-The full list can be found there: [man.recast.ai](https://man.recast.ai/#list-of-entities)
-
-```php
-$res = $client->textRequest($text);
-
-$result = $res->get('location');
-
-var_dump($result->slug);
-var_dump($result->raw);
-```
-
-## class RecastError
-
-The Recast.AI Error is thrown when receiving an non-200 response from Recast.AI.
+This module contains 5 classes, as follows:
 
-As it inherits from Error, it implements the default Error methods.
+* [Client](https://github.com/RecastAI/SDK-PHP/wiki/Class-Client) is the client allowing you to make requests.
+* [Conversation](https://github.com/RecastAI/SDK-PHP/wiki/Class-Conversation) wraps the response from a call to [Recast.AI](https://recast.ai) API with the textConverse Client method.
+* [Response](https://github.com/RecastAI/SDK-PHP/wiki/Class-Response) wraps the response from a call to [Recast.AI](https://recast.ai) API with the textRequest or fileRequest Client methods.
+* [Entity](https://github.com/RecastAI/SDK-PHP/wiki/Class-Entity) represents an entity extracted from an input.
 
 ## More
 

composer.json

@@ -11,7 +11,7 @@
   "minimum-stability": "dev",
   "require": {
     "php": "^5.3.3 || ^7.0",
-    "rmccue/requests": "dev-master",
+    "rmccue/requests": "^1.6.1",
     "guzzlehttp/guzzle": "^6.2@dev"
   },
   "require-dev": {

misc/logo-inline.png

@@ -6,9 +6,11 @@
 use response;
 use Requests;
 use constants;
+use conversation;
 
 require 'constants.php';
 require 'response.php';
+require 'conversation.php';
 
 class Client
 {
@@ -29,9 +31,9 @@ public  function __construct($token=null, $language=null)
    */
   public function textRequest($text, $options=null)
   {
-    if (!$options) {
+    if ($options === null) {
       $token = $this->token;
-    } else {
+    } else if (array_key_exists('token', $options)) {
       $token = $options['token'];
     }
 
@@ -45,11 +47,9 @@ public function textRequest($text, $options=null)
       return('Token is missing');
     } else {
       $headers = array('Content-Type' => 'application/json', 'Authorization' => "Token " . $token);
-      $response = file_get_contents("test.json");
 
       $res = $this->requestPrivate(constants\Constants::API_ENDPOINT, $headers, $params);
-      // return ($res);
-      return(new response\Response($response));
+      return(new response\Response($res));
     }
   }
 
@@ -94,9 +94,9 @@ protected function requestFilePrivate($url, $params) {
    */
   public  function fileRequest($file, $options=null)
   {
-    if (!$options) {
+    if ($options === null) {
       $token = $this->token;
-    } else {
+    } else if (array_key_exists('token', $options)) {
       $token = $options['token'];
     }
 
@@ -118,7 +118,6 @@ public  function fileRequest($file, $options=null)
             ],
           ]
         ];
-        $res = $this->requestFilePrivate($url, $params);
       } else {
         $params = [
           'headers' => [
@@ -136,10 +135,31 @@ public  function fileRequest($file, $options=null)
             ],
           ]
         ];
-        $res = $this->requestFilePrivate($url, $params);
       }
-       $body = (string) $res->getBody();
-       return(new response\Response($body));
+      $res = $this->requestFilePrivate($url, $params);
+       return(new response\Response($res));
+    }
+  }
+  public function textConverse($text, $conversation_token=null, $options=null) {
+    if ($options === null) {
+      $token = $this->token;
+    } else if ($options['token']) {
+      $token = $options['token'];
+    }
+
+    if ($this->language) {
+      $params = array('text' => $text, 'language' => $this->language, 'conversation_token' => $conversation_token);
+    } else {
+      $params = array('text' => $text, 'conversation_token' => $conversation_token);
+    }
+
+    if (!$token) {
+      return('Token is missing');
+    } else {
+      $headers = array('Content-Type' => 'application/json', 'Authorization' => "Token " . $token);
+      $res = $this->requestPrivate(constants\Constants::API_ENDPOINT_CONVERSATION, $headers, $params);
+
+      return(new conversation\Conversation(($res)));
     }
   }
 }

misc/recast-ai-tokens.png

@@ -4,7 +4,8 @@
 
 class Constants
 {
-    const API_ENDPOINT = 'https://api.recast.ai/v1/request';
+    const API_ENDPOINT = 'https://api.recast.ai/v2/request';
+    const API_ENDPOINT_CONVERSATION = 'https://api.recast.ai/v2/converse';
 
     const ACT_ASSERT = 'assert';
     const ACT_COMMAND = 'command';