nfe-easy/nfe-easy

Easy package to manage NFe resources

NFeEasy

Introduction

NFeEasy is a wrapper to manage NFe files., _(*1)

Requirements

• PHP 7.0.13 or later

Instalation

Composer

You and install via composer:, _(*2)

$ composer require nfe-easy/nfe-easy

and use composer autoload:, _(*3)

require_once('vendor/autoload.php');

Manual Instalation

If you don't want to use Composer, download the latest version of NefEasy and include the init.php file:, _(*4)

require_once('/path/to/nfeasy/init.php');

You will also need to dowload the NfeEasy php dependencies and autoload then manually. See composer.json to see NfeEasy dependencies., _(*5)

How to use

To use the NfeEasy, just pass the xml nfe file content to the XmlInvoiceBuilder and it will returns the PHP objects representing the given NFe., _(*6)

XmlInvoiceBuilder::::create(
    file_get_contents('path/to//my/invoice.xml')
); // returns an instance of NFeEasy\Invoice

Domain Objects

Each Domain from NFe file is represented by an NFeEasy object class. These classes are called Domain Object Classes., _(*7)

The list of Domains Object Classes includes:, _(*8)

• NFeEasy\Invoice
• NFeEasy\Product
• NFeEasy\Emitter
• NFeEasy\Receiver
• NFeEasy\Address

A full NFe file is represented by a relationship between one or more NFeEasy Domain Objects Classes., _(*9)

The NFeEasy Domain Object Classes contain the data extracted from the NFe file. The data is diviled between the NfeEasy Domain Object Classes., _(*10)

For a full NfeEasy reprentation, use the NFeEasy\Builder\XmlInvoiceBuilder::create method. It will return an NFeEasy\Invoice instance., _(*11)

Invoice

The NFeEasy\Invoice represents the NFe file itself, and contains data to indentity the NFe., _(*12)

All other Domain Object Classes resides below Invoice Object., _(*13)

The table bellow describes all attributes you can access from NFeEasy\Invoice class:, _(*14)

Product

NFeEasy\Product represents an Invoice`s product. It contains informations like the name of the product, the NCM, the value, the quantity the taxes, and other product related things., _(*15)

The table bellow describes all attributes you can access from NFeEasy\Product class:, _(*16)

Emitter

NFeEasy\Emitter represents the NFe emitter, _(*17)

The table bellow describes all attributes you can access from NFeEasy\Product class:, _(*18)

Receiver

NFeEasy\Receiver represents the NFe Receiver, _(*19)

The table bellow describes all attributes you can access from NFeEasy\Product class:, _(*20)

Address

NFeEasy\Address represents an address object, _(*21)

The table bellow describes all attributes you can access from NFeEasy\Address class:, _(*22)

Creating Domain Objects

You can create Domain Object classes individually. Just use the method created from the respective object passing the parameters you wnat to populate into the object:, _(*23)

$address = Address::create([
    'xLgr' => 'Some address street',
    'nro' => '207'
]); // returns an NFeEasy\Address

If you dont't want to create the domain objects individually, you can pass all data directy to the NfeEasy\Invoice:, _(*24)

$invoice = Invoice::create([
    'cUF' => '32',
    'natOp' => 'Venda Sub / Venda Mer',
    'addicionalInfo' => 'Some Info',
    // ...
    'emitter' => [
        'xNome' => 'Emitter Name',
        'CNPJ' => '23740049120232'
        // ...
    ],
    'receiver' => [
        'xNome' => 'Receiver Name',
        'CNPJ' => '40193549120112'
        // ...
    ],
    'products' => [
        [
            'cProd' => '13'
            'xProd' => 'Shampoo'
            // ...
        ],
        [
            'cProd' => '345'
            'xProd' => 'Soap'
            // ...
        ],
        // ...
    ]
]); // returns an NFeEasy\Invoice

Attributes

After a Domain Object is created, you can access the data by access attributes by its names:, _(*25)

$product = Product::create([
    'cProd' => '12'
    'xProd' => 'Notebook'
]);

echo $product->xProd; // prints 'Shampoo'

You can access child objects by the attributes names too:, _(*26)

$emitter = Emitter::create([
    'xNome' => 'Andrew'
    'CNPJ' => '23740049120232',
    'address' => [
        'xLgr' => 'Rua Ivaí',
        'nro' => 207,
        'xBairro' => 'Tatuapé'
    ],
]);

$emitter->address;  // returns an instance of NfeEasy\Address;

echo $emitter->address->xBairro; prints 'Tatuapé'

Collections

Array of Domain Objects are treated as Collections into NfeEasy. All Object Collections are represented by an instance of Illuminate\Support\Collection., _(*27)

Collections in NfeEasy are used for:, _(*28)

• products attribute into Invoice Object

For example, to return the collection of products from an Invoice, use:, _(*29)

$products $invoice->products;  // Return an instance of `Illuminate\Support\Collection`.

To filter products with value greater than 20, use:, _(*30)

$products = $invoice->products->filter(function ($product, $key){
    return $product->vProd > 20;
});

For all Illuminate\Support\Collection available methods, see Illuminate Collection Docs., _(*31)

Serialization

All Domain objects implements Illuminate\Contracts\Support\Arrayable and Illuminate\Contracts\Support\Arrayable\Jsonable., _(*32)

So you can transform the all NfeEasy Domain objects easily:, _(*33)

$invoice => Invoice::create([
    // attributes data
]);

$invoice->toArray(); // converts the domains objects into arrays

$invoice->toJson(); // converts the domains objects into a json string

(string)$invoice; // converts the domains objects into a json string

Tests

NfeEasy uses PHPUnit unit tests for better reliablility and security., _(*34)

To run all tests, justs go to the project folder and type:, _(*35)

$ phpunit

License

NfeEasy is open-sourced software licensed under the MIT license., _(*36)