Merge pull request #2 from eclipxe13/master

eclipxe13 · web-flow · commit f673f3ce7587 · 2019-03-28T14:20:50.000-05:00
Version 2.0.0
diff --git a/.php_cs.dist b/.php_cs.dist
@@ -4,7 +4,7 @@ declare(strict_types=1);
 
 return PhpCsFixer\Config::create()
     ->setRiskyAllowed(true)
-    ->setCacheFile(__DIR__.'/build/.php_cs.cache')
+    ->setCacheFile(__DIR__ . '/build/.php_cs.cache')
     ->setRules([
         '@PSR2' => true,
         '@PHP70Migration' => true,
diff --git a/.scrutinizer.yml b/.scrutinizer.yml
@@ -8,7 +8,7 @@ build:
     analysis:
       environment:
         php:
-          version: 7.3
+          version: "7.3"
       project_setup:
         override: true
       tests:
diff --git a/.travis.yml b/.travis.yml
@@ -6,8 +6,8 @@ sudo: false
 
 # php compatibility
 php:
-  - 7.2
-  - 7.3
+  - "7.2"
+  - "7.3"
 
 cache:
   - directories:
diff --git a/README.md b/README.md
@@ -53,10 +53,10 @@ composer require phpcfdi/cfdi-expresiones
 
 ```php
 <?php
-use PhpCfdi\CfdiExpresiones\ExpressionExtractor;
+use PhpCfdi\CfdiExpresiones\DiscoverExtractor;
 
 // creamos el extractor
-$extractor = new ExpressionExtractor();
+$extractor = new DiscoverExtractor();
 
 // abrimos el documento en un DOMDocument
 $document = new DOMDocument();
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
@@ -1,17 +1,15 @@
 # CHANGELOG
 
-## About SemVer
-
-In summary, [SemVer](https://semver.org/) can be viewed as ` Breaking . Feature . Fix `, where:
-
-- Breaking version = includes incompatible changes to the API
-- Feature version = adds new feature(s) in a backwards-compatible manner
-- Fix version = includes backwards-compatible bug fixes
-
-**Non breaking changes (doesn't apply any of the SemVer rules)**
-
-- Version `0.x.x`
-- Library elements with annotation `@internal` doesn't apply any of the SemVer rules
+## Version 2.0.0 2019-03-28
+
+- Allows to create an expression with format fixes from specific types
+- Change `ExpressionExtractorInterface` to add `public function format(array $values): string`
+- Give a unique name for extractors, so when discovering by type can obtain an item
+- Change `ExpressionExtractorInterface` to add `public function uniqueName(): string`
+    - `Comprobante33` uses `CFDI33`
+    - `Comprobante32` uses `CFDI32`
+    - `Retenciones10` uses `RET10`
+- Rename `ExpressionExtractor` to `DiscoverExtractor`, it makes more sense
 
 
 ## Version 1.0.0 2019-03-27
diff --git a/docs/SEMVER.md b/docs/SEMVER.md
@@ -0,0 +1,42 @@
+# SEMVER
+
+Respetamos el estándar [Versionado Semántico 2.0.0](https://semver.org/lang/es/).
+
+En resumen, [SemVer](https://semver.org/) es un sistema de versiones de tres componentes `X.Y.Z`
+que nombraremos así: ` Breaking . Feature . Fix `, donde:
+
+- `Breaking`: Rompe la compatibilidad de código con versiones anteriores.
+- `Feature`: Agrega una nueva característica que es compatible con lo anterior.
+- `Fix`: Incluye algún cambio (generalmente correcciones) que no agregan nueva funcionalidad.
+
+## Composer
+
+[Composer](https://getcomposer.org/) es un gestor de dependencias en proyectos para PHP.
+Este gestor usa las [reglas](https://getcomposer.org/doc/articles/versions.md)
+de versionado semántico para instalar y actualizar paquetes.
+
+Te recomendamos instalar dependencias de librerías (no frameworks) con *Caret Version Range*.
+Por ejemplo: `"vendor/package": "^2.5"`.
+
+Esto significa que:
+
+- no debe actualizar a versiones `3.x.x`
+- no debe utilizar ninguna versión menor a `2.5.0`
+
+## Versiones 0.x.y no rompe compatibilidad
+
+Las versiones que inician con cero, por ejemplo `0.y.z`, no se ajustan a las reglas de versionado.
+Se considera que estas versiones son previas a la madurez del proyecto y por lo tanto
+introducen cambios sin previo aviso.
+
+## `@internal` no rompe compatibilidad
+
+Si la librería contiene elementos marcados como `@internal` significa que no deben ser utilizados
+por tu código. Son partes de código internos de la librería.
+Por lo tanto, no se consideran breaking changes.
+
+Cuando un elemento es `@internal`, dicho elemento:
+
+- no debe ser una entrada (parámetro)
+- no debe ser una salida (retorno)
+- no debe exponer exponer funcionalidades en los objetos públicos (rasgos)
diff --git a/src/DiscoverExtractor.php b/src/DiscoverExtractor.php
@@ -10,7 +10,7 @@
 use PhpCfdi\CfdiExpresiones\Extractors\Comprobante33;
 use PhpCfdi\CfdiExpresiones\Extractors\Retenciones10;
 
-class ExpressionExtractor implements ExpressionExtractorInterface
+class DiscoverExtractor implements ExpressionExtractorInterface
 {
     /** @var ExpressionExtractorInterface[] */
     private $expressions;
@@ -35,11 +35,22 @@ public function defaultExtractors(): array
         ];
     }
 
+    /** @return ExpressionExtractorInterface[] */
     public function currentExpressionExtractors(): array
     {
         return $this->expressions;
     }
 
+    protected function findByUniqueName(string $uniqueName): ?ExpressionExtractorInterface
+    {
+        foreach ($this->expressions as $expression) {
+            if ($uniqueName === $expression->uniqueName()) {
+                return $expression;
+            }
+        }
+        return null;
+    }
+
     protected function findMatch(DOMDocument $document): ?ExpressionExtractorInterface
     {
         foreach ($this->expressions as $expression) {
@@ -54,7 +65,7 @@ protected function getFirstMatch(DOMDocument $document): ExpressionExtractorInte
     {
         $discovered = $this->findMatch($document);
         if (null === $discovered) {
-            throw new UnmatchedDocumentException('Cannot discover any ExpressionExtractor that matches with document');
+            throw new UnmatchedDocumentException('Cannot discover any DiscoverExtractor that matches with document');
         }
         return $discovered;
     }
@@ -64,9 +75,24 @@ public function matches(DOMDocument $document): bool
         return (null !== $this->findMatch($document));
     }
 
+    public function uniqueName(): string
+    {
+        return 'discover';
+    }
+
     public function extract(DOMDocument $document): string
     {
         $discovered = $this->getFirstMatch($document);
         return $discovered->extract($document);
     }
+
+    public function format(array $values, $type = ''): string
+    {
+        $extractor = $this->findByUniqueName($type);
+        if (null === $extractor) {
+            throw new UnmatchedDocumentException('DiscoverExtractor requires type key with an extractor identifier');
+        }
+        unset($values['type']);
+        return $extractor->format($values);
+    }
 }
diff --git a/src/ExpressionExtractorInterface.php b/src/ExpressionExtractorInterface.php
@@ -8,7 +8,17 @@
 
 interface ExpressionExtractorInterface
 {
+    public function uniqueName(): string;
+
     public function matches(DOMDocument $document): bool;
 
     public function extract(DOMDocument $document): string;
+
+    /**
+     * Format an expression based on given values
+     *
+     * @param array<string, string> $values
+     * @return string
+     */
+    public function format(array $values): string;
 }
diff --git a/src/Extractors/Comprobante32.php b/src/Extractors/Comprobante32.php
@@ -20,6 +20,11 @@ public function __construct()
         $this->matchDetector = new MatchDetector('http://www.sat.gob.mx/cfd/3', 'cfdi:Comprobante', 'version', '3.2');
     }
 
+    public function uniqueName(): string
+    {
+        return 'CFDI32';
+    }
+
     public function matches(DOMDocument $document): bool
     {
         return $this->matchDetector->matches($document);
@@ -35,16 +40,27 @@ public function extract(DOMDocument $document): string
         $uuid = $helper->getAttribute('cfdi:Comprobante', 'cfdi:Complemento', 'tfd:TimbreFiscalDigital', 'UUID');
         $rfcEmisor = $helper->getAttribute('cfdi:Comprobante', 'cfdi:Emisor', 'rfc');
         $rfcReceptor = $helper->getAttribute('cfdi:Comprobante', 'cfdi:Receptor', 'rfc');
-        $totalComprobante = $helper->getAttribute('cfdi:Comprobante', 'total');
+        $total = $helper->getAttribute('cfdi:Comprobante', 'total');
 
-        return '?' . implode('&', [
-            're=' . $rfcEmisor,
-            'rr=' . $rfcReceptor,
-            'tt=' . $this->formatTotal($totalComprobante),
-            'id=' . $uuid,
+        return $this->format([
+            're' => $rfcEmisor,
+            'rr' => $rfcReceptor,
+            'tt' => $total,
+            'id' => $uuid,
         ]);
     }
 
+    public function format(array $values): string
+    {
+        return '?'
+            . implode('&', [
+                're=' . ($values['re'] ?? ''),
+                'rr=' . ($values['rr'] ?? ''),
+                'tt=' . $this->formatTotal($values['tt'] ?? ''),
+                'id=' . ($values['id'] ?? ''),
+            ]);
+    }
+
     public function formatTotal(string $input): string
     {
         return str_pad(number_format(floatval($input), 6, '.', ''), 17, '0', STR_PAD_LEFT);
diff --git a/src/Extractors/Comprobante33.php b/src/Extractors/Comprobante33.php
@@ -20,6 +20,11 @@ public function __construct()
         $this->matchDetector = new MatchDetector('http://www.sat.gob.mx/cfd/3', 'cfdi:Comprobante', 'Version', '3.3');
     }
 
+    public function uniqueName(): string
+    {
+        return 'CFDI33';
+    }
+
     public function matches(DOMDocument $document): bool
     {
         return $this->matchDetector->matches($document);
@@ -35,20 +40,30 @@ public function extract(DOMDocument $document): string
         $uuid = $helper->getAttribute('cfdi:Comprobante', 'cfdi:Complemento', 'tfd:TimbreFiscalDigital', 'UUID');
         $rfcEmisor = $helper->getAttribute('cfdi:Comprobante', 'cfdi:Emisor', 'Rfc');
         $rfcReceptor = $helper->getAttribute('cfdi:Comprobante', 'cfdi:Receptor', 'Rfc');
-        $totalComprobante = $helper->getAttribute('cfdi:Comprobante', 'Total');
+        $total = $helper->getAttribute('cfdi:Comprobante', 'Total');
         $sello = substr($helper->getAttribute('cfdi:Comprobante', 'Sello'), -8);
 
-        $total = $this->formatTotal($totalComprobante);
-
-        return 'https://verificacfdi.facturaelectronica.sat.gob.mx/default.aspx?' . implode('&', [
-            'id=' . $uuid,
-            're=' . $rfcEmisor,
-            'rr=' . $rfcReceptor,
-            'tt=' . $total,
-            'fe=' . substr($sello, -8),
+        return $this->format([
+            'id' => $uuid,
+            're' => $rfcEmisor,
+            'rr' => $rfcReceptor,
+            'tt' => $total,
+            'fe' => substr($sello, -8),
         ]);
     }
 
+    public function format(array $values): string
+    {
+        return 'https://verificacfdi.facturaelectronica.sat.gob.mx/default.aspx?'
+            . implode('&', [
+                'id=' . ($values['id'] ?? ''),
+                're=' . ($values['re'] ?? ''),
+                'rr=' . ($values['rr'] ?? ''),
+                'tt=' . $this->formatTotal($values['tt'] ?? ''),
+                'fe=' . ($values['fe'] ?? ''),
+            ]);
+    }
+
     public function formatTotal(string $input): string
     {
         $total = rtrim(number_format(floatval($input), 6, '.', ''), '0');
diff --git a/src/Extractors/Retenciones10.php b/src/Extractors/Retenciones10.php
@@ -26,6 +26,11 @@ public function __construct()
         );
     }
 
+    public function uniqueName(): string
+    {
+        return 'RET10';
+    }
+
     public function matches(DOMDocument $document): bool
     {
         return $this->matchDetector->matches($document);
@@ -76,12 +81,33 @@ public function extract(DOMDocument $document): string
             $helper->getAttribute('retenciones:Retenciones', 'retenciones:Totales', 'montoTotOperacion')
         );
 
-        return '?' . implode('&', array_filter([
-            're=' . $rfcEmisor,
-            $rfcReceptorKey . '=' . $rfcReceptor,
-            'tt=' . $this->formatTotal($total),
-            'id=' . $uuid,
-        ]));
+        return $this->format([
+            're' => $rfcEmisor,
+            $rfcReceptorKey => $rfcReceptor,
+            'tt' => $this->formatTotal($total),
+            'id' => $uuid,
+        ]);
+    }
+
+    public function format(array $values): string
+    {
+        $receptorKey = 'rr';
+        if (isset($values['nr'])) {
+            $receptorKey = 'nr';
+            $values['nr'] = $this->formatForeignTaxId($values['nr']);
+        }
+        return '?'
+            . implode('&', [
+                're=' . ($values['re'] ?? ''),
+                $receptorKey . '=' . ($values[$receptorKey] ?? ''),
+                'tt=' . $this->formatTotal($values['tt'] ?? ''),
+                'id=' . ($values['id'] ?? ''),
+            ]);
+    }
+
+    public function formatForeignTaxId(string $foreignTaxId): string
+    {
+        return str_pad($foreignTaxId, 20, '0', STR_PAD_LEFT);
     }
 
     public function formatTotal(string $input): string
diff --git a/tests/Unit/DiscoverExtractorTest.php b/tests/Unit/DiscoverExtractorTest.php
diff --git a/tests/Unit/Extractors/Comprobante32Test.php b/tests/Unit/Extractors/Comprobante32Test.php
diff --git a/tests/Unit/Extractors/Comprobante33Test.php b/tests/Unit/Extractors/Comprobante33Test.php
diff --git a/tests/Unit/Extractors/Retenciones10Test.php b/tests/Unit/Extractors/Retenciones10Test.php

Original file line number	Diff line number	Diff line change
`@@ -10,7 +10,7 @@`
`10`	`10`	`use PhpCfdi\CfdiExpresiones\Extractors\Comprobante33;`
`11`	`11`	`use PhpCfdi\CfdiExpresiones\Extractors\Retenciones10;`
`12`	`12`
`13`		`-class ExpressionExtractor implements ExpressionExtractorInterface`
	`13`	`+class DiscoverExtractor implements ExpressionExtractorInterface`
`14`	`14`	`{`
`15`	`15`	`/** @var ExpressionExtractorInterface[] */`
`16`	`16`	`private $expressions;`
`@@ -35,11 +35,22 @@ public function defaultExtractors(): array`
`35`	`35`	`];`
`36`	`36`	`}`
`37`	`37`
	`38`	`+ /** @return ExpressionExtractorInterface[] */`
`38`	`39`	`public function currentExpressionExtractors(): array`
`39`	`40`	`{`
`40`	`41`	`return $this->expressions;`
`41`	`42`	`}`
`42`	`43`
	`44`	`+ protected function findByUniqueName(string $uniqueName): ?ExpressionExtractorInterface`
	`45`	`+ {`
	`46`	`+ foreach ($this->expressions as $expression) {`
	`47`	`+ if ($uniqueName === $expression->uniqueName()) {`
	`48`	`+ return $expression;`
	`49`	`+ }`
	`50`	`+ }`
	`51`	`+ return null;`
	`52`	`+ }`
	`53`	`+`
`43`	`54`	`protected function findMatch(DOMDocument $document): ?ExpressionExtractorInterface`
`44`	`55`	`{`
`45`	`56`	`foreach ($this->expressions as $expression) {`
`@@ -54,7 +65,7 @@ protected function getFirstMatch(DOMDocument $document): ExpressionExtractorInte`
`54`	`65`	`{`
`55`	`66`	`$discovered = $this->findMatch($document);`
`56`	`67`	`if (null === $discovered) {`
`57`		`- throw new UnmatchedDocumentException('Cannot discover any ExpressionExtractor that matches with document');`
	`68`	`+ throw new UnmatchedDocumentException('Cannot discover any DiscoverExtractor that matches with document');`
`58`	`69`	`}`
`59`	`70`	`return $discovered;`
`60`	`71`	`}`
`@@ -64,9 +75,24 @@ public function matches(DOMDocument $document): bool`
`64`	`75`	`return (null !== $this->findMatch($document));`
`65`	`76`	`}`
`66`	`77`
	`78`	`+ public function uniqueName(): string`
	`79`	`+ {`
	`80`	`+ return 'discover';`
	`81`	`+ }`
	`82`	`+`
`67`	`83`	`public function extract(DOMDocument $document): string`
`68`	`84`	`{`
`69`	`85`	`$discovered = $this->getFirstMatch($document);`
`70`	`86`	`return $discovered->extract($document);`
`71`	`87`	`}`
	`88`	`+`
	`89`	`+ public function format(array $values, $type = ''): string`
	`90`	`+ {`
	`91`	`+ $extractor = $this->findByUniqueName($type);`
	`92`	`+ if (null === $extractor) {`
	`93`	`+ throw new UnmatchedDocumentException('DiscoverExtractor requires type key with an extractor identifier');`
	`94`	`+ }`
	`95`	`+ unset($values['type']);`
	`96`	`+ return $extractor->format($values);`
	`97`	`+ }`
`72`	`98`	`}`