Merge pull request #1 from eclipxe13/improvements

Versión 0.2.0

CONTRIBUTING.md

@@ -79,7 +79,7 @@ composer dev:test
 composer dev:build
 ```
 
-# Ejecutar GitHub Actions localmente
+## Ejecutar GitHub Actions localmente
 
 Puedes utilizar la herramienta [`act`](https://github.com/nektos/act) para ejecutar las GitHub Actions localmente.
 Según [`actions/setup-php-action`](https://github.com/marketplace/actions/setup-php-action#local-testing-setup)

README.md

@@ -55,7 +55,7 @@ y que la imagen del captcha se encuentra como imagen embedida y su contenido en
 
 use PhpCfdi\ImageCaptchaResolver\CaptchaImage;
 use PhpCfdi\ImageCaptchaResolver\CaptchaResolverInterface;
-use PhpCfdi\ImageCaptchaResolver\UnableToResolveCaptcha;
+use PhpCfdi\ImageCaptchaResolver\UnableToResolveCaptchaException;
 
 /**
  * @var string $theImgElementSrcAtributte
@@ -66,7 +66,7 @@ $image = CaptchaImage::newFromInlineHtml($theImgElementSrcAtributte);
 
 try {
     $answer = $resolver->resolve($image);
-} catch (UnableToResolveCaptcha $exception) {
+} catch (UnableToResolveCaptchaException $exception) {
     echo 'No se pudo resolver el captcha', PHP_EOL;
     return;
 }
@@ -142,8 +142,49 @@ $resolverConstructed = new CaptchaLocalResolver(
 );
 ```
 
