Merge pull request #5 from josemmo/develop

v0.1.2

.github/workflows/ci.yml

@@ -8,6 +8,7 @@ jobs:
     runs-on: ubuntu-latest
     continue-on-error: ${{ matrix.experimental || false }}
     strategy:
+      fail-fast: false
       matrix:
         php-version: ['7.1', '7.2', '7.3', '7.4']
         include:
@@ -26,7 +27,7 @@ jobs:
         with:
           php-version: ${{ matrix.php-version }}
           coverage: none
-          extensions: ast
+          extensions: ast-stable
 
       # Setup Composer
       - name: Setup Composer
@@ -35,7 +36,7 @@ jobs:
       # Run static analyzer
       - name: Run static analyzer
         if: ${{ success() && matrix.php-version != '7.1' }}
-        run: vendor/bin/phan
+        run: vendor/bin/phan --color --no-progress-bar
 
       # Run tests
       - name: Run tests
@@ -51,9 +52,8 @@ jobs:
        # Deploy documentation
       - name: Deploy documentation
         if: ${{ success() && matrix.deploy || false }}
-        uses: JamesIves/github-pages-deploy-action@3.7.1
+        uses: JamesIves/github-pages-deploy-action@4.1.4
         with:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          BRANCH: gh-pages
-          FOLDER: site
-          CLEAN: true # Automatically remove deleted files from the deploy branch
+          branch: gh-pages
+          folder: site
+          clean: true # Automatically remove deleted files from the deploy branch

.phan/config.php

@@ -1,20 +1,42 @@
 <?php
