Vantage Laravel Package

Getting Started

Vantage is installed like any Laravel package, and the surface area you touch day-to-day is small: config, migrations, and (as of v0.1.25) an optional HTTP API.

1. Install and publish.

   composer require storviaio/vantage
   php artisan vendor:publish --tag="vantage-config"
   php artisan vendor:publish --tag="vantage-migrations"   # if the package ships its own tables
   php artisan migrate
   

   Check config/vantage.php first — it is the single place that tells you whether the package is enabled, which storage/driver it uses, and (new in this release) whether the API is exposed.

2. Confirm the service provider is auto-discovered. Laravel's package discovery should register it; if you keep a hand-written config/app.php, verify the provider is listed. If routes 404 after install, this is almost always the cause.

3. First use case: read data through the package's own entry point before wiring anything custom. Whatever Vantage collects or exposes (dashboard routes, an artisan command, a facade), exercise it once locally with php artisan route:list | grep vantage and hit the endpoint or command directly. That gives you a known-good baseline before you integrate it into your app's own flows.

4. Only then turn on the API (new in v0.1.25). The REST/JSON API is described as optional, which in Laravel packages normally means a config flag plus a route file that is only loaded when enabled. Look for something like VANTAGE_API_ENABLED / 'api' => ['enabled' => ...] in the published config, enable it in .env for a non-production environment first, and confirm the routes appear in route:list before touching clients.

5. Issue a token. The API uses Bearer token authentication, so you need a token before your first request. Check the package's artisan commands (php artisan list | grep vantage) for a token-creation command, or the README for the model/table that backs tokens. Store the plaintext token in your secret manager — most token implementations only show it once.

Implementation Patterns

Treat the API as a read-only integration surface first. The pragmatic rollout is: enable the API, mint one token for a machine client, point a small internal tool or a scheduled job at it, and leave your application's write paths untouched until you have a reason to change them. Bearer-token APIs in early-stage packages (this is still 0.1.x) tend to evolve; keeping consumers behind an interface keeps the blast radius small.

Wrap the API in a client class, not scattered Http:: calls. A single VantageClient with a configured base URL and token means that when the route prefix, pagination parameters, or response envelope change, you edit one file:

// config/services.php
'vantage' => [
    'base_url' => env('VANTAGE_API_URL'),
    'token'    => env('VANTAGE_API_TOKEN'),
],

Http::baseUrl(config('services.vantage.base_url'))
    ->withToken(config('services.vantage.token'))
    ->acceptJson()
    ->retry(3, 200)
    ->get('/api/...');

Keep tokens per-consumer and per-environment. Because auth is a Bearer token, a leaked token is a leaked token. Issue separate tokens for local, staging, and each production consumer so you can revoke one without a coordinated redeploy. If the package stores tokens hashed, keep that column out of any export or seed you commit.

Gate the API routes by environment in your deploy pipeline. If the flag lives in config, it belongs in your .env templates with an explicit value (VANTAGE_API_ENABLED=false by default), not left to fall through to a package default you haven't read. This is the single most valuable habit with an "optional" feature.

Integrate with Laravel's own primitives rather than inventing new ones. If the API exposes data you also render in your app, prefer calling the package's PHP-side services directly inside your app and reserve the HTTP API for genuinely external or out-of-process consumers (other services, dashboards, mobile, CI jobs). Going over HTTP to your own process adds auth, serialization, and latency for no benefit.

Use a feature test to pin the contract. A single test that boots the app with the API enabled, hits one endpoint with a token, and asserts the shape (status, top-level keys) will catch breaking changes on the next 0.1.x bump far faster than reading changelogs.

Gotchas and Tips

• 0.1.x means the API surface is not stable. This release is dominated by dev-dependency bumps (phpstan, larastan, pint) — good hygiene, but it tells you the maintainers' energy went into CI and the new API rather than into a stability guarantee. Pin "storviaio/vantage": "0.1.25" in composer.json (or use a ~0.1.25 constraint) rather than a floating ^0.1, and re-test on each bump.
• "Optional" usually means "off by default" — verify, don't assume. Confirm the default in config/vantage.php after publishing. Route files loaded unconditionally in a service provider bypass the flag entirely; php artisan route:list is the quickest way to prove the flag actually works in both states.
• Bearer auth needs the same hardening as any token endpoint. If you enable the API on a public-facing host, put it behind rate limiting and HTTPS, and check whether the package ships a throttle middleware group. If it doesn't, wrap the routes yourself at the proxy or via a Route::middleware('throttle:...') override.
• Config cache will bite you. After changing the enable flag or the token guard, run php artisan config:clear (or re-run config:cache in deploys). A stale cached config is the classic reason "I enabled it but the routes still 404".
• Auth failures are ambiguous by design. A 401 can mean "API disabled", "missing header", or "bad token". When debugging, first confirm the route exists (route:list), then confirm the header is actually on the wire (Http::withToken() vs. a manually built Authorization header — watch for double Bearer prefixes), then the token value.
• Extension points worth knowing before you need them: the published config for defaults and overrides, the package's service provider for binding a custom implementation (common pattern: publish a config key that names a class), and the package's migrations if you need to add columns for tenancy or retention. Prefer these over editing vendor files — a composer update will erase anything you patched.
• Don't let the dev-dependency bumps distract your review. phpstan-deprecation-rules, phpstan-phpunit, phpstan, pint, and larastan updates are maintainer-side only; they have no runtime impact on your app. The one behavioural item in v0.1.25 is the REST/JSON API PR (#62) — review that, and treat the rest as noise.