+### Creación de un resolvedor de captchas basado en línea de comandos
+
+La implementación dependerá siempre de la herramienta que se esté utilizando, es probable que fabrique
+su propio punto de entrada a la herramienta para que devuelva el *exit code* correcto y la respuesta.
+
+Esta herramienta podría ser útil en caso de que el captcha se pueda resolver utilizando alguna herramienta
+como [`tesseract`](https://github.com/tesseract-ocr/tesseract).
+
+El siguiente ejemplo supone que tiene la imagen del captcha a resolver en `$image` y que existe un commando
+llamado `my-captcha-breaker` que se le entrega una imagen y devuelve en el último renglón de la salida
+la respuesta del captcha.
+
+```php
+<?php declare(strict_types=1);
+
+use PhpCfdi\ImageCaptchaResolver\CaptchaImageInterface;
+use PhpCfdi\ImageCaptchaResolver\Resolvers\CommandLineResolver;
+use PhpCfdi\ImageCaptchaResolver\UnableToResolveCaptchaException;
+
+/**
+ * @var CaptchaImageInterface $image 
+ */
+
+$resolver = CommandLineResolver::create(explode(' ', 'my-captcha-breaker --in {file} --stdout'));
+
+try {
+    $answer = $resolver->resolve($image);
+} catch (UnableToResolveCaptchaException $exception) {
+    echo 'No se pudo resolver el captcha: ', $exception->getMessage(), PHP_EOL;
+    return;
+}
+
+echo $answer, PHP_EOL;
+```
+
 ## Resolvedores
 
+### Multiresolvedor
+
+El resolvedor `MultiResolver` es en sí mismo un resolvedor que intenta resolver el captcha usando un conjunto
+predefinido de resolvedores. Podría ser útil para intentar resolver utilizando diferentes estrategias
+o reintentando con un mismo resolvedor el número de veces en las que esté incluído.
+
 ### Resolvedores para pruebas
 
 El resolvedor `CaptchaLocalResolver` usa servicio de resolución de captchas local y es comúnmente utilizado para pruebas.
@@ -154,7 +195,7 @@ ejecutando el proceso. Solo es útil si puede escribir la respuesta. Si no se re
 en un tiempo predeterminado el resolvedor fallará lo tomará como una respuesta vacía.
 
 Si está haciendo pruebas unitarias, la mejor alternativa es usar el resolvedor `MockResolver`, que se construye
-con respuestas prestablecidas `CaptchaAnswerInterface` o excepciones `UnableToResolveCaptcha` y falla con una
+con respuestas prestablecidas `CaptchaAnswerInterface` o excepciones `UnableToResolveCaptchaException` y falla con una
 excepción `OutOfRangeException` si se le pide una respuesta y ya no tiene más.
 
 ### Nuevos resolvedores

composer.json

@@ -27,7 +27,11 @@
         "vlucas/phpdotenv": "^5.3",
         "guzzlehttp/guzzle": "^7.3",
         "guzzlehttp/psr7": "^2.0",
-        "php-http/guzzle7-adapter": "^1.0"
+        "php-http/guzzle7-adapter": "^1.0",
+        "symfony/process": "^5.3"
+    },
+    "suggest": {
+        "symfony/process": "To implement recommended CommandLineResolver"
     },
     "autoload": {
         "psr-4": {

docs/CHANGELOG.md

@@ -4,7 +4,21 @@
 
 Utilizamos [Versionado Semántico 2.0.0](SEMVER.md).
 
-## Versión 0.1.0
+## Versión 0.2.0 2021-07-28
+
+Se agrega el resolvedor `CommandLineResolver` que pasa la imagen del captcha como un archivo temporal
+para ser resuelto por un commando externo.
+
+Se agrega el resolvedor `MultiResolver` que contiene un conjunto de resolvedores para intentar resolver
+con ellos uno a uno.
+
+Se cambia el nombre de la excepción `UnableToResolveCaptcha` a `UnableToResolveCaptchaException`.
+
+Se cambia el nombre de la excepción `UndiscoverableClient` a `UndiscoverableClientException`.
+
+Se agrega la clase interna `TemporaryFile` para crear y eliminar archivos temporales.
+
+## Versión 0.1.0 2021-07-26
 
 Versión inicial, implementa los siguientes resolvedores:
 

src/CaptchaResolverInterface.php

@@ -12,7 +12,7 @@ interface CaptchaResolverInterface
      *
      * @param CaptchaImageInterface $image
      * @return CaptchaAnswerInterface
-     * @throws UnableToResolveCaptcha
+     * @throws UnableToResolveCaptchaException
      */
     public function resolve(CaptchaImageInterface $image): CaptchaAnswerInterface;
 }

src/HttpClient/HttpClient.php

@@ -39,7 +39,7 @@ public function __construct(
     /**
      * Create the object with discovered PSR http client, PSR request factory and PSR stream factory
      *
-     * @throws UndiscoverableClient
+     * @throws UndiscoverableClientException
      */
     public static function discover(): self
     {
@@ -49,9 +49,11 @@ public static function discover(): self
                 Psr17FactoryDiscovery::findRequestFactory(),
                 Psr17FactoryDiscovery::findStreamFactory()
             );
+            // @codeCoverageIgnoreStart
         } catch (Throwable $exception) {
-            throw new UndiscoverableClient('Cannot discover the HttpClient', $exception);
+            throw new UndiscoverableClientException($exception);
         }
+        // @codeCoverageIgnoreEnd
     }
 
     /**

src/HttpClient/UndiscoverableClientException.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpCfdi\ImageCaptchaResolver\HttpClient;
+
+use RuntimeException;
+use Throwable;
+
+class UndiscoverableClientException extends RuntimeException
+{
+    public function __construct(Throwable $previous)
+    {
+        parent::__construct('Cannot discover the HttpClient', 0, $previous);
+    }
+}

src/Internal/TemporaryFile.php

@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpCfdi\ImageCaptchaResolver\Internal;
+
+use RuntimeException;
+
+/**
+ * Class to create a temporary file and remove it on object destruction
+ * @internal
+ */
+final class TemporaryFile
+{
+    /** @var string */
+    private $path;
+
+    public function __construct(string $prefix = '', string $directory = '')
+    {
+        $tempnam = tempnam($directory, $prefix);
+        if (false === $tempnam) {
+            /** @noinspection PhpUnhandledExceptionInspection */
+            throw new RuntimeException('Unable to create a temporary file'); // @codeCoverageIgnore
+        }
+        $this->path = $tempnam;
+    }
+
+    public function __destruct()
+    {
+        if (file_exists($this->path)) {
+            /** @noinspection PhpUsageOfSilenceOperatorInspection */
+            @unlink($this->path);
+        }
+    }
+
+    public function getPath(): string
+    {
+        return $this->path;
+    }
+
+    public function getContents(): string
+    {
+        return file_get_contents($this->path) ?: '';
+    }
+
+    public function putContents(string $data): void
+    {
+        file_put_contents($this->path, $data);
+    }
+}

src/Resolvers/AntiCaptchaResolver.php

@@ -8,11 +8,11 @@
 use PhpCfdi\ImageCaptchaResolver\CaptchaAnswerInterface;
 use PhpCfdi\ImageCaptchaResolver\CaptchaImageInterface;
 use PhpCfdi\ImageCaptchaResolver\CaptchaResolverInterface;
-use PhpCfdi\ImageCaptchaResolver\HttpClient\UndiscoverableClient;
+use PhpCfdi\ImageCaptchaResolver\HttpClient\UndiscoverableClientException;
 use PhpCfdi\ImageCaptchaResolver\Resolvers\AntiCaptchaResolver\AntiCaptchaConnector;
 use PhpCfdi\ImageCaptchaResolver\Timer\Timer;
 use PhpCfdi\ImageCaptchaResolver\Timer\TimerInterface;
