square-bit/invoicexpress-for-laravel

Laravel package to integrate invoicexpress

v0.9.1 2023-06-24 16:31 UTC

Requires

• php: ^8.2
• illuminate/contracts: ^10.0
• spatie/laravel-data: ^3.5
• spatie/laravel-package-tools: ^1.14.0

Requires (Dev)

• guzzlehttp/guzzle: ^7.6
• laravel/pint: ^1.0
• nunomaduro/collision: ^7.9
• nunomaduro/larastan: ^2.0.1
• orchestra/testbench: ^8.0
• pestphp/pest: ^2.0
• pestphp/pest-plugin-arch: ^2.0
• pestphp/pest-plugin-faker: ^2.0
• pestphp/pest-plugin-laravel: ^2.0
• phpstan/extension-installer: ^1.1
• phpstan/phpstan-deprecation-rules: ^1.0
• phpstan/phpstan-phpunit: ^1.0

MIT

• Squarebit, Lda

• laravel
• square-bit
• invoicexpress-for-laravel

README

Integrate your Laravel application with InvoiceXpress' API

Concept

This package can be used on 2 different layers:

• via the provided Models.
• interacting directly with the API endpoint.

Using the former allows you to transparently create, update and delete entities both in your application's database and in InvoiceXpress.

Installation

You can install the package via composer:

composer require square-bit/invoicexpress-for-laravel

Optionally, you can publish and run the migrations:

php artisan vendor:publish --tag="invoicexpress-for-laravel-migrations"
php artisan migrate

You can publish the config file with:

php artisan vendor:publish --tag="invoicexpress-for-laravel-config"

This is the contents of the published config file:

return [
    'account' => [
        'name' => env('IX_ACCOUNT_NAME'),
        'api_key' => env('IX_API_KEY'),
    ],
    'service_endpoint' => 'app.invoicexpress.com',
    'eloquent' => [
        'persist' => false,
    ],
];

IX_ACCOUNT_NAME is your InvoiceXpress account name (the XXX in https://XXX.app.invoicexpress.com).

IX_API_KEY is the API key you can get from your InvoiceXpress account settings page.

persist defines whether to store the entities in your database, when using the "Model" layer. Default is false. If you set it to true, make sure you ran the migrations.

Usage

Option 1 - Via the model layer

With this approach, the package handles both local and remote changes to the entities.

This however is not enabled by default. To enable it:

• publish and run the migrations (see Installation)
• set persist => true in the config file (see Installation)

You can get a specific Item and update it:

use Squarebit\InvoiceXpress\API\Data\ItemData;
use Squarebit\InvoiceXpress\Model\IxItem;

$item = IxItem::find(1234);
$item->description = "a serious description";
$item->save();

Or you can create one:

$data = ItemData::from([...]);
$item = (new IxItem())->fromData($data)
    ->save();

Or even delete it:

$item->delete();

Invoice lifecycle:

use Squarebit\InvoiceXpress\API\Data\PdfData;

$invoice = (new IxInvoice())
    ->setClient(IxClient::findOrFail(1234)) // set the invoice's client
    ->addItem(IxItem::find(2345)) // add an IxItem model
    ->addItem(ItemData::from([....])) // you can also add from an ItemData
    ->addItems([  // or from an array
        ItemData::from([...]),
        IxItem::find(3579),
        ...
    ])
    ->save(); // creates the new invoice (locally and in InvoiceXpress)
    ->finalizeDocument() // formally registers the invoice
    ->email(); // email the invoice to the client

// Store the pdf locally
$pdf = $invoice->getPdf()->pdfUrl;
Storage::put('file.jpg', $pdf);

// Pay the invoice and email the receipt
$receipt = $invoice
    ->pay()
    ->email();

Option 2 - Directly using the endpoints

With this approach, only remote changes are handled. If you want, you'll have to manage local changes (in your database) manually.

You can get a specific Item and update it:

use Squarebit\InvoiceXpress\Facades\InvoiceXpress;

$itemsEndpoint = InvoiceXpress::items();

$itemData = $itemsEndpoint->get(1234);
$itemData->description = "a serious description";
$itemsEndpoint->update($itemData);

Or you can create one:

$data = ItemData::from([...]);
$itemData = InvoiceXpress::items()->create($itemData);

Or even delete it:

InvoiceXpress::items()->delete(1234);

Invoice lifecycle:

use Squarebit\InvoiceXpress\API\Data\ClientData;
use Squarebit\InvoiceXpress\API\Data\EmailClientData;
use Squarebit\InvoiceXpress\API\Data\EmailData;
use Squarebit\InvoiceXpress\API\Data\InvoiceData;
use Squarebit\InvoiceXpress\API\Data\ItemData;
use Squarebit\InvoiceXpress\API\Data\PartialPaymentData;
use Squarebit\InvoiceXpress\API\Data\StateData;
use Squarebit\InvoiceXpress\Enums\DocumentEventEnum;
use Squarebit\InvoiceXpress\Enums\EntityTypeEnum;
use Squarebit\InvoiceXpress\Facades\InvoiceXpress;

$invoiceEndpoint = InvoiceXpress::invoices();

// Create an Invoice
$invoiceData = $invoiceEndpoint->create(
    EntityTypeEnum::SimplifiedInvoice,
    InvoiceData::from([
        ...
        'client' => ClientData::from([
            ...
        ]),
        'items' => [
            ItemData::from([])
        ]
    ])
);

// Formally register it
$invoiceEndpoint->changeState(
    EntityTypeEnum::SimplifiedInvoice,
    $invoiceData->id,
    StateData::from([
        'state' => DocumentEventEnum::Finalized
    ])
);

// Email the Invoice
$invoiceEndpoint->sendByEmail(
    EntityTypeEnum::SimplifiedInvoice,
    $invoiceData->id,
    EmailData::from([
        'client_data' => EmailClientData::from([
            'email' => '[e-mail]'
        ]),
        'subject' => '...',
        'body' => '...',
        'cc' => '...',
        'bcc' => '...',
    ])
);

// Get the pdf
$pdfData = $invoiceEndpoint->generatePDF($invoiceData->id)

// Pay the invoice (in total)
$receiptData = $invoiceEndpoint->generatePayment([
    EntityTypeEnum::SimplifiedInvoice,
    $invoiceData->id,
    PartialPaymentData::from([
        'amount' => $invoiceData->total,
    ])
])

 

You can mix both options, if you want

$itemsEndpoint = InvoiceXpress::items();

// get an Item by querying the endpoint directly
$itemData = $itemsEndpoint->get(1234);

// create an IxItem model with that data and update it
$item = (new IxItem())->fromData($itemData);
$item->description = 'a more serious description';

// send the modifed data to InvoiceXpress
$itemsEndpoint->update($item->getData());

Available entities

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Squarebit, Lda
• All Contributors
• Spatie's Laravel Data

License

The MIT License (MIT). Please see License File for more information.