Api Support Classes Laravel Package

Getting Started

firefly-iii/api-support-classes is a small, low-level library that holds classes shared between the Firefly III core application and its API layer. It is not a standalone product — it exists so the API payload shapes (resources, transformers, value objects, shared constants) can be versioned and consumed without pulling in the entire Firefly III monolith. For most applications it arrives as a transitive dependency; you only add it explicitly when you need to speak Firefly III's API dialect from your own code.

Minimal steps:

composer require firefly-iii/api-support-classes

1. Read composer.json first. That is your real documentation here. Check the PSR-4 root (the namespace is under FireflyIII\...) and, more importantly, the php and illuminate/* constraints. The package tracks Firefly III releases, so its constraints tell you which Firefly version it is designed to match.
2. Skim src/. With a package this size the class list is the API. Look for resource/transformer classes and any constant or enum-like classes describing account types, transaction types, or webhook events.
3. Grep the main Firefly III repo for the namespace. Because this package is extracted from the monolith, the most reliable usage examples are in firefly-iii/firefly-iii itself. Search for the fully-qualified class names there rather than trusting the package README (which is typically terse).
4. Confirm there is nothing to register. Packages of this shape usually ship no service provider, no facade, and no publishable config. Composer autoloading is the whole integration.

First use case: you are writing a service or plugin that must produce or consume Firefly III API payloads and you want the serialized output to match exactly what the Firefly instance emits — same field names, same type coercion, same JSON:API envelope. Instantiate (or call) the relevant support class, serialize, and return.

Implementation Patterns

Adopt it as an internal contract, not a public dependency. Wrap the package behind a thin adapter of your own:

namespace App\Support;

use FireflyIII\...\SomeResource; // whatever the package actually exposes

final class FireflyApi
{
    public function accountPayload(array $attributes): array
    {
        return (new SomeResource($attributes))->toArray();
    }
}

Everything else in your app depends on FireflyApi, never on the package directly. When the package's classes shift, you patch one file.

Pin to the same minor version as the Firefly instance you talk to. If you are integrating against Firefly III 6.x, constrain the package to the matching line. Treat the pair as a single deployment unit and upgrade them together.

Use it to build test fixtures. The single highest-value day-to-day use is generating realistic API responses for your test suite:

$response = $this->fireflyApi->accountPayload($this->accountAttributes());

$this->assertJsonPath('data.attributes.name', 'Checking');

This catches the "my payload looks right but Firefly rejects it" class of bug before it reaches a live instance.

Mirror it in validation. If the package defines allowed values (account types, transaction types), build your FormRequest::rules() from those same definitions rather than hard-coding a Rule::in([...]) list that will silently drift.

Inside a Firefly III installation (custom module, local plugin, theme work), the package is already present — reference its classes directly instead of copying constants into your module. Duplicated constants are the most common source of "the API accepts it but the UI does not" inconsistencies.

Keep a contract test against a real instance. A small integration test that posts your generated payload to a disposable Firefly III container and asserts a 200/201 is worth more than any unit test here, because it validates the package version, your adapter, and the server together.

Gotchas and Tips

• Version coupling is the dominant failure mode. The classes evolve in lockstep with Firefly III releases. A mismatched pair usually does not throw — it silently emits a payload with a missing or renamed field that Firefly ignores or rejects with an unhelpful 422. Pin constraints and assert on the output shape.
• Expect thin documentation. With zero dependents there is effectively no community knowledge base, no Stack Overflow trail, and no ecosystem of examples. Budget time to read the source and the main repository. The source is small; this is tractable, but do not plan on searching your way out of a problem.
• No stability guarantee. Treat the package as internal API. Semantic versioning is followed loosely at best on a 0.x line, and minor bumps have historically been the place where shapes change. Your adapter wrapper plus a lockfile is the mitigation.
• Potential namespace collision. The classes live under FireflyIII\.... If the full monolith is also installed in the same project, you have two sources for the same namespace. Composer will autoload only one, and which one wins depends on autoload ordering. Do not install both deliberately.
• No service provider, facade, or config file is shipped. If you find yourself looking for config/api-support-classes.php or a FireflyApi facade, stop — instantiate the classes directly or write your own binding in a service provider.
• Debugging technique: dump your serialized payload with json_encode(..., JSON_PRETTY_PRINT) and diff it field-by-field against a real GET /api/v1/... response from a running instance. Also fetch the Firefly III OpenAPI spec from the instance and compare your output against the schema — that is the authoritative description of what the server expects.
• Extension points are limited. Composition beats inheritance here: build your own resource class that delegates to the package's where useful, rather than subclassing transformers whose internals may change between releases.
• When not to use it: if you only need to call a handful of Firefly endpoints, a plain HTTP client with hand-written arrays will be less fragile than tracking this package's release cadence. The package earns its place when you need exact serialization fidelity or are extending Firefly III itself.