Zumokit Bundle Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package — there is no service provider auto-discovery, no config/zumokit.php publish step, and no Laravel-facing facade. Treat it as a PHP domain library you wire into Laravel yourself.

1. composer require the package and confirm it does not hard-require the Symfony framework beyond symfony/* contracts you already tolerate.
2. Read Resources/doc/index.rst and Resources/doc/index.md first — both were added in 1.0.9, so prior to this release there was effectively no entry-point documentation. index.md covers Zumokit Bundle integration specifically.
3. Register the bundle's services in a small ZumokitServiceProvider using explicit $this->app->bind(...) calls; do not attempt to reuse the Symfony DI extension class.
4. First use case: create a user, attach a wallet (crypto account), then read it back through the repository/service layer.

// app/Providers/ZumokitServiceProvider.php
public function register(): void
{
    $this->app->bind(
        \ZumoKit\Bundle\Wallet\WalletRepositoryInterface::class,
        \App\Zumokit\DoctrineWalletRepository::class // or your adapter
    );
}

Before 1.0.9 the interfaces assumed one wallet per user, so any tutorial or snippet older than this release is wrong — start from the shipped docs, not from blog posts.

Implementation Patterns

Interface-first wiring. The bundle exposes User and Wallet interfaces rather than concrete entities. In Laravel you will almost certainly not reuse the bundled Doctrine entities; instead implement the interfaces on your Eloquent models or wrap them:

class User extends Authenticatable implements \ZumoKit\Bundle\User\UserInterface
{
    public function getWallets(): Collection
    {
        return $this->wallets; // hasMany(Wallet::class)
    }
}

Multiple wallets per user (new in 1.0.9). The dominant pattern is now a collection, not a scalar. Typical flows:

• List all wallets: foreach ($user->getWallets() as $wallet) { ... }
• Resolve a specific account by currency/network before an operation, and fail loudly if ambiguous:

  $wallet = $user->getWallets()->firstWhere('currency', $currency)
      ?? throw new WalletNotFoundException($currency);
  

• Persist a new wallet through the repository rather than mutating the collection directly, so the bundle's own invariants (address derivation, account indexing) still apply.

Adapter layer over Eloquent. Keep the bundle's domain services untouched and put translation logic in App\Zumokit\* classes. This is the only sane way to survive future Symfony/Doctrine-driven signature changes without rewriting controllers.

Testing. 1.0.9 adds phpunit.xml.dist and functional-test plumbing. Mirror that structure: bind in-memory fakes of the wallet/user interfaces in tests/TestCase, and assert against your adapters, not the bundle internals. The phpstan-symfony addition signals the upstream is now statically analysed — running PHPStan (with phpstan/phpstan-larastan on your side) will catch interface drift early.

CI parity. Travis CI and Flint CI configs landed upstream. Reproduce the useful parts (static analysis + functional suite) in GitHub Actions so your integration breaks at PR time, not on composer update.

Gotchas and Tips

• The version number lies. 1.0.9 is a patch bump, but "now we support multiple wallets" is a breaking interface change. Any code calling getWallet() (singular) or type-hinting a single WalletInterface return will fatal. Pin to 1.0.9 deliberately and grep your codebase for single-wallet assumptions.
• Removed excess code is unqualified. The changelog gives no list. Diff vendor/ between 1.0.8 and 1.0.9, or check the tag comparison on GitHub, before assuming a method you rely on still exists.
• Symfony/Doctrine assumptions leak. Resources/doc/index.rst is reStructuredText because this is a Symfony bundle. Doctrine mapping, bundle extension config, and Symfony event dispatcher are all things Laravel does differently — budget time for a manual bridge; do not expect vendor:publish to help.
• Container mismatch. The Symfony Extension class and services.yaml will not be loaded in Laravel. If you find yourself instantiating Symfony ContainerBuilder, stop — bind the concrete classes manually instead.
• Debugging. Since nothing is auto-wired, a Target [X] is not instantiable error almost always means a missing bind() in your provider, not a package bug. php artisan tinker plus app()->make(SomeBundleService::class) is the fastest sanity check.
• Extension points to favour: the User/Wallet interfaces and the repository abstraction. These are the surfaces the maintainers just changed intentionally — build against them rather than against concrete classes, and the next interface revision costs you one adapter edit instead of a refactor.
• Docs location. Resources/doc/ inside vendor/ is not browsable in the browser. Read it in the editor, and consider copying index.md into your own docs/zumokit.md so the integration notes survive a composer update.