Added Client::setEncoding() and associated tests

Author: vaites

README.md

@@ -13,7 +13,7 @@ from documents, images and other formats.
 
 The following modes are supported:
 * **App mode**: run app JAR via command line interface
-* **Server mode**: make HTTP requests to [JSR 311 network server](http://wiki.apache.org/tika/TikaJAXRS)
+* **Server mode**: make HTTP requests to [JSR 311 network server](https://cwiki.apache.org/confluence/display/TIKA/TikaServer)
 
 Server mode is recommended because is 5 times faster, but some shared hosts don't allow run processes in background.
 
@@ -144,6 +144,12 @@ $client->getAvailableDetectors();
 $client->getAvailableParsers();
 $client->getVersion();
 ```
+
+Encoding methods:
+```php
+$client->getEncoding();
+$client->setEncoding('UTF-8');
+```
 
 Supported versions related methods:
 
@@ -219,6 +225,26 @@ $client->setTimeout($seconds);
 $client->getTimeout();
 ```
 
+## Troubleshooting
+
+### Empty responses or unexpected results
+
+This library is only a _proxy_ so if you get an empy responses or unexpected results the most common cause is Tika 
+itself. A simple test is using the GUI to check the response:
+
+1. Run the Tika app without arguments: `java -jar tika-app-x.xx.jar` 
+2. Drop your file or select it using _File -> Open_
+3. Wait until the metadata appears
+4. Get the text or HTML using _View_ menu
+
+If the results are the same, you must take a look into [Tika's Jira](https://issues.apache.org/jira/projects/TIKA/issues)
+and open an issue if necessary.
+
+### Encoding
+
+By default the returned text is encoded with UTF-8 but there are some issues with the encoding when using the app mode.
+The `Client::setEncoding()` method allows to set the expected encoding (this will be fixed in the upcoming 1.0 release). 
+
 ## Tests
 
 Tests are designed to **cover all features for all supported versions** of Apache Tika in app mode and server mode. 
@@ -229,8 +255,10 @@ There are a few samples to test against:
 * **sample3**: text recognition
 * **sample4**: unsupported media
 * **sample5**: huge text for callbacks 
+* **sample6**: remote calls 
+* **sample7**: text encoding
 
-## Issues
+## Known issues
 
 There are some issues found during tests, not related with this library:
 

samples/sample7.doc

@@ -58,6 +58,13 @@ abstract class Client
      */
     protected $cache = [];
 
+    /**
+     * Text encoding
+     *
+     * @var \Closure
+     */
+    protected $encoding = null;
+
     /**
      * Callback called on secuential read
      *
@@ -130,6 +137,30 @@ public static function prepare($param1 = null, $param2 = null, $options = [])
         return self::make($param1, $param2, $options, false);
     }
 
+    /**
+     * Get the encoding
+     *
+     * @return  \Closure|null
+     */
+    public function getEncoding()
+    {
+        return $this->encoding;
+    }
+
+    /**
+     * Set the encoding
+     *
+     * @param   string   $encoding
+     * @return  $this
+     * @throws  \Exception
+     */
+    public function setEncoding($encoding)
+    {
+        $this->encoding = $encoding;
+
+        return $this;
+    }
+
     /**
      * Get the callback
      *
@@ -144,6 +175,7 @@ public function getCallback()
      * Set the callback (callable or closure) for call on secuential read
      *
      * @param   mixed   $callback
+     * @param   bool    $append
      * @return  $this
      * @throws  \Exception
      */

samples/sample7.pdf

@@ -247,8 +247,8 @@ public function exec($command)
      */
     protected function getArguments($type, $file = null)
     {
-        // parameters for command
-        $arguments = [];
+        $arguments = $this->encoding ? ["--encoding={$this->encoding}"] : [];
+
         switch($type)
         {
             case 'html':

src/Client.php

@@ -597,6 +597,35 @@ public function testDirectRemoteDocumentText($file)
         }
     }
 
+    /**
+     * Encoding tests
+     *
+     * @dataProvider    encodingProvider
+     *
+     * @param   string $file
+     * @throws  \Exception
+     */
+    public function testEncodingDocumentText($file)
+    {
+        $client =& self::$client;
+
+        if($client::MODE == 'web' && version_compare(self::$version, '1.9') == 0)
+        {
+            $this->markTestSkipped('Apache Tika 1.9 throws random "Error while processing document" errors');
+        }
+        else
+        {
+            //$client->setEncoding('UTF-8');
+
+            $this->assertThat($client->getText($file), $this->logicalAnd
+            (
+                $this->stringContains('L’espéranto'),
+                $this->stringContains('世界語'),
+                $this->stringContains('Эспера́нто')
+            ));
+        }
+    }
+
     /**
      * Test available detectors
      *
@@ -690,6 +719,16 @@ public function remoteProvider()
         ];
     }
 
+    /**
+     * File provider for encoding testing
+     *
+     * @return array
+     */
+    public function encodingProvider()
+    {
+        return $this->samples('sample7');
+    }
+
     /**
      * File provider using "samples" folder
      *