Merge pull request #25 from josemmo/develop

v0.2.1

README.md

@@ -11,9 +11,9 @@
 </p>
 
 ## About
-eInvoicing is a PHP library for creating and reading electronic invoices according to the [eInvoicing Directive and European standard](https://ec.europa.eu/cefdigital/wiki/display/CEFDIGITAL/eInvoicing).
+eInvoicing is a PHP library for creating and reading electronic invoices according to the [eInvoicing Directive and European standard](https://ec.europa.eu/digital-building-blocks/wikis/display/DIGITAL/eInvoicing).
 
-It aims to be 100% compliant with [EN 16931](https://ec.europa.eu/cefdigital/wiki/x/kwFVBg) as well as with the most popular CIUS and extensions, such as [PEPPOL BIS](https://docs.peppol.eu/poacc/billing/3.0/bis/).
+It aims to be 100% compliant with [EN 16931](https://ec.europa.eu/digital-building-blocks/wikis/x/boTXGw) as well as with the most popular CIUS and extensions, such as [PEPPOL BIS](https://docs.peppol.eu/poacc/billing/3.0/bis/).
 
 ## Installation
 First of all, make sure your environment meets the following requirements:
@@ -98,7 +98,7 @@ echo $writer->export($inv);
 These are the expected features for the library and how's it going so far:
 
 - [x] Representation of invoices, parties and invoice lines as objects
-- [x] Compatibility with the most used [CIUS and extensions](https://ec.europa.eu/cefdigital/wiki/x/5xLoAg)
+- [x] Compatibility with the most used [CIUS and extensions](https://ec.europa.eu/digital-building-blocks/wikis/display/EINVCOMMUNITY/Registry+of+CIUS+%28Core+Invoice+Usage+Specifications%29+and+Extensions)
 - [x] Export invoices to UBL documents
 - [x] Import invoices from UBL documents
 - [ ] Export invoices to CII documents

composer.json

@@ -29,7 +29,7 @@
     },
     "require": {
         "php": ">=7.1",
-        "josemmo/uxml": "^0.1.3"
+        "josemmo/uxml": "^0.1.4"
     },
     "require-dev": {
         "ext-openssl": "*",

docs/getting-started/eu-einvoicing-concepts.md

@@ -39,7 +39,7 @@ more particular cases, such us the ones mentioned before.
 The most popular CIUS is [PEPPOL BIS Billing 3.0][4], a cross-border specification used by multiple countries and
 international companies from both public and private sectors.
 
-[1]: https://ec.europa.eu/cefdigital/wiki/display/CEFDIGITAL/Navigating+the+eInvoicing+standard+documentation
-[2]: https://ec.europa.eu/cefdigital/wiki/display/CEFDIGITAL/Required+syntaxes
-[3]: https://ec.europa.eu/cefdigital/wiki/x/5xLoAg
+[1]: https://ec.europa.eu/digital-building-blocks/wikis/display/DIGITAL/Navigating+the+eInvoicing+standard+documentation
+[2]: https://ec.europa.eu/digital-building-blocks/wikis/display/DIGITAL/Required+syntaxes
+[3]: https://ec.europa.eu/digital-building-blocks/wikis/display/EINVCOMMUNITY/Registry+of+CIUS+%28Core+Invoice+Usage+Specifications%29+and+Extensions
 [4]: http://docs.peppol.eu/poacc/billing/3.0/

docs/getting-started/installation.md

@@ -1,6 +1,6 @@
 # Getting Started
 eInvoicing (short for "European Invoicing") is a free and open-source library written in PHP for creating and reading
-electronic invoices compliant with [EN 16931](https://ec.europa.eu/cefdigital/wiki/x/kwFVBg).
+electronic invoices compliant with [EN 16931](https://ec.europa.eu/digital-building-blocks/wikis/x/boTXGw).
 
 ## Requirements
 In order to install this library, your environment has to meet the following requirements:

docs/index.md

@@ -1,9 +1,9 @@
 # European Invoicing (eInvoicing)
 
-eInvoicing is a PHP library for creating and reading electronic invoices according to the [eInvoicing Directive and European standard](https://ec.europa.eu/cefdigital/wiki/display/CEFDIGITAL/eInvoicing).
+eInvoicing is a PHP library for creating and reading electronic invoices according to the [eInvoicing Directive and European standard](https://ec.europa.eu/digital-building-blocks/wikis/display/DIGITAL/eInvoicing).
 
-It aims to be 100% compliant with [EN 16931](https://ec.europa.eu/cefdigital/wiki/x/kwFVBg) as well as with the most popular CIUS and extensions, such as [PEPPOL BIS](https://docs.peppol.eu/poacc/billing/3.0/bis/).
+It aims to be 100% compliant with [EN 16931](https://ec.europa.eu/digital-building-blocks/wikis/x/boTXGw) as well as with the most popular CIUS and extensions, such as [PEPPOL BIS](https://docs.peppol.eu/poacc/billing/3.0/bis/).
 
 [Get Started](getting-started/installation.md){: .md-button .md-button--primary }
  
-[Go to GitHub](https://github.com/josemmo/einvoicing){: .md-button }
+[Go to GitHub](https://github.com/josemmo/einvoicing){: .md-button }

scripts/build-docs.php

@@ -1,7 +1,9 @@
 <?php
 use phpDocumentor\Reflection\DocBlock;
+use phpDocumentor\Reflection\DocBlock\Tags\Deprecated;
 use phpDocumentor\Reflection\DocBlock\Tags\Param;
 use phpDocumentor\Reflection\DocBlock\Tags\Return_;
+use phpDocumentor\Reflection\DocBlock\Tags\See;
 use phpDocumentor\Reflection\DocBlock\Tags\Throws;
 use phpDocumentor\Reflection\DocBlock\Tags\Var_;
 use phpDocumentor\Reflection\File\LocalFile;
@@ -27,7 +29,7 @@
 
 /**
  * Get project files
- * @return Element[string] Array of documentable classes
+ * @return array<string,Element> Array of documentable classes
  */
 function getProjectFiles(): array {
     $files = [];
@@ -55,7 +57,7 @@ function getProjectFiles(): array {
  * Get class public elements
  * @param  Class_                         $class    Class instance
  * @param  string                         $type     Element type ("constants", "properties" or "methods")
- * @param  Element[string]                &$project Project files
+ * @param  array<string,Element>          &$project Project files
  * @return Constant[]|Property[]|Method[]           Public elements
  */
 function getPublicElements(Class_ $class, string $type, array &$project): array {
@@ -102,9 +104,9 @@ function getClassUrl(string $fqsen): string {
 
 /**
  * Render class
- * @param  Class_          $class    Class instance
- * @param  Element[string] &$project Project files
- * @return string                    Markdown documentation
+ * @param  Class_                $class    Class instance
+ * @param  array<string,Element> &$project Project files
+ * @return string                          Markdown documentation
  */
 function renderClass(Class_ $class, array &$project): string {
     $doc = "# {$class->getFqsen()}\n\n";
@@ -180,9 +182,22 @@ function renderMethod(Method $method, array $addDocblocks, Class_ $class): strin
     $return = $docblock->getTagsByName('return')[0] ?? null;
 
     // Method summary
-    $doc = "## `{$method->getName()}()`\n";
+    $doc  = "## `{$method->getName()}()`\n";
     $doc .= $docblock->getSummary() . "\n";
 
+    // Deprecation warning
+    /** @var Deprecated|null */
+    $deprecated = $docblock->getTagsByName('deprecated')[0] ?? null;
+    if ($deprecated !== null) {
+        /** @var See */
+        $see = $docblock->getTagsByName('see')[0];
+        $seeRef = $see->getReference();
+        $doc .= "\n";
+        $doc .= "!!! warning \"Deprecated since v{$deprecated->getVersion()}\"\n";
+        $doc .= "\n";
+        $doc .= "    Use [`$seeRef`](#" . strtolower(substr($seeRef, strpos($seeRef, '::')+2, -2)) . ") instead.\n";
+    }
+
     // Signature
     $doc .= "\n```php\n";
     $doc .= "public " . ($method->isStatic() ? "static " : "") . $method->getName() . "(";

src/Invoice.php

@@ -16,6 +16,7 @@
 use function array_splice;
 use function count;
 use function is_subclass_of;
+use function round;
 
 class Invoice {
     const DEFAULT_DECIMALS = 8;
@@ -27,17 +28,19 @@ class Invoice {
     protected $number = null;
     protected $type = 380; // TODO: add constants
     protected $currency = "EUR"; // TODO: add constants
+    protected $vatCurrency = null;
     protected $issueDate = null;
     protected $dueDate = null;
     protected $taxPointDate = null;
-    protected $note = null;
+    protected $notes = [];
     protected $buyerReference = null;
     protected $purchaseOrderReference = null;
     protected $salesOrderReference = null;
     protected $tenderOrLotReference = null;
     protected $contractReference = null;
     protected $paidAmount = 0;
     protected $roundingAmount = 0;
+    protected $customVatAmount = null;
     protected $seller = null;
     protected $buyer = null;
     protected $payee = null;
@@ -83,6 +86,21 @@ public function getDecimals(string $field): int {
     }
 
 
+    /**
+     * Round value
+     * @param  float  $value Value to round
+     * @param  string $field Field name
+     * @return float         Rounded value
+     */
+    public function round(float $value, string $field): float {
+        $rounded = round($value, $this->getDecimals($field));
+        if ($rounded == 0) {
+            $rounded += 0; // To fix negative zero
+        }
+        return $rounded;
+    }
+
+
     /**
      * Set rounding matrix
      * @param  array $matrix Rounding matrix
@@ -194,6 +212,26 @@ public function setCurrency(string $currencyCode): self {
     }
 
 
+    /**
+     * Get VAT accounting currency code
+     * @return string|null VAT accounting currency code or NULL if same as document's
+     */
+    public function getVatCurrency(): ?string {
+        return $this->vatCurrency;
+    }
+
+
+    /**
+     * Set VAT accounting currency code
+     * @param  string|null $currencyCode VAT accounting currency code or NULL if same as document's
+     * @return self                      Invoice instance
+     */
+    public function setVatCurrency(?string $currencyCode): self {
+        $this->vatCurrency = $currencyCode;
+        return $this;
+    }
+
+
     /**
      * Get invoice issue date
      * @return DateTime|null Invoice issue date
@@ -254,22 +292,72 @@ public function setTaxPointDate(?DateTime $taxPointDate): self {
     }
 
 
+    /**
+     * Get invoice notes
+     * @return string[] Invoice notes
+     */
+    public function getNotes(): array {
+        return $this->notes;
+    }
+
+
+    /**
+     * Add invoice note
+     * @param  string $note Invoice note
+     * @return self         Invoice instance
+     */
+    public function addNote(string $note): self {
+        $this->notes[] = $note;
+        return $this;
+    }
+
+
+    /**
+     * Remove invoice note
+     * @param  int  $index Invoice note index
+     * @return self        Invoice instance
+     * @throws OutOfBoundsException if invoice note index is out of bounds
+     */
+    public function removeNote(int $index): self {
+        if ($index < 0 || $index >= count($this->notes)) {
+            throw new OutOfBoundsException('Could not find invoice note by index');
+        }
+        array_splice($this->notes, $index, 1);
+        return $this;
+    }
+
+
+    /**
+     * Clear all invoice notes
+     * @return self Invoice instance
+     */
+    public function clearNotes(): self {
+        $this->notes = [];
+        return $this;
+    }
+
+
     /**
      * Get invoice note
      * @return string|null Invoice note
+     * @deprecated 0.2.1
+     * @see Invoice::getNotes()
      */
     public function getNote(): ?string {
-        return $this->note;
+        return $this->notes[0] ?? null;
     }
 
 
     /**
      * Set invoice note
      * @param  string|null $note Invoice note
      * @return self              Invoice instance
+     * @deprecated 0.2.1
+     * @see Invoice::addNote()
      */
     public function setNote(?string $note): self {
-        $this->note = $note;
+        // @phan-suppress-next-line PhanPartialTypeMismatchProperty
+        $this->notes = ($note === null) ? [] : [$note];
         return $this;
     }
 
@@ -414,6 +502,26 @@ public function setRoundingAmount(float $roundingAmount): self {
     }
 
 
+    /**
+     * Get total VAT amount in VAT accounting currency
+     * @return float|null Total amount in accounting currency
+     */
+    public function getCustomVatAmount(): ?float {
+        return $this->customVatAmount;
+    }
+
+
+    /**
+     * Set total VAT amount in VAT accounting currency
+     * @param  float|null  $customVatAmount Total amount in accounting currency
+     * @return self                         Invoice instance
+     */
+    public function setCustomVatAmount(?float $customVatAmount): self {
+        $this->customVatAmount = $customVatAmount;
+        return $this;
+    }
+
+
     /**
      * Get seller
      * @return Party|null Seller instance

src/Models/InvoiceTotals.php

@@ -4,15 +4,20 @@
 use Einvoicing\Invoice;
 use Einvoicing\Traits\VatTrait;
 use function array_values;
-use function round;
 
 class InvoiceTotals {
     /**
-     * Totals currency code
+     * Invoice currency code
      * @var string
      */
     public $currency;
 
+    /**
+     * VAT accounting currency code
+     * @var string|null
+     */
+    public $vatCurrency = null;
+
     /**
      * Sum of all invoice line net amounts
      * @var float
@@ -61,6 +66,12 @@ class InvoiceTotals {
      */
     public $roundingAmount = 0;
 
+    /**
+     * Total VAT amount in accounting currency
+     * @var float|null
+     */
+    public $customVatAmount = null;
+
     /**
      * Amount due for payment
      * @var float
@@ -83,8 +94,9 @@ static public function fromInvoice(Invoice $inv, bool $round=true): InvoiceTotal
         $totals = new self();
         $vatMap = [];
 
-        // Set currency code
+        // Set currency codes
         $totals->currency = $inv->getCurrency();
+        $totals->vatCurrency = $inv->getVatCurrency();
 
         // Process all invoice lines
         foreach ($inv->getLines() as $line) {
@@ -116,25 +128,26 @@ static public function fromInvoice(Invoice $inv, bool $round=true): InvoiceTotal
         $totals->taxInclusiveAmount = $totals->taxExclusiveAmount + $totals->vatAmount;
         $totals->paidAmount = $inv->getPaidAmount();
         $totals->roundingAmount = $inv->getRoundingAmount();
+        $totals->customVatAmount = $inv->getCustomVatAmount();
         $totals->payableAmount = $totals->taxInclusiveAmount - $totals->paidAmount + $totals->roundingAmount;
 
         // Attach VAT breakdown
         $totals->vatBreakdown = array_values($vatMap);
 
         // Round values
         if ($round) {
-            $totals->netAmount = round($totals->netAmount, $inv->getDecimals('invoice/netAmount'));
-            $totals->allowancesAmount = round($totals->allowancesAmount, $inv->getDecimals('invoice/allowancesChargesAmount'));
-            $totals->chargesAmount = round($totals->chargesAmount, $inv->getDecimals('invoice/allowancesChargesAmount'));
-            $totals->vatAmount = round($totals->vatAmount, $inv->getDecimals('invoice/vatAmount'));
-            $totals->taxExclusiveAmount = round($totals->taxExclusiveAmount, $inv->getDecimals('invoice/taxExclusiveAmount'));
-            $totals->taxInclusiveAmount = round($totals->taxInclusiveAmount, $inv->getDecimals('invoice/taxInclusiveAmount'));
-            $totals->paidAmount = round($totals->paidAmount, $inv->getDecimals('invoice/paidAmount'));
-            $totals->roundingAmount = round($totals->roundingAmount, $inv->getDecimals('invoice/roundingAmount'));
-            $totals->payableAmount = round($totals->payableAmount, $inv->getDecimals('invoice/payableAmount'));
+            $totals->netAmount = $inv->round($totals->netAmount, 'invoice/netAmount');
+            $totals->allowancesAmount = $inv->round($totals->allowancesAmount, 'invoice/allowancesChargesAmount');
+            $totals->chargesAmount = $inv->round($totals->chargesAmount, 'invoice/allowancesChargesAmount');
+            $totals->vatAmount = $inv->round($totals->vatAmount, 'invoice/vatAmount');
+            $totals->taxExclusiveAmount = $inv->round($totals->taxExclusiveAmount, 'invoice/taxExclusiveAmount');
+            $totals->taxInclusiveAmount = $inv->round($totals->taxInclusiveAmount, 'invoice/taxInclusiveAmount');
+            $totals->paidAmount = $inv->round($totals->paidAmount, 'invoice/paidAmount');
+            $totals->roundingAmount = $inv->round($totals->roundingAmount, 'invoice/roundingAmount');
+            $totals->payableAmount = $inv->round($totals->payableAmount, 'invoice/payableAmount');
             foreach ($totals->vatBreakdown as $item) {
-                $item->taxableAmount = round($item->taxableAmount, $inv->getDecimals('invoice/allowancesChargesAmount'));
-                $item->taxAmount = round($item->taxAmount, $inv->getDecimals('invoice/taxAmount'));
+                $item->taxableAmount = $inv->round($item->taxableAmount, 'invoice/allowancesChargesAmount');
+                $item->taxAmount = $inv->round($item->taxAmount, 'invoice/taxAmount');
             }
         }