+use Phan\Issue;
+
 /**
  * This configuration will be read and overlaid on top of the
- * default configuration. Command-line arguments will be applied
+ * default configuration. Command line arguments will be applied
  * after this file is read.
+ *
+ * @see https://github.com/phan/phan/wiki/Phan-Config-Settings for all configurable options
+ * @see src/Phan/Config.php for the configurable options in this version of Phan
+ *
+ * A Note About Paths
+ * ==================
+ *
+ * Files referenced from this file should be defined as
+ *
+ * ```
+ *   Config::projectPath('relative_path/to/file')
+ * ```
+ *
+ * where the relative path is relative to the root of the
+ * project which is defined as either the working directory
+ * of the phan executable or a path passed in via the CLI
+ * '-d' flag.
  */
 return [
-    // Supported values: `'5.6'`, `'7.0'`, `'7.1'`, `'7.2'`, `'7.3'`,
-    // `'7.4'`, `null`.
+    // The PHP version that the codebase will be checked for compatibility against.
+    // For best results, the PHP binary used to run Phan should have the same PHP version.
+    // (Phan relies on Reflection for some types, param counts,
+    // and checks for undefined classes/methods/functions)
+    //
+    // Supported values: `'5.6'`, `'7.0'`, `'7.1'`, `'7.2'`, `'7.3'`, `'7.4'`,
+    // `'8.0'`, `'8.1'`, `null`.
     // If this is set to `null`,
     // then Phan assumes the PHP version which is closest to the minor version
     // of the php executable used to execute Phan.
     //
-    // Note that the **only** effect of choosing `'5.6'` is to infer
-    // that functions removed in php 7.0 exist.
+    // Note that the **only** effect of choosing `'5.6'` is to infer that functions removed in php 7.0 exist.
     // (See `backward_compatibility_checks` for additional options)
-    // TODO: Set this.
     'target_php_version' => null,
 
     // A list of directories that should be parsed for class and
@@ -26,15 +48,9 @@
     // your application should be included in this list.
     'directory_list' => [
         'src',
-        'vendor/josemmo/uxml'
+        'vendor',
     ],
 
-    // A regex used to match every file name that you want to
-    // exclude from parsing. Actual value will exclude every
-    // "test", "tests", "Test" and "Tests" folders found in
-    // "vendor/" directory.
-    'exclude_file_regex' => '@^vendor/.*/(tests?|Tests?)/@',
-
     // A directory list that defines files that will be excluded
     // from static analysis, but whose class and method
     // information should be included.
@@ -47,28 +63,128 @@
     //       should be added to both the `directory_list`
     //       and `exclude_analysis_directory_list` arrays.
     'exclude_analysis_directory_list' => [
-        'vendor/'
+        'vendor',
     ],
 
-    // Set to true in order to attempt to detect unused variables.
-    // `dead_code_detection` will also enable unused variable detection.
+    // If enabled, Phan will warn if **any** type in a method invocation's object
+    // is definitely not an object,
+    // or if **any** type in an invoked expression is not a callable.
+    // Setting this to true will introduce numerous false positives
+    // (and reveal some bugs).
+    'strict_method_checking' => true,
+
+    // If enabled, Phan will warn if **any** type in the argument's union type
+    // cannot be cast to a type in the parameter's expected union type.
+    // Setting this to true will introduce numerous false positives
+    // (and reveal some bugs).
+    'strict_param_checking' => true,
+
+    // If enabled, Phan will warn if **any** type in a property assignment's union type
+    // cannot be cast to a type in the property's declared union type.
+    // Setting this to true will introduce numerous false positives
+    // (and reveal some bugs).
+    // (For self-analysis, Phan has a large number of suppressions and file-level suppressions, due to \ast\Node being difficult to type check)
+    'strict_property_checking' => true,
+
+    // If enabled, Phan will warn if **any** type in a returned value's union type
+    // cannot be cast to the declared return type.
+    // Setting this to true will introduce numerous false positives
+    // (and reveal some bugs).
+    // (For self-analysis, Phan has a large number of suppressions and file-level suppressions, due to \ast\Node being difficult to type check)
+    'strict_return_checking' => true,
+
+    // If enabled, Phan will warn if **any** type of the object expression for a property access
+    // does not contain that property.
+    'strict_object_checking' => true,
+
+    // If enabled, check all methods that override a
+    // parent method to make sure its signature is
+    // compatible with the parent's. This check
+    // can add quite a bit of time to the analysis.
+    // This will also check if final methods are overridden, etc.
+    'analyze_signature_compatibility' => true,
+
+    // If true, check to make sure the return type declared
+    // in the doc-block (if any) matches the return type
+    // declared in the method signature.
+    'check_docblock_signature_return_type_match' => true,
+
+    // If true, check to make sure the param types declared
+    // in the doc-block (if any) matches the param types
+    // declared in the method signature.
+    'check_docblock_signature_param_type_match' => true,
+
+    // Set to true in order to attempt to detect dead
+    // (unreferenced) code. Keep in mind that the
+    // results will only be a guess given that classes,
+    // properties, constants and methods can be referenced
+    // as variables (like `$class->$property` or
+    // `$class->$method()`) in ways that we're unable
+    // to make sense of.
     //
-    // This has a few known false positives, e.g. for loops or branches.
-    'unused_variable_detection' => true,
+    // To more aggressively detect dead code,
+    // you may want to set `dead_code_detection_prefer_false_negative` to `false`.
+    'dead_code_detection' => true,
+
+    // Set to true in order to attempt to detect redundant and impossible conditions.
+    //
+    // This has some false positives involving loops,
+    // variables set in branches of loops, and global variables.
+    'redundant_condition_detection' => true,
+
+    // Set to true in order to attempt to detect error-prone truthiness/falsiness checks.
+    //
+    // This is not suitable for all codebases.
+    'error_prone_truthy_condition_detection' => true,
+
+    // Enable or disable support for generic templated
+    // class types.
+    'generic_types_enabled' => true,
 
     // If enabled, warn about throw statement where the exception types
     // are not documented in the PHPDoc of functions, methods, and closures.
     'warn_about_undocumented_throw_statements' => true,
 
-    // If enabled (and warn_about_undocumented_throw_statements is enabled),
-    // warn about function/closure/method calls that have (at)throws
-    // without the invoking method documenting that exception.
+    // If enabled (and `warn_about_undocumented_throw_statements` is enabled),
+    // Phan will warn about function/closure/method invocations that have `@throws`
+    // that aren't caught or documented in the invoking method.
     'warn_about_undocumented_exceptions_thrown_by_invoked_functions' => true,
 
-    // A list of plugin files to execute
-    // NOTE: values can be the base name without the extension for plugins bundled with Phan (E.g. 'AlwaysReturnPlugin')
-    // or relative/absolute paths to the plugin (Relative to the project root).
+    // The minimum severity level to report on. This can be
+    // set to Issue::SEVERITY_LOW, Issue::SEVERITY_NORMAL or
+    // Issue::SEVERITY_CRITICAL.
+    'minimum_severity' => Issue::SEVERITY_NORMAL,
+
+    // Add any issue types (such as `'PhanUndeclaredMethod'`)
+    // to this list to inhibit them from being reported.
+    'suppress_issue_types' => [
+        'PhanUnreferencedClass',
+        'PhanUnreferencedPublicMethod',
+    ],
+
+    // A list of plugin files to execute.
+    // Plugins which are bundled with Phan can be added here by providing their name
+    // (e.g. 'AlwaysReturnPlugin')
+    //
+    // Documentation about available bundled plugins can be found
+    // at https://github.com/phan/phan/tree/v4/.phan/plugins
+    //
+    // Alternately, you can pass in the full path to a PHP file
+    // with the plugin's implementation.
+    // (e.g. 'vendor/phan/phan/.phan/plugins/AlwaysReturnPlugin.php')
     'plugins' => [
+        'AlwaysReturnPlugin', // Checks if a function, closure or method unconditionally returns.
+        'DollarDollarPlugin',
+        'DuplicateArrayKeyPlugin',
+        'DuplicateExpressionPlugin',
+        'EmptyStatementListPlugin',
+        'InlineHTMLPlugin',
+        'LoopVariableReusePlugin',
         'PreferNamespaceUsePlugin',
-    ]
+        'PregRegexCheckerPlugin',
+        'PrintfCheckerPlugin',
+        'SleepCheckerPlugin',
+        'UnreachableCodePlugin', // Checks for syntactically unreachable statements in the global scope or function bodies.
+        'UseReturnValuePlugin',
+    ],
 ];

