Kuali Companion Laravel Package

Getting Started

1. Install the package:

   composer require savannabits/kuali-companion
   

2. Publish and review the config (credentials, base URL, timeout) and add the values to .env. The config file is the first place to look — it tells you which Kuali endpoints/accounts the package is wired to.
3. Locate the main entry point: the KualiCompanion class (and its facade, if registered). This is the object you resolve from the container in your own services.
4. First use case to try end-to-end: build and post a Journal Voucher (JV). As of v1.2.0 you no longer need to construct the JV object yourself — call kualiJournalVoucher() on the companion to get a pre-wired instance, populate it, and post it to your Kuali sandbox.
5. Verify auth and connectivity with the simplest read call before attempting any posting, so you can separate credential problems from payload problems.

Implementation Patterns

• Resolve, don't instantiate. Inject the companion (via constructor or app()) rather than new-ing it, so config and HTTP client wiring are respected.
• Use the factory method for JVs. $kuali->kualiJournalVoucher() returns a JV instance bound to the companion's configuration — this is the intended v1.2.0+ pattern. Keep JV construction in one place (a dedicated service or action class) so a future signature change is a one-file fix.
• Wrap posting in a job. Journal voucher posting is a side-effecting, network-bound operation. Dispatch a queued job with $tries/backoff, and guard against double-posting with your own idempotency key or a "posted" flag on the local record.
• Persist before you post. Store the payload (or the domain record it was built from) locally with a status column (pending/posted/failed) plus the raw response. Reconciliation against Kuali becomes trivial.
• Keep payload assembly separate from transport. Build arrays/DTOs in your app, hand them to the companion. This makes the JV payload unit-testable without HTTP.
• Fake the HTTP layer in tests. Http::fake() around the companion's client lets you assert the outgoing JV document without hitting Kuali; assert on the shape of the ledger lines, not just the status code.
• Multi-environment config. Point staging at the Kuali sandbox and production at live; keep the two credential sets in separate env blocks so a copy-paste mistake can't post test vouchers to production.

Gotchas and Tips

• JV posting is marked experimental. Pin the version ("savannabits/kuali-companion": "1.2.*") and treat any minor bump as potentially behaviour-changing for JV payloads. Read the diff before upgrading in production.
• The kualiJournalVoucher() accessor is new in v1.2.0. Code written against v1.0.x that instantiated the JV class directly will still work but bypasses the companion's config; migrate those call sites so timeouts, base URL, and auth come from one place.
• Don't trust a 200. Kuali APIs can return success envelopes that still carry per-line validation errors. Inspect the response body for rejected lines and surface them — a partially accepted voucher is worse than a hard failure.
• Log the request/response pair on failure only. Full JV payloads are large and contain account codes; logging them at info on every call will flood your logs and leak financial data into places with looser retention.
• Config caching bites. After changing credentials or the base URL, run php artisan config:clear — a stale cached config is the most common cause of "it works locally, not in CI."
• Timeouts and retries. The default HTTP timeout is often too short for posting multi-line vouchers. Set an explicit timeout in config, and make retries safe (idempotent) before enabling them on the queue.
• Extension points. If the package exposes macros/bindings on the companion or a custom HTTP client, use those rather than copying the package's classes into your app — forked internals break silently on upgrade.
• Version-jump caution. The changelog goes v1.0.1 → v1.2.0 with no v1.1.x notes published in this release; skim the full compare link before assuming nothing else moved.