Download the PHP package codebar-ag/laravel-bexio without Composer

This package was developed to give you a quick start to the Bexio API.

💡 What is Bexio?

Bexio is a cloud-based simple business software for the self-employed, small businesses and startups.

🛠 Requirements

Authentication

The package supports multiple authentication methods for both single-tenant and multi-tenant applications:

⚙️ Installation

You can install the package via composer:

Optionally, you can publish the config file with:

🔐 Authentication Setup

Environment Variables

Add the following environment variables to your .env file:

You can retrieve your API token or OAuth credentials from your Bexio Developer Dashboard.

For OAuth credentials, you'll need to register your application in the Bexio Developer Portal.

🚀 Usage

Single Tenant Authentication

For applications that only need to authenticate with one Bexio account:

Token Authentication

OAuth Authentication

OAuth Flow

The package provides built-in routes for OAuth authentication:

1. Redirect to Bexio: /bexio/redirect
2. OAuth Callback: /bexio/callback

You can customize the route prefix and middleware in your config file:

OAuth Callback Response

After the OAuth callback is processed, the user will be redirected to the URL specified in your configuration (config('bexio.redirect_url') or / by default) with flash session data indicating the result:

Success Response:

Error Responses:

Handling the callback in your controller:

Multi-Tenant Authentication

For applications that need to authenticate with multiple Bexio accounts:

Token Authentication (Multi-Tenant)

OAuth Authentication (Multi-Tenant)

For multi-tenant OAuth, you need to create custom resolvers and bind them to Laravel's service container.

Step 1: Create Custom Config Resolver

this example is with the auth user as a tenant, but you can easily modify it to another model of your choice.

Step 2: Create Custom Authentication Store Resolver

this example is with the auth user as a tenant, but you can easily modify it to another model of your choice. you are also not required to use cache, you could store the authenticator on the model's database entry by updating a column on the model rather than using the Cache facade.

Step 3: Register Custom Resolvers

In your AppServiceProvider or a dedicated service provider:

Step 4: Using Multi-Tenant OAuth

Custom OAuth Authentication Validation (Optional)

You can implement custom validation logic that runs before the OAuth authenticator is stored. This is useful for:

• Validating user permissions with API calls
• Checking company/organization restrictions
• Implementing custom business logic
• Adding custom error handling with redirects

This feature is not limited to multi-tenant setups; it can be used in single-tenant applications as well.

Create Custom Validation Resolver:

Register the Custom Validator:

Add to your service provider:

Validation Result Types:

Error Handling:

When validation fails, users will be redirected with these session variables:

Available OAuth Scopes

The package automatically applies default OAuth scopes for OpenID Connect authentication. These default scopes are:

• openid - Required for OpenID Connect authentication
• profile - Access to basic profile information
• email - Access to email address
• company_profile - Access to company profile information
• offline_access - Enables refresh token functionality for long-term access

These default scopes are automatically included in all OAuth requests and cannot be removed. You can add additional scopes as needed for your application.

The package provides enums for OAuth scopes:

🔧 Advanced Configuration

Custom Cache Store

You can specify a custom cache store for OAuth token storage:

Custom Route Configuration

Route Middleware

The OAuth routes (/bexio/redirect and /bexio/callback) automatically include the web middleware group by default. You can add additional middleware using the route_middleware configuration:

Examples:

Common Use Cases:

• Authentication Required: Use ['auth'] to ensure only authenticated users can initiate OAuth flow
• Email Verification: Use ['auth', 'verified'] for applications requiring email verification
• Rate Limiting: Use ['throttle:10,1'] to limit OAuth attempts
• Custom Authorization: Add your own middleware to control who can access OAuth routes

The middleware will be applied to both OAuth routes:

• GET /bexio/redirect - Initiates OAuth flow
• GET /bexio/callback - Handles OAuth callback from Bexio

Basic Usage

After setting up authentication, create a connector instance:

Responses

The following responses are currently supported for retrieving the response body:

See https://docs.saloon.dev/the-basics/responses for more information.

Enums

We provide enums for the following values:

Note: When using the dto method on a response, the enum values will be converted to their respective enum class.

DTOs

We provide DTOs for the following:

In addition to the above, we also provide DTOs to be used for create and edit request for the following:

Note: This is the preferred method of interfacing with Requests and Responses however you can still use the json, object and collect methods. and pass arrays to the requests.

Examples

Here are some examples of how to use the package with different authentication methods:

Accounts

Addresses

Bank Accounts

Business Years

Calendar Years

Company Profiles

Additional Addresses

Contact Groups

Contact Relations

Contacts

Contact Sectors

Currencies

Files

Iban Payments

Invoices

Languages

Manual Entries

Notes

Payments

Qr Payments

Reports

Salutations

Taxes

Titles

VAT Periods

🚧 Testing

Copy your own phpunit.xml-file.

Run the tests:

📝 Changelog

Please see CHANGELOG for recent changes.

✏️ Contributing

Please see CONTRIBUTING for details.

Code Style

🧑‍💻 Security Vulnerabilities

Please review our security policy on reporting security vulnerabilities.

🙏 Credits

• Rhys Lees
• Sebastian Fix
• Kasper Nowak
• All Contributors
• Skeleton Repository from Spatie
• Laravel Package Training from Spatie
• Laravel Saloon by Sam Carré

🎭 License

The MIT License (MIT). Please have a look at License File for more information.