README.md

@@ -1,16 +1,20 @@
-# European Invoicing (eInvoicing)
-[![Build Status](https://github.com/josemmo/einvoicing/workflows/CI/badge.svg)](https://github.com/josemmo/einvoicing/actions)
-[![Latest Version](https://img.shields.io/packagist/v/josemmo/einvoicing?include_prereleases)](https://packagist.org/packages/josemmo/einvoicing)
-[![Minimum PHP Version](https://img.shields.io/packagist/php-v/josemmo/einvoicing)](#installation)
-[![License](https://img.shields.io/github/license/josemmo/einvoicing)](LICENSE)
-[![Documentation](https://img.shields.io/badge/online-docs-blueviolet)](https://josemmo.github.io/einvoicing/)
+<h1 align="center">
+    <a href="https://josemmo.github.io/einvoicing/"><img src="docs/logo.svg" width="100" alt=""><br>European Invoicing (eInvoicing)</a>
+</h1>
 
+<p align="center">
+    <a href="https://github.com/josemmo/einvoicing/actions"><img src="https://github.com/josemmo/einvoicing/workflows/CI/badge.svg" alt="Build Status"></a>
+    <a href="https://packagist.org/packages/josemmo/einvoicing"><img src="https://img.shields.io/packagist/v/josemmo/einvoicing" alt="Latest Version"></a>
+    <a href="#installation"><img src="https://img.shields.io/packagist/php-v/josemmo/einvoicing" alt="Supported PHP Versions"></a>
+    <a href="LICENSE"><img src="https://img.shields.io/github/license/josemmo/einvoicing" alt="License"></a>
+    <a href="https://josemmo.github.io/einvoicing/"><img src="https://img.shields.io/badge/online-docs-blueviolet" alt="Documentation"></a>
+</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).
 
 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/).
 
-> ⚠️ WARNING: This library is almost ready for production. Some features may not be available yet. ⚠️
-
 ## Installation
 First of all, make sure your environment meets the following requirements:
 
@@ -24,9 +28,72 @@ composer require josemmo/einvoicing
 ```
 
 ## Usage
-For a quick guide on how to get started, visit the documentation website at
+For a proper quick start guide, visit the documentation website at
 [https://josemmo.github.io/einvoicing/](https://josemmo.github.io/einvoicing/).
 
+### Importing invoice documents
+```php
+use Einvoicing\Exceptions\ValidationException;
+use Einvoicing\Readers\UblReader;
+
+$reader = new UblReader();
+$document = file_get_contents(__DIR__ . "/example.xml");
+$inv = $reader->import($document);
+try {
+    $inv->validate();
+} catch (ValidationException $e) {
+    // Invoice is not EN 16931 complaint 
+}
+```
+
+### Exporting invoice documents
+```php
+use Einvoicing\Identifier;
+use Einvoicing\Invoice;
+use Einvoicing\InvoiceLine;
+use Einvoicing\Party;
+use Einvoicing\Presets;
+use Einvoicing\Writers\UblWriter;
+
+// Create PEPPOL invoice instance
+$inv = new Invoice(Presets\Peppol::class);
+$inv->setNumber('F-202000012')
+    ->setIssueDate(new DateTime('2020-11-01'))
+    ->setDueDate(new DateTime('2020-11-30'));
+
+// Set seller
+$seller = new Party();
+$seller->setElectronicAddress(new Identifier('9482348239847239874', '0088'))
+    ->setCompanyId(new Identifier('AH88726', '0183'))
+    ->setName('Seller Name Ltd.')
+    ->setTradingName('Seller Name')
+    ->setVatNumber('ESA00000000')
+    ->setAddress(['Fake Street 123', 'Apartment Block 2B'])
+    ->setCity('Springfield')
+    ->setCountry('DE');
+$inv->setSeller($seller);
+
+// Set buyer
+$buyer = new Party();
+$buyer->setElectronicAddress(new Identifier('ES12345', '0002'))
+    ->setName('Buyer Name Ltd.')
+    ->setCountry('FR');
+$inv->setBuyer($buyer);
+
+// Add a product line
+$line = new InvoiceLine();
+$line->setName('Product Name')
+    ->setPrice(100)
+    ->setVatRate(16)
+    ->setQuantity(1);
+$inv->addLine($line);
+
+// Export invoice to a UBL document
+header('Content-Type: text/xml');
+$writer = new UblWriter();
+echo $writer->export($inv);
+```
+
 ## Roadmap
 These are the expected features for the library and how's it going so far:
 

composer.json

@@ -29,12 +29,12 @@
     },
     "require": {
         "php": ">=7.1",
-        "josemmo/uxml": "^0.1.1"
+        "josemmo/uxml": "^0.1.2"
     },
     "require-dev": {
         "ext-openssl": "*",
-        "phan/phan": "^4",
+        "phan/phan": "^5.0",
         "phpdocumentor/reflection": "^4.0",
-        "symfony/phpunit-bridge": "^5.2"
+        "symfony/phpunit-bridge": "^5.3"
     }
 }