Bexio Connector Bundle Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package. In a Laravel app, do not try to install/use the bundle directly; use the underlying fatpanda-gmbh/bexio-connector library behind a small Laravel service provider/facade. In Symfony, the bundle’s only job is wiring the connector library into the container and exposing configuration.

Minimal Symfony setup:

composer require fatpanda-gmbh/bexio-connector-bundle

Register the bundle class from the package’s src/ namespace in config/bundles.php if Flex does not do it automatically. Then inspect the real config keys before writing YAML:

bin/console config:dump-reference bexio_connector
bin/console debug:container --show-private | grep -i bexio

Typical config shape will be OAuth/client credentials supplied by env vars:

# config/packages/bexio_connector.yaml
bexio_connector:
    client_id: '%env(BEXIO_CLIENT_ID)%'
    client_secret: '%env(BEXIO_CLIENT_SECRET)%'
    redirect_uri: '%env(BEXIO_REDIRECT_URI)%'

Look first at:

• DependencyInjection/Configuration.php in the bundle — the authoritative config tree.
• Resources/config/services.* — service IDs and aliases to inject.
• The underlying library’s client/service classes — actual API methods live there, not in the bundle.
• The bundle README/tests — especially for OAuth/token expectations.

First useful use case: complete the OAuth handshake, then perform a read-only call such as fetching a small page of contacts. Validate credentials, token refresh, and pagination before attempting invoice/order writes.

Implementation Patterns

Inject the connector, do not instantiate it. Find the service alias with debug:container, then wrap it in your own application service so API details do not leak into controllers/commands.

final class BexioContactImporter
{
    public function __construct(private object $bexioClient) {}

    public function importPage(int $offset = 0, int $limit = 100): void
    {
        // Call the underlying library's contact list method here.
        // Map Bexio DTOs/arrays to your domain entities.
    }
}

OAuth pattern. Keep the authorization callback route thin: exchange the code, persist the token, redirect back. Persist refresh tokens securely and update them when refreshed. If the bundle/library exposes a token store abstraction, use it rather than rolling your own; if not, decorate the client/service with your own token-aware wrapper.

Idempotent sync pattern. For contacts, invoices, orders, etc., store the Bexio ID as a unique external ID. Upsert by that ID, and make retries safe. Do not rely on “last sync time” alone — Bexio resources can be updated independently.

Queue writes and bulk syncs. Use Symfony Messenger for imports/exports and scheduled commands for polling. A day-to-day integration usually looks like:

• Cron command pulls changed contacts/invoices.
• Messenger handler maps and upserts records.
• Failures go to a failure transport for replay.
• Manual admin action triggers a targeted sync.

Read-before-write. Bexio APIs have required fields, country/currency conventions, and resource-specific validation. Fetch an existing record first when building create/update payloads, especially for invoices and orders.

Centralize error translation. Wrap HTTP/API exceptions into your own exception types. Retry 429 and transient 5xx; do not retry validation/authentication 4xx blindly. Log the Bexio request context without logging client secrets or tokens.

Multi-tenant caveat. The bundle is likely a singleton Symfony config. If you need one Bexio tenant per customer, use the underlying connector library/factory directly per tenant rather than fighting the bundle’s single configured client.

Gotchas and Tips

• Maintenance risk is the biggest issue. Last release was 2020-06-02, with effectively no dependents. Pin the version, check PHP/Symfony constraints with composer why-not, and expect to fork or bypass the bundle for modern Symfony versions.
• Not Laravel-compatible. There is no Laravel service provider or auto-discovery. In Laravel, consume fatpanda-gmbh/bexio-connector directly and bind the client in your own provider.
• Config cache quirks. Symfony caches resolved env vars. After changing .env, run bin/console cache:clear; in production use real environment variables, not runtime putenv.
• Redirect URI must match exactly. OAuth failures are often caused by trailing slashes, http/https mismatch, or a different host between the Bexio app config and Symfony route.
• Token expiry/refresh is where integrations break. Handle refresh centrally, serialize refreshes to avoid concurrent refresh-token invalidation, and persist rotated refresh tokens if Bexio returns them.
• Pagination and rate limits. Do not assume one request returns everything. Use small page sizes, backoff on 429, and make sync commands resumable.
• API drift. Bexio’s API and field requirements can change independently of this old wrapper. Keep mapping/validation in your app layer so API changes do not require patching vendor code.
• Debugging sequence: config:dump-reference bexio_connector → debug:config bexio_connector → debug:container | grep -i bexio → make one read-only API call with verbose HTTP logging.
• Extension points: decorate the bundle’s client service, override the token store, or register your own service using the underlying library client. Prefer decoration over editing vendor files.
• Testing: mock the underlying HTTP client or connector service in unit tests; keep a small sandbox/integration test for OAuth and one real read endpoint.