Laravel Accounting Laravel Package

Getting Started

This is a 0.1.0 feedback release with no published changelog beyond "first release," so treat the README and the source tree as the specification — there is no stable API contract to read against yet.

First steps:

1. composer require <vendor>/<package>:0.1.* — pin the minor explicitly rather than using ^0.1. You want upgrades to be a deliberate act while the public surface is still moving.
2. Read composer.json first, before any docs. The require block tells you the supported laravel/framework and PHP ranges, and extra.laravel.providers / extra.laravel.aliases tell you whether the package relies on auto-discovery or expects manual registration in bootstrap/providers.php (Laravel 11+) or config/app.php (10 and below).
3. Check for config/, database/migrations/, routes/, and resources/views/ in the package root. Anything publishable there defines your install sequence: php artisan vendor:publish --tag=<package>-config then php artisan migrate.
4. Skim src/ for the service provider and any Facade. That is the real entry point; anything not reachable from there is likely internal and will change.
5. Run the package's own test suite locally (vendor/bin/phpunit or vendor/bin/pest inside the package, or via orchestra/testbench if it ships a test harness) to see what behaviour the author actually asserts.

First use case: install into a throwaway Laravel app with a single representative flow, exercise the happy path end to end, and confirm what happens on the failure path (invalid input, missing config, absent credentials). At 0.1.0 the failure modes are usually where the rough edges are, and that is exactly the feedback this release is soliciting.

Implementation Patterns

Contain the blast radius behind your own boundary. Wrap the package's entry points in a single service class or a thin repository/adapter of your own, and inject that everywhere else. When 0.2.0 renames a method or changes a return type, you edit one file instead of grepping the codebase. This is the single highest-value pattern for a pre-1.0 dependency.

final class MyFeatureService
{
    public function __construct(private PackageClient $client) {}

    public function doThing(MyDto $dto): MyResult
    {
        // only place in the app that touches the package API
    }
}

Bind through the container, not new. Resolve the package's client/manager from the container (constructor injection or app(...)) so you can instance()-swap it with a fake in tests without touching production code.

Publish config, then own it. Publish once and commit the resulting config file. Never rely on the package's in-repo defaults for anything environment-sensitive — a 0.1.x patch can change a default and silently alter behaviour.

Evaluate with a Testbench test, not by hand. If you plan to depend on this long-term, a small orchestra/testbench test in your own suite that asserts the integration contract (config keys present, migrations run, the happy path returns what you expect) gives you a fast red/green signal on every bump.

Upgrade workflow. Bump the constraint, run composer update <vendor>/<package> --with-dependencies, then php artisan config:clear && php artisan cache:clear, then run your integration test. Diff the package's src/ between tags (composer require a second copy in a scratch project, or check the VCS diff) — at this stage the changelog will not cover the changes that matter.

Feedback loop. Since this release is explicitly for feedback gathering, file issues with a minimal reproduction (Laravel version, PHP version, package version, the failing call, the actual vs. expected result). That is the most useful thing you can do with a 0.1.0.

Gotchas and Tips

• Pre-1.0 semver is not your friend. Under semver, 0.1.x → 0.2.0 may contain breaking changes. composer outdated will happily show you the bump; composer update will not warn you. Pin 0.1.* and review before moving.

• Auto-discovery surprises. If the package registers a provider via extra.laravel.providers, it boots in every environment including php artisan package:discover during deploy. If discovery is cached (bootstrap/cache/packages.php), a stale cache after an upgrade produces "class not found" errors that look unrelated. php artisan package:discover and clear the cache.

• Config caching hides published config. In production, config:cache means edits to the published config file do nothing until you re-cache. A very common "the package ignores my settings" report.

• Queued jobs and serialized package objects. If the package exposes DTOs or value objects you push onto a queue, upgrading the package while old serialized jobs sit in the queue can produce unserialize failures or silently missing properties. Prefer serializing your own primitives into the job and reconstructing the package object in handle().

• Published migrations are yours now. Once you publish and run a package migration, the package cannot change that migration file retroactively. Watch for the package adding new columns in later releases without shipping a follow-up migration — you will need to write it yourself.

• Config keys are the least stable surface. Renamed or removed config keys fail silently (the new default applies) rather than throwing. When upgrading, diff the package's config/ directory against your published copy before assuming nothing changed.

• Debugging. php artisan about confirms the Laravel version and provider discovery; for container bindings, app()->bound(...) in tinker is quicker than reading the provider. If a Facade resolves to something unexpected, check whether the package binds an interface you have also bound — ordering in your own provider matters.

• Extension points to prefer. Contracts (interfaces) and config-driven strategy keys are usually the intended extension points and survive minor bumps. Concrete class extension is not: at 0.1.0, subclasses of package classes are the most likely thing to break.

• Do not build on undocumented behaviour. If you had to read src/ to make something work, assume it is incidental and will change. Open an issue asking for it to be documented or exposed — that is precisely the feedback this release is looking for.