Merge pull request #14 from eclipxe13/master

Cancellation for CFDI Retentions & maintenance

Author: eclipxe13

.gitattributes

@@ -3,16 +3,15 @@
 
 # Do not put this files on a distribution package (by .gitignore)
 /vendor              export-ignore
-/build               export-ignore
 /composer.lock       export-ignore
 
 # Do not put this files on a distribution package
+/build/              export-ignore
 /docs/               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
 /composer.lock

.phplint.yml

@@ -4,6 +4,11 @@ filter:
     - 'vendor/'
 
 build:
+  dependencies:
+    override:
+      - composer self-update --no-interaction --no-progress
+      - composer remove squizlabs/php_codesniffer friendsofphp/php-cs-fixer phpstan/phpstan --dev --no-interaction --no-progress --no-update
+      - composer install --no-interaction
   nodes:
     build:
       tests:

.scrutinizer.yml

@@ -1,14 +1,7 @@
 language: php
 
 # php compatibility
-php:
-  - "7.2"
-  - "7.3"
-  - "7.4snapshot"
-
-matrix:
-  allow_failures:
-    - php: "7.4snapshot"
+php: ["7.2", "7.3", "7.4"]
 
 cache:
   - directories:
@@ -17,14 +10,12 @@ cache:
 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
-  - vendor/bin/phpstan.phar analyse --no-progress --verbose --level max src/ tests/
+  - vendor/bin/phpstan analyse --no-progress --verbose --level max src/ tests/
 
 notifications:
   email: false

.travis.yml

@@ -79,5 +79,5 @@ 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

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2019 PHPCFDI
+Copyright (c) 2019 - 2020 PHPCFDI
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

LICENSE

@@ -137,8 +137,8 @@ En la herramienta de ayuda no se especifica el RFC, cuando se fabrica la solicit
 se obtiene el RFC directamente de las propiedades del certificado.
 
 Los métodos de ayuda utilizan una fecha opcional (`DateTimeImmutable` o `null`), si no se especifica
-entonces se toma la fecha actual del sistema, ten en cuenta que para la creación se toma en cuenta
-el reloj del sistema y el uso horario. Si no estás seguro de poder controlar estas configuraciones te
+entonces se toma la fecha actual del sistema, ten en cuenta que para la creación se utiliza el reloj
+del sistema y el uso horario. Si no estás seguro de poder controlar estas configuraciones te
 recomiendo que establezcas el parámetro.
 
 ### Solicitud de cancelación
@@ -158,6 +158,16 @@ Para crear la solicitud de respuesta usa el método `signCancellationAnswer`.
 Requiere el UUID para el cual estás estableciendo la respuesta, la respuesta (aceptación o cancelación)
 y el RFC del PAC por el cual se realiza la consulta.
 
+### Solicitud de cancelación de RET
+
+Existe un CFDI especial de *"Retenciones e información de pagos"*, donde también se requiere una solicitud
+firmada tal como en una cancelación de CFDI pero su contenido cambia.
+
+Para crear la solicitud firmada para RET se puede hacer con los métodos `signRetentionCancellation` para un sólo UUID
+o `signRetentionCancellationUuids` para varios UUID. Como primer parámetro reciben qué UUID será cancelado.
+
+TIP: Por la experiencia en el uso de los servicios de SAT se comienda usar siempre cancelaciones individuales.
+
 ## Objetos de trabajo
 
 **`CapsuleInterface`** son los objetos que contienen toda la información relacionada con los datos a firmar,
@@ -213,15 +223,15 @@ and licensed for use under the MIT License (MIT). Please see [LICENSE][] for mor
 [source]: https://github.com/phpcfdi/xml-cancelacion
 [release]: https://github.com/phpcfdi/xml-cancelacion/releases
 [license]: https://github.com/phpcfdi/xml-cancelacion/blob/master/LICENSE
-[build]: https://travis-ci.org/phpcfdi/xml-cancelacion?branch=master
+[build]: https://travis-ci.com/phpcfdi/xml-cancelacion?branch=master
 [quality]: https://scrutinizer-ci.com/g/phpcfdi/xml-cancelacion/
 [coverage]: https://scrutinizer-ci.com/g/phpcfdi/xml-cancelacion/code-structure/master/code-coverage/src/
 [downloads]: https://packagist.org/packages/phpcfdi/xml-cancelacion
 
 [badge-source]: https://img.shields.io/badge/source-phpcfdi/xml--cancelacion-blue?style=flat-square
 [badge-release]: https://img.shields.io/github/release/phpcfdi/xml-cancelacion?style=flat-square
 [badge-license]: https://img.shields.io/github/license/phpcfdi/xml-cancelacion?style=flat-square
