Merge pull request #51 from josemmo/develop

v1.5.0

.travis.yml

@@ -19,6 +19,10 @@ matrix:
   allow_failures:
     - php: nightly
 
+# Prepare environment
+before_install:
+  - if [ "$TRAVIS_PULL_REQUEST" != "false" ]; then unset SEND_COVERAGE; unset TEST_WEBSERVICES; fi
+
 # Install Composer package before testing
 install:
   - composer install --no-interaction

doc/extensiones/extensiones.md

@@ -6,6 +6,52 @@ permalink: /extensiones/
 ---
 
 # Extensiones
-Las [extensiones de formato](http://www.facturae.gob.es/formato/Paginas/extensiones-formato.aspx) son complementos que añaden funcionalidad al formato FacturaE. Facturae-PHP dispone de una interfaz propia para gestionar estas extensiones.
+Las [extensiones de formato](http://www.facturae.gob.es/formato/Paginas/extensiones-formato.aspx) son complementos que añaden funcionalidad al formato FacturaE. Similarmente, Facturae-PHP dispone de una interfaz propia para gestionar estas extensiones.
 
-Una extensión puede ser accedida desde cualquier factura a través de `$fac->getExtension()` y cada extensión dispone de su propio set de métodos, memoria interna y funcionalidad.
+Una extensión puede ser accedida desde cualquier factura a través del método `$fac->getExtension()` y cada extensión dispone de su propio set de métodos, estado interno y funcionalidad.
+
+## Extensiones de terceros
+Además de las extensiones incluidas con Facturae-PHP, desde la versión 1.5.0 es posible utilizar clases externas como extensiones. Esto permite a las empresas **añadir lógica de negocio propia** a esta librería sin la obligación de compartir el código fuente bajo licencia MIT.
+
+Para usar una extensión de terceros se deberá llamar al mismo método de antes con el nombre de la clase como parámetro:
+```php
+$awesome = $fac->getExtension(AwesomeExtension::class);
+```
+
+Una extensión de Facturae-PHP tiene un aspecto similar a este:
+```php
+class AwesomeExtension extends josemmo\Facturae\Extensions\FacturaeExtension {
+  // NOTA: todos los métodos de este ejemplo son opcionales
+
+  public function __getAdditionalData() {
+    // Devuelve un string con el XML a inyectar en el bloque
+    // "AdditionalData/Extensions" de un documento FacturaE.
+  }
+
+  public function __onBeforeExport() {
+    // Lógica a ejecutar antes de exportar (generar el XML)
+    // de una factura. Indicado para realizar acciones sobre
+    // la instancia de la factura, que se puede obtener a
+    // través del método `$this->getInvoice()`.
+  }
+
+  public function __onBeforeSign($xml) {
+    // Lógica a ejecutar cuando el XML de la factura ya está
+    // generado pero todavía no ha sido firmado.
+    // Útil para modificar el XML antes de firmarlo, que
+    // recibe por parámetro.
+    return $xml;
+  }
+
+  public function __onAfterSign($xml) {
+    // Lógica a ejecutar después de haber firmado el XML de la
+    // factura y antes de ser devuelto por el método `export()`.
+    // Útil para modificar el XML después de firmarlo, que
+    // recibe por parámetro.
+    return $xml;
+  }
+
+  // Otros métodos propios de la clase
+
+}
+```

src/Controller/Extensions/Extension.php → src/Extensions/FacturaeExtension.php

@@ -1,11 +1,9 @@
 <?php
-namespace josemmo\Facturae\Controller\Extensions;
-
-abstract class Extension {
+namespace josemmo\Facturae\Extensions;
 
+abstract class FacturaeExtension {
   private $fac;
 
-
   /**
    * Constructor function
    * @param Facturae $fac Parent invoice object
@@ -34,6 +32,14 @@ public function __getAdditionalData() {
   }
 
 
+  /**
+   * On before export
+   */
+  public function __onBeforeExport() {
+    // NOTE: Nothing done by default
+  }
+
+
   /**
    * On before sign
    * @param  string $xml Input XML

src/Controller/Extensions/Fb2bExtension.php → src/Extensions/Fb2bExtension.php

@@ -1,16 +1,14 @@
 <?php
-namespace josemmo\Facturae\Controller\Extensions;
+namespace josemmo\Facturae\Extensions;
 
 use josemmo\Facturae\FacturaeCentre;
 
-class Fb2bExtension extends Extension {
-
+class Fb2bExtension extends FacturaeExtension {
   private $publicSectorInfo = array();
   private $receiver = null;
   private $sellerCentres = array();
   private $buyerCentres = array();
 
-
   /**
    * Set public organism code
    * @param string $code Public organism code
@@ -71,8 +69,7 @@ private function centresToXml($centres) {
 
 
   /**
-   * Get additional data
-   * @return string|null Additional XML data
+   * @inheritdoc
    */
   public function __getAdditionalData() {
     if (empty($this->receiver)) return null;