README

Simple wrapper for the official PHP package https://github.com/fakturoid/fakturoid-php supporting the recent version 3

Docs

Installation
Configuration
Examples
Upgrade Guide

Installation

Step 1: Install package

Add the package in your composer.json by executing the command.

composer require szymsza/laravel-fakturoid

This will both update composer.json and install the package into the vendor/ directory.

Step 2: Configuration

First initialise the config file by running this command:

php artisan vendor:publish --provider="WEBIZ\LaravelFakturoid\FakturoidServiceProvider" --tag="config"

With this command, initialize the configuration and modify the created file, located under config/fakturoid.php.

Configuration

return [
    'account_name' => env('FAKTUROID_NAME', 'XXX'), // URL slug of your account
    'account_api_id' => env('FAKTUROID_API_ID', 'XXX'), // found in your Fakturoid user account settings
    'account_api_secret' => env('FAKTUROID_API_SECRET', 'XXX'), // found in your Fakturoid user account settings
    'app_contact' => env('FAKTUROID_APP_CONTACT', 'Application <your@email.cz>'), // linked to the application you are developing
];

Examples

Create Subject, Create Invoice, Send Invoice (API v3-style)

use Fakturoid;

try {
    // create subject
    $subject = Fakturoid::getSubjectsProvider()->create([
        'name' => 'Firma s.r.o.',
        'email' => 'aloha@pokus.cz'
    ]);
    if ($subject->getBody()) {
        $subject = $subject->getBody();

        // create invoice with lines
        $lines = [
            [
                'name' => 'Big sale',
                'quantity' => 1,
                'unit_price' => 1000
            ],
        ];

        $invoice = Fakturoid::getInvoicesProvider()->create(['subject_id' => $subject->id, 'lines' => $lines]);
        $invoice = $invoice->getBody();

        // send created invoice
        Fakturoid::getInvoicesProvider()->fireAction($invoice->id, 'deliver');
    }
} catch (\Exception $e) {
    dd($e->getCode() . ": " . $e->getMessage());
}

Create Subject, Create Invoice, Send Invoice (old API-style)

use Fakturoid;

try {
    // create subject
    $subject = Fakturoid::createSubject(array(
        'name' => 'Firma s.r.o.',
        'email' => 'aloha@pokus.cz'
    ));
    if ($subject->getBody()) {
        $subject = $subject->getBody();

        // create invoice with lines
        $lines = [
            [
                'name' => 'Big sale',
                'quantity' => 1,
                'unit_price' => 1000
            ],
        ];

        $invoice = Fakturoid::createInvoice(array('subject_id' => $subject->id, 'lines' => $lines));
        $invoice = $invoice->getBody();

        // send created invoice
        Fakturoid::fireInvoice($invoice->id, 'deliver');
    }
} catch (\Exception $e) {
    dd($e->getCode() . ": " . $e->getMessage());
}

Upgrade Guide

If you used the older version of this package communicating with Fakturoid API v2 (pre-March 2024), an update is required before the old API version gets turned off on 31st March 2025.

Standard upgrade guide:

Update the package to the latest version using Composer.
Update your configuration in config/fakturoid.php (see Configuration) or delete your config/fakturoid.php and publish the configuration again (see Installation: Step 2).
Edit your configuration in .env:
- Remove FAKTUROID_EMAIL and FAKTUROID_API_KEY
- Add FAKTUROID_API_ID and FAKTUROID_API_SECRET with credentials found in your Fakturoid user account settings

If you only used basic Fakturoid functionality, all might work as usual at this point. If not, the issue might be of two types:

Changes of the underlying API

Arguments and return types of Fakturoid API v3 calls are not always the same as in v2 - e.g., proforma boolean has been replaced by a document_type attribute when fetching invoices.

To see if you need to provide different arguments of should expect different return values, please consult the official Fakturoid API changelog.

Changes of the underlying PHP library

The PHP library this package provides a facade to has changed significantly. Although this wrapper tries to cover up most of these changes to make your code backwards compatible, some less commonly used methods or generally edge cases might case a problem. This can be usually recognized by a BadMethodCallException: Method 'XXX' does not exist on Fakturoid instance. or a similar exception thrown by the wrapper or the PHP library.

To solve this issue, please consult the PHP library documentation to learn how to call your functionality in the new API format (viewing the README diff might come in handy). E.g., to create a subject, instead of calling

Fakturoid::createSubject([...]);

you would now use

Fakturoid::->getSubjectsProvider()->create([...]);

as can be seen in the README diff on line 27, resp. 172.

If you do run into such unhandled comatibility problem, please consider submitting a pull request to the V2Compatibility trait of this package, or at least opening an issue in this repository.

szymsza / laravel-fakturoid

Maintainers

Details