-[badge-build]: https://img.shields.io/travis/phpcfdi/xml-cancelacion/master?style=flat-square
+[badge-build]: https://img.shields.io/travis/com/phpcfdi/xml-cancelacion/master?style=flat-square
 [badge-quality]: https://img.shields.io/scrutinizer/g/phpcfdi/xml-cancelacion/master?style=flat-square
 [badge-coverage]: https://img.shields.io/scrutinizer/coverage/g/phpcfdi/xml-cancelacion/master?style=flat-square
 [badge-downloads]: https://img.shields.io/packagist/dt/phpcfdi/xml-cancelacion?style=flat-square

README.md

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

build/.gitignore

@@ -26,15 +26,14 @@
         "ext-dom": "*",
         "ext-openssl": "*",
         "eclipxe/enum": "^0.2",
-        "phpcfdi/credentials": "^1.0"
+        "phpcfdi/credentials": "^1.1.1"
     },
     "require-dev": {
         "robrichards/xmlseclibs": "^3.0.4",
         "phpunit/phpunit": "^8.3.5",
-        "overtrue/phplint": "^1.0",
         "squizlabs/php_codesniffer": "^3.0",
         "friendsofphp/php-cs-fixer": "^2.4",
-        "phpstan/phpstan-shim": "^0.11"
+        "phpstan/phpstan": "^0.12"
     },
     "suggest": {
         "robrichards/xmlseclibs": "Create document signatures (partially) using xmlseclibs"
@@ -60,7 +59,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/"
@@ -73,7 +71,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

@@ -1,11 +1,29 @@
 # CHANGELOG
 
-# Version 1.0.1 2019-10-02
+## Version 1.1.0 2020-01-23
+
+- Update license year, happy 2020!
+- Include cancellation document for document *"CFDI de retención e información de pagos"*.
+- Add `DocumentType` enumerator with keys `cfdi` and `retention` to specify the correct namespace of the request.
+- Add `XmlCancellationHelper::signRetentionCancellation` and `XmlCancellationHelper::signRetentionCancellationUuids`
+  that create cancellation request for retentions.
+- Refactor `XmlCancelacionHelper` and delegate the creation of the `Cancellation` object to a specific
+  protected method.
+- Other capsules uses also `DocumentType` to set the main namespace but as hardcoded.
+- Development:
+    - Move from `phpstan/phpstan-shim` to `phpstan/phpstan`.
+    - Upgrade to `phpstan/phpstan: ^0.12`
+- Testing:
+    - Improve `CancellationTest` to check that `DocumentType` is used correctly.
+    - Create a testing class `XmlCancelacionHelperSpy` to spy on `XmlCancelacionHelper`.
+    - Refactor tests on `XmlCancelacionHelperTest` to test against the spy class.  
+
+## Version 1.0.1 2019-10-02
 
 - Fix documentation to point out version 1.0 instead of 0.5.
 - Fix documentation PHP examples.
 
-# Version 1.0.0 2019-09-28
+## Version 1.0.0 2019-09-28
 
 - This version is a major change, it is not compatible with previous versions
   Read [UPGRADE-1.0](https://github.com/phpcfdi/xml-cancelacion/blob/master/docs/UPGRADE-1.0.md)

docs/CHANGELOG.md

@@ -1,5 +1,12 @@
 # phpcfdi/xml-cancelacion To Do List
 
-- [X] Generar excepciones internas en lugar de excepciones genéricas de SPL.
-- [X] Poner el copyright correcto en cuanto esté el sitio de PhpCfdi
-- [X] Dejar de usar CfdiUtils y usar phpcfdi/credentials cuando esté publicada y estable
+## Pendientes
+
+- El tercer parámetro del constructor de `Cancellation` que recibe el `DocumentType` debería ser obligatorio,
+  es opcional para compatibilidad con la versión actual.
+
+## Resueltas
+
+- Generar excepciones internas en lugar de excepciones genéricas de SPL.
+- Poner el copyright correcto en cuanto esté el sitio de PhpCfdi
+- Dejar de usar CfdiUtils y usar phpcfdi/credentials cuando esté publicada y estable

docs/TODO.md

@@ -1,5 +1,5 @@
 <phpunit xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/8.0/phpunit.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-         bootstrap="./tests/bootstrap.php" colors="true" verbose="true" cacheResultFile="./build/phpunit.result.cache">
+         bootstrap="./tests/bootstrap.php" colors="true" verbose="true" cacheResult="false">
     <testsuites>
         <testsuite name="Default">
             <directory>./tests/</directory>

phpunit.xml.dist

@@ -35,6 +35,7 @@ public function __construct(array $extraNamespaces = null)
         $this->extraNamespaces = $extraNamespaces;
     }
 
+    /** @return array<string, string> */
     public function extraNamespaces(): array
     {
         return $this->extraNamespaces;

src/Capsules/BaseDocumentBuilder.php

@@ -8,6 +8,7 @@
 use DateTimeImmutable;
 use DOMDocument;
 use DOMElement;
+use PhpCfdi\XmlCancelacion\Definitions\DocumentType;
 
 class Cancellation implements Countable, CapsuleInterface
 {
@@ -20,11 +21,23 @@ class Cancellation implements Countable, CapsuleInterface
     /** @var array<string, bool> This is a B-Tree array, values are stored in keys */
     private $uuids;
 
-    public function __construct(string $rfc, array $uuids, DateTimeImmutable $date)
+    /** @var DocumentType */
+    private $documentType;
+
+    /**
+     * DTO for cancellation request, it support CFDI and Retention
+     *
+     * @param string $rfc
+     * @param string[] $uuids
+     * @param DateTimeImmutable $date
+     * @param DocumentType|null $type Uses CFDI if non provided
+     */
+    public function __construct(string $rfc, array $uuids, DateTimeImmutable $date, DocumentType $type = null)
     {
         $this->rfc = $rfc;
         $this->date = $date;
         $this->uuids = [];
+        $this->documentType = $type ?? DocumentType::cfdi();
         foreach ($uuids as $uuid) {
             $this->uuids[strtoupper($uuid)] = true;
         }
@@ -40,6 +53,11 @@ public function date(): DateTimeImmutable
         return $this->date;
     }
 
+    public function documentType(): DocumentType
+    {
+        return $this->documentType;
+    }
+
     /**
      * The list of UUIDS
      * @return string[]
@@ -56,7 +74,7 @@ public function count(): int
 
     public function exportToDocument(): DOMDocument
     {
-        $document = (new BaseDocumentBuilder())->createBaseDocument('Cancelacion', 'http://cancelacfd.sat.gob.mx');
+        $document = (new BaseDocumentBuilder())->createBaseDocument('Cancelacion', $this->documentType->value());
 
         /** @var DOMElement $cancelacion */
         $cancelacion = $document->documentElement;

src/Capsules/Cancellation.php

@@ -8,6 +8,7 @@
 use DOMDocument;
 use DOMElement;
 use PhpCfdi\XmlCancelacion\Definitions\CancelAnswer;
+use PhpCfdi\XmlCancelacion\Definitions\DocumentType;
 
 class CancellationAnswer implements CapsuleInterface
 {
@@ -68,7 +69,7 @@ public function pacRfc(): string
     public function exportToDocument(): DOMDocument
     {
         $document = (new BaseDocumentBuilder())
-            ->createBaseDocument('SolicitudAceptacionRechazo', 'http://cancelacfd.sat.gob.mx');
+            ->createBaseDocument('SolicitudAceptacionRechazo', DocumentType::cfdi()->value());
 
         /** @var DOMElement $solicitudAceptacionRechazo */
         $solicitudAceptacionRechazo = $document->documentElement;

src/Capsules/CancellationAnswer.php

@@ -7,6 +7,7 @@
 use DOMDocument;
 use DOMElement;
 use PhpCfdi\XmlCancelacion\Definitions;
+use PhpCfdi\XmlCancelacion\Definitions\DocumentType;
 use PhpCfdi\XmlCancelacion\Definitions\RfcRole;
 
 class ObtainRelated implements CapsuleInterface
@@ -54,7 +55,7 @@ public function pacRfc(): string
     public function exportToDocument(): DOMDocument
     {
         $document = (new BaseDocumentBuilder())
-            ->createBaseDocument('PeticionConsultaRelacionados', 'http://cancelacfd.sat.gob.mx');
+            ->createBaseDocument('PeticionConsultaRelacionados', DocumentType::cfdi()->value());
 
         /** @var DOMElement $peticion */
         $peticion = $document->documentElement;

src/Capsules/ObtainRelated.php

@@ -72,6 +72,7 @@ public function certificateAsPEM(): string
         return $this->getCsd()->certificate()->pem();
     }
 
+    /** @return array<mixed> */
     public function publicKeyData(): array
     {
         return $this->getCsd()->certificate()->publicKey()->parsed();

src/Credentials.php

@@ -16,7 +16,10 @@
  */
 class CancelAnswer extends Enum
 {
-    /** @noinspection PhpMissingParentCallCommonInspection */
+    /**
+     * @inheritDoc
+     * @noinspection PhpMissingParentCallCommonInspection
+     */
     protected static function overrideValues(): array
     {
         return [

src/Definitions/CancelAnswer.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpCfdi\XmlCancelacion\Definitions;
+
+use Eclipxe\Enum\Enum;
+
+/**
+ * Define the answer to the cancellation request (accept/reject)
+ *
+ * @method static self cfdi()
+ * @method static self retention()
+ * @method bool isCfdi()
+ * @method bool isRetention()
+ */
+final class DocumentType extends Enum
+{
+    /**
+     * @inheritDoc
+     * @noinspection PhpMissingParentCallCommonInspection
+     */
+    protected static function overrideValues(): array
+    {
+        return [
+            'cfdi' => 'http://cancelacfd.sat.gob.mx',
+            'retention' => 'http://cancelaretencion.sat.gob.mx',
+        ];
+    }
+}