Merge pull request #11 from eclipxe13/master

Better dev experience (0.2.4)

Author: blacktrue

.gitattributes

@@ -2,16 +2,15 @@
 * text=auto
 
 # Do not put this files on a distribution package (by .gitignore)
-/vendor              export-ignore
-/build               export-ignore
+/vendor/             export-ignore
 /composer.lock       export-ignore
 
 # Do not put this files on a distribution package
+/build/              export-ignore
 /tests/              export-ignore
 /.gitattributes      export-ignore
 /.gitignore          export-ignore
 /.php_cs.dist        export-ignore
-/.phplint.yml        export-ignore
 /.scrutinizer.yml    export-ignore
 /.travis.yml         export-ignore
 /phpcs.xml.dist      export-ignore

.gitignore

@@ -1,4 +1,3 @@
 # do not include this files on git
-/vendor
-/build
+/vendor/
 /composer.lock

.phplint.yml

@@ -4,13 +4,14 @@ filter:
     - 'vendor/'
 
 build:
+  dependencies:
+    before:
+      - pecl install zip
+    override:
+      - composer self-update --no-interaction --no-progress
+      - composer install --no-interaction
   nodes:
-    php73:
-      environment:
-        php:
-          version: "7.3"
-          pecl_extensions:
-            - "zip"
+    php:
       tests:
         override:
           - php-scrutinizer-run --enable-security-analysis

.scrutinizer.yml

@@ -11,21 +11,15 @@ env:
     - PHP_CS_FIXER_FUTURE_MODE=1
     - PHP_CS_FIXER_IGNORE_ENV=1
 
-matrix:
-  allow_failures:
-    - php: "7.4snapshot"
-
 cache:
   - directories:
     - $HOME/.composer
 
 before_script:
   - phpenv config-rm xdebug.ini || true
   - travis_retry composer install --no-interaction --prefer-dist
-  - mkdir -p build
 
 script:
-  - vendor/bin/phplint
   - vendor/bin/php-cs-fixer fix --verbose --dry-run
   - vendor/bin/phpcs --colors -sp src/ tests/
   - vendor/bin/phpunit --testdox --verbose

.travis.yml

@@ -74,9 +74,8 @@ If any of these do not pass, it will result in a complete build failure.
 Before you can run these, be sure to `composer install` or `composer update`.
 
 ```shell
-vendor/bin/parallel-lint src/ tests/
 vendor/bin/phpcs -sp src/ tests/
 vendor/bin/php-cs-fixer fix -v --dry-run
 vendor/bin/phpunit --coverage-text
-vendor/bin/phpstan.phar analyse --no-progress --level max src/ tests/
+vendor/bin/phpstan analyse --no-progress --level max src/ tests/
 ```

CONTRIBUTING.md