-use PhpCfdi\ImageCaptchaResolver\UnableToResolveCaptcha;
+use PhpCfdi\ImageCaptchaResolver\UnableToResolveCaptchaException;
 use RuntimeException;
 use Throwable;
 
@@ -56,7 +56,7 @@ public function getTimer(): TimerInterface
      * @param int $timeoutSeconds
      * @param int $waitMilliseconds
      * @return self
-     * @throws UndiscoverableClient
+     * @throws UndiscoverableClientException
      */
     public static function create(
         string $clientKey,
@@ -75,7 +75,7 @@ public function resolve(CaptchaImageInterface $image): CaptchaAnswerInterface
         try {
             return $this->resolveImage($image);
         } catch (Throwable $exception) {
-            throw new UnableToResolveCaptcha($this, $image, $exception);
+            throw new UnableToResolveCaptchaException($this, $image, $exception);
         }
     }
 

src/Resolvers/AntiCaptchaResolver/AntiCaptchaConnector.php

@@ -8,7 +8,7 @@
 use PhpCfdi\ImageCaptchaResolver\HttpClient\HttpClient;
 use PhpCfdi\ImageCaptchaResolver\HttpClient\HttpClientInterface;
 use PhpCfdi\ImageCaptchaResolver\HttpClient\HttpException;
-use PhpCfdi\ImageCaptchaResolver\HttpClient\UndiscoverableClient;
+use PhpCfdi\ImageCaptchaResolver\HttpClient\UndiscoverableClientException;
 use RuntimeException;
 use stdClass;
 use Stringable;
@@ -33,7 +33,7 @@ class AntiCaptchaConnector
      *
      * @param string $clientKey
      * @param HttpClientInterface|null $httpClient
-     * @throws UndiscoverableClient
+     * @throws UndiscoverableClientException
      */
     public function __construct(string $clientKey, HttpClientInterface $httpClient = null)
     {

src/Resolvers/CaptchaLocalResolver.php

@@ -7,11 +7,11 @@
 use PhpCfdi\ImageCaptchaResolver\CaptchaAnswerInterface;
 use PhpCfdi\ImageCaptchaResolver\CaptchaImageInterface;
 use PhpCfdi\ImageCaptchaResolver\CaptchaResolverInterface;
-use PhpCfdi\ImageCaptchaResolver\HttpClient\UndiscoverableClient;
+use PhpCfdi\ImageCaptchaResolver\HttpClient\UndiscoverableClientException;
 use PhpCfdi\ImageCaptchaResolver\Resolvers\CaptchaLocalResolver\CaptchaLocalResolverConnector;
 use PhpCfdi\ImageCaptchaResolver\Timer\Timer;
 use PhpCfdi\ImageCaptchaResolver\Timer\TimerInterface;
-use PhpCfdi\ImageCaptchaResolver\UnableToResolveCaptcha;
+use PhpCfdi\ImageCaptchaResolver\UnableToResolveCaptchaException;
 use Throwable;
 
 class CaptchaLocalResolver implements CaptchaResolverInterface
@@ -42,7 +42,7 @@ public function __construct(
      * @param int $timeoutSeconds
      * @param int $sleepMilliseconds
      * @return self
-     * @throws UndiscoverableClient
+     * @throws UndiscoverableClientException
      */
     public static function create(
         string $baseUrl,
@@ -71,7 +71,7 @@ public function resolve(CaptchaImageInterface $image): CaptchaAnswerInterface
         try {
             return $this->connector->resolveImage($image, $this->timer);
         } catch (Throwable $exception) {
-            throw new UnableToResolveCaptcha($this, $image, $exception);
+            throw new UnableToResolveCaptchaException($this, $image, $exception);
         }
     }
 }

src/Resolvers/CaptchaLocalResolver/CaptchaLocalResolverConnector.php

@@ -10,7 +10,7 @@
 use PhpCfdi\ImageCaptchaResolver\HttpClient\HttpClient;
 use PhpCfdi\ImageCaptchaResolver\HttpClient\HttpClientInterface;
 use PhpCfdi\ImageCaptchaResolver\HttpClient\HttpException;
-use PhpCfdi\ImageCaptchaResolver\HttpClient\UndiscoverableClient;
+use PhpCfdi\ImageCaptchaResolver\HttpClient\UndiscoverableClientException;
 use PhpCfdi\ImageCaptchaResolver\Timer\TimerInterface;
 use RuntimeException;
 
@@ -33,7 +33,7 @@ class CaptchaLocalResolverConnector
      *
      * @param string $baseUrl Full URL to access service, by example http://localhost:9095
      * @param HttpClientInterface|null $httpClient
-     * @throws UndiscoverableClient
+     * @throws UndiscoverableClientException
      */
     public function __construct(string $baseUrl, HttpClientInterface $httpClient = null)
     {