@@ -19,16 +19,15 @@ También te esperamos en el [canal #phpcfdi de discord](https://discord.gg/aFGYX
 Esta librería contiene un cliente (consumidor) del servicio del SAT de
 **Servicio Web de Descarga Masiva de CFDI y Retenciones**.
 
+## Instalación
 
-## Installation
+Utiliza [composer](https://getcomposer.org/), instala de la siguiente forma:
 
-Use [composer](https://getcomposer.org/), please run
 ```shell
 composer require phpcfdi/sat-ws-descarga-masiva
 ```
 
-
-## Basic usage
+## Ejemplo básico de uso
 
 ```php
 <?php
@@ -41,16 +40,24 @@ use PhpCfdi\SatWsDescargaMasiva\Shared\DateTimePeriod;
 use PhpCfdi\SatWsDescargaMasiva\Shared\DownloadType;
 use PhpCfdi\SatWsDescargaMasiva\Shared\Fiel;
 use PhpCfdi\SatWsDescargaMasiva\Shared\RequestType;
-use PhpCfdi\SatWsDescargaMasiva\WebClient\WebClientInterface;
+use PhpCfdi\SatWsDescargaMasiva\WebClient\GuzzleWebClient;
 
-// Creación de la fiel
+// Creación de la fiel, puede leer archivos DER (como los envía el SAT) o PEM (convertidos)
 $fiel = Fiel::create(
-    file_get_contents('llaveprivada.key.pem'), // en formato PEM
-    file_get_contents('certificado.cer'),      // en formato PEM o DER
+    file_get_contents('certificado.cer'),
+    file_get_contents('llaveprivada.key'),
     '12345678a'
 );
 
-/** @var WebClientInterface $webClient */
+// verificar que la fiel sea válida (no sea CSD y sea vigente acorde a la fecha del sistema)
+if (! $fiel->isValid()) {
+    return;
+}
+
+// creación del web client basado en Guzzle que implementa WebClientInterface
+// para usarlo necesitas instalar guzzlehttp/guzzle pues no es una dependencia directa
+$webClient = new GuzzleWebClient();
+
 // Creación del servicio
 $service = new Service($fiel, $webClient);
 
@@ -83,36 +90,31 @@ $metadataReader = new MetadataPackageReader($zipfile);
 foreach ($metadataReader->metadata() as $metadata) {
     echo $metadata->uuid, PHP_EOL;
 }
-
 ```
 
-
 ### Acerca de la interfaz `WebClientInterface`
 
 Para hacer esta librería compatible con diferentes formas de comunicación se utiliza una interfaz de cliente HTTP.
-Tu *debes* crear tu implementación para poderla utilizar, si así lo prefieres, podrías usar la clase
-[`GuzzleWebClient`](https://github.com/phpcfdi/sat-ws-descarga-masiva/blob/master/tests/WebClient/GuzzleWebClient.php)
-
-En este momento no se provee esta implementación por defecto, es posible que en un futuro se incluya por default
-una clase que utilice [PSR-18 - HTTP Client](https://www.php-fig.org/psr/psr-18/).
-
+Tu *puedes* crear tu implementación para poderla utilizar.
+ 
+Si lo prefieres -como en el ejemplo de uso- podrías instalar Guzzle `composer require guzzlehttp/guzzle` y usar la clase
+[`GuzzleWebClient`](https://github.com/phpcfdi/sat-ws-descarga-masiva/blob/master/src/WebClient/GuzzleWebClient.php).
 
 ### Recomendación de fábrica del servicio
 
 Te recomendamos configurar el framework de tu aplicación (Dependency Injection Container) o crear una clase que
 fabrique los objetos `Service`, `Fiel` y `WebClient` usando tus propias configuraciones de certificado, llave privada
 y contraseña.
 
-
 ## Acerca del Servicio Web de Descarga Masiva de CFDI y Retenciones
 
 El servicio se compone de 4 partes:
 
 1. Autenticación: Esto se hace con tu fiel y la libería oculta la lógica de obtener y usar el Token.
-2. Solicitud: Presentar una solicitud incluyendo la fecha de inicio, fecha de fin, tipo de solicitud emitidas/recibidas
-y tipo de información solicitada (cfdi o metadata)
-3. Verificación: pregunta al SAT si ya tiene disponible la solicitud
-4. Descargar la solicitud.
+2. Solicitud: Presentar una solicitud incluyendo la fecha de inicio, fecha de fin, tipo de solicitud
+   emitidas/recibidas y tipo de información solicitada (cfdi o metadata).
+3. Verificación: pregunta al SAT si ya tiene disponible la solicitud.
+4. Descargar los paquetes emitidos por la solicitud.
 
 La mejor manera de entenderlo es la siguiente, imagina que el servicio del SAT se compone de tres ventanillas con tres
 personas diferentes atendiendo cada una de estas ventanillas.
@@ -148,22 +150,19 @@ Notas importantes del web service:
 - Podrás recuperar hasta 200 mil registros por petición y hasta un millón en metadata.
 - No existe limitante en cuanto al número de solicitudes siempre que no se descargue en más de una ocasión un XML.
 
-
 ## Compatilibilidad
 
 Esta librería se mantendrá compatible con al menos la versión con
-[soporte activo de PHP](http://php.net/supported-versions.php) más reciente.
+[soporte activo de PHP](https://www.php.net/supported-versions.php) más reciente.
 
 También utilizamos [Versionado Semántico 2.0.0](https://semver.org/lang/es/)
 por lo que puedes usar esta librería sin temor a romper tu aplicación.
 
-
 ## Contribuciones
 
 Las contribuciones con bienvenidas. Por favor lee [CONTRIBUTING][] para más detalles
 y recuerda revisar el archivo de tareas pendientes [TODO][] y el [CHANGELOG][].
 
-
 ## Copyright and License
 
 The `phpcfdi/sat-ws-descarga-masiva` library is copyright © [PhpCfdi](https://www.phpcfdi.com)
@@ -183,7 +182,7 @@ and licensed for use under the MIT License (MIT). Please see [LICENSE][] for mor
 [coverage]: https://scrutinizer-ci.com/g/phpcfdi/sat-ws-descarga-masiva/code-structure/master/code-coverage/src/
 [downloads]: https://packagist.org/packages/phpcfdi/sat-ws-descarga-masiva
 
-[badge-source]: http://img.shields.io/badge/source-phpcfdi/sat--ws--descarga--masiva-blue?style=flat-square
+[badge-source]: https://img.shields.io/badge/source-phpcfdi/sat--ws--descarga--masiva-blue?style=flat-square
 [badge-discord]: https://img.shields.io/discord/459860554090283019?logo=discord&style=flat-square
 [badge-release]: https://img.shields.io/github/release/phpcfdi/sat-ws-descarga-masiva?style=flat-square
 [badge-license]: https://img.shields.io/github/license/phpcfdi/sat-ws-descarga-masiva?style=flat-square

README.md

@@ -0,0 +1,2 @@
+*
+!.gitignore

build/.gitignore

@@ -25,18 +25,20 @@
         "ext-dom": "*",
         "ext-json": "*",
         "ext-zip": "*",
-        "phpcfdi/credentials": "^1.0",
+        "phpcfdi/credentials": "^1.1",
         "eclipxe/enum": "^0.2.0"
     },
     "require-dev": {
         "guzzlehttp/guzzle": "^6.3",
-        "robrichards/xmlseclibs": "^3.0",
+        "robrichards/xmlseclibs": "^3.0.4",
         "phpunit/phpunit": "^8.0",
-        "overtrue/phplint": "^1.0",
         "squizlabs/php_codesniffer": "^3.0",
         "friendsofphp/php-cs-fixer": "^2.4",
         "phpstan/phpstan-shim": "^0.11"
     },
+    "suggest": {
+        "guzzlehttp/guzzle": "To use GuzzleWebClient implementation"
+    },
     "autoload": {
         "psr-4": {
             "PhpCfdi\\SatWsDescargaMasiva\\": "src/"
@@ -58,7 +60,6 @@
             "vendor/bin/phpcbf --colors -sp src/ tests/"
         ],
         "dev:test": [
-            "vendor/bin/phplint",
             "@dev:check-style",
             "vendor/bin/phpunit --testdox --verbose --stop-on-failure",
             "vendor/bin/phpstan analyse --verbose --no-progress --level max src/ tests/"
@@ -71,7 +72,7 @@
         "dev:build": "DEV: run dev:fix-style dev:tests and dev:docs, run before pull request",
         "dev:check-style": "DEV: search for code style errors using php-cs-fixer and phpcs",
         "dev:fix-style": "DEV: fix code style errors using php-cs-fixer and phpcbf",
-        "dev:test": "DEV: run phplint, phpunit and phpstan",
+        "dev:test": "DEV: run @dev:check-style, phpunit and phpstan",
         "dev:coverage": "DEV: run phpunit with xdebug and storage coverage in build/coverage/html/"
     }
 }

composer.json

@@ -10,13 +10,27 @@ In summary, [SemVer](https://semver.org/) can be viewed as ` Breaking . Feature
 
 **Version `0.x.x` doesn't have to apply any of the SemVer rules**
 
-
-## **TO BE RELEASED**: Include this changes on next release, currently on `master` branch
-
-- Development environment (Travis CI):
-    - Fix code style issues.
-    - Add `PHP_CS_FIXER_FUTURE_MODE` and `PHP_CS_FIXER_IGNORE_ENV` to run `php-cs-fixer` on PHP 7.4.
-    - Remove deprecated config `sudo: false`.
+## Importante:
+
+- En Travis-CI pasar de `7.4snapshot` a `7.4` cuando se corrija el bug de construcción.
+  <https://travis-ci.community/t/some-extensions-are-missing-in-php-7-4-0-zip-gmp-sodium/6320/9>.
+
+## Version 0.2.4 2019-12-06
+
+- Se agrega la clase `PhpCfdi\SatWsDescargaMasiva\WebClient\GuzzleWebClient` que estaba en testing
+  a el código distribuible, aunque no se agrega la dependencia `guzzlehttp/guzzle`.
+- Se documenta el uso de `GuzzleWebClient`.
+- Forzar la dependencia de `phpcfdi/credentials` a `^1.1` para leer llaves privadas en formato DER.
+- Forzar la dependencia de `robrichards/xmlseclibs` a `^3.0.4` por reporte de seguridad `CVE-2019-3465`.
+- Agregar ejemplo en la documentación para crear y verificar un objeto `Fiel`.
+- Corrección en la documentación al crear una fiel, tenía los parámetros invertidos.
+- Integración continua (Travis CI):
+    - Se remueve la configuración `sudo: false`.
+    - No se permite el fallo del build en PHP `7.4snapshot`.
+- Integración continua (Scrutinizer):
+    - Se instala la extensión `zip` con `pecl`.
+    - Se elimina la información de la versión fija.
+    - Se modifica el archivo de configuración para que actualice `composer`.
 
 
 ## Version 0.2.3 2019-09-23

docs/CHANGELOG.md

@@ -1,8 +1,12 @@
 # phpcfdi/sat-ws-descarga-masiva To Do List
 
+- Traducir CHANGELOG.md a español
+
 - Mover el script de consumo con credenciales válidas a su propio proyecto dependiente de este.
 
 - Llevar el code coverage a 100% con test unitarios
+    2019-12-06: Cersion 0.2.4 92%
+    2019-09-23: Version 0.2.3 93% 
     2019-08-23: Current 93%
     2019-08-09: Current 86%
     2019-08-08: Current 84%

docs/TODO.md

@@ -16,9 +16,17 @@ public function __construct(Credential $credential)
         $this->credential = $credential;
     }
 
-    public static function create(string $certificate, string $privateKey, string $passPhrase): self
+    /**
+     * Create a Fiel based on certificate and private key contents
+     *
+     * @param string $certificateContents Contents of X.509 formats PEM, DER or DER as base64
+     * @param string $privateKeyContents Contents of PKCS#8 DER, PKCS#8 PEM or PKCS#5 PEM
+     * @param string $passPhrase Private key pass phrase
+     * @return static
+     */
+    public static function create(string $certificateContents, string $privateKeyContents, string $passPhrase): self
     {
-        $credential = Credential::create($certificate, $privateKey, $passPhrase);
+        $credential = Credential::create($certificateContents, $privateKeyContents, $passPhrase);
         return new self($credential);
     }