Hypervel Influxdb Laravel Package

Getting Started

• Install with composer require ipsocode/hypervel-influxdb. As of v0.2.0 this pulls hypervel/components 0.4.x-dev, so your app is on a dev-stability dependency chain — pin it and commit composer.lock before doing anything else.
• The package tracks Hypervel, not stock Laravel. Confirm your app's hypervel/components constraint matches 0.4.x-dev; if your app is on a tagged release you will need to relax or align constraints, and that decision effectively fixes your PHP version too.
• Start in the repo's README and composer.json, then read the package's config file and service provider — that's where connection names, env keys, and container bindings are defined. Publish the config (vendor:publish with the package's tag) rather than editing vendor files.
• Configure a single default connection via env (host, port, database/bucket, credentials) and leave the rest of the connections array empty until you need it.
• First use case: write one point from a queued job or scheduled command, then read it back with a query in the same command. Doing it outside the request cycle keeps slow Influx calls off your response path while you learn the API.
• The best executable documentation is the test suite: v0.2.0 added real InfluxDB integration tests, so those tests show you correct configuration, client construction, and assertion patterns against a live instance.

Implementation Patterns

• Resolve through the container, never new. Bind or resolve the manager/connection from the container (facade or constructor injection) so config swapping and test doubles work. Hard-coding a client instance is the fastest way to make the package untestable.
• Write from jobs, not controllers. InfluxDB writes are network calls with their own failure modes; push them to a queued listener or Artisan command with retries. Batch points for a single flush rather than one write per model event.
• Own your point shape. Decide measurement names, tag keys, and field types once and document them. Tags are indexed and fields are not — putting a high-cardinality value (user ID, request ID) in a tag is the classic way to blow up memory on the server.
• Use the FailureStore as a dead-letter queue. v0.2.0 introduced it as the place failed writes land. Wire a retry command or scheduled job that drains it, and put a depth check in your monitoring — an unwatched FailureStore is a silent data-loss bug.
• Pick one InfluxQL path and stay on it. v0.2.0 explicitly synchronised the "twin InfluxQL stacks." If your code mixes raw query strings with a builder, migrate fully to whichever the docs designate as current; mixed usage is where behaviour diverges.
• Multi-connection like Laravel. If you have more than one InfluxDB (e.g. per-tenant or per-environment), model it as named connections in config and resolve by name, mirroring DB::connection('x') habits. This is the pattern the config already anticipates; don't invent your own registry.
• Test in two layers. Unit tests bind a fake/stub connection and assert on what would be written. Integration tests (the ones the package itself runs) hit a real InfluxDB container — copy their Docker setup into your CI rather than mocking the wire protocol.
• Integration tips: run Influx in CI as a service container, gate those tests behind a group (e.g. @group integration) so local phpunit stays fast, and seed a throwaway database per run.

Gotchas and Tips

• The 0.4.x-dev pin is the biggest risk. A dev constraint means no semver protection across the Hypervel boundary; a patch bump upstream can break this package. Budget for occasional firefighting and don't put this on a critical write path without a fallback.
• v0.2.0 is a breaking release. The InfluxQL synchronisation change means any raw query strings, builder chains, or assumptions about escaping/identifier quoting should be re-verified. Grep your codebase for the query layer and re-run your integration tests before upgrading.
• FailureStore is new and therefore thinly battle-tested. Treat its schema and retention as yours to own — decide how long failures live and when they're discarded, and don't assume it retries automatically.
• Time precision is the perennial footgun. InfluxDB defaults to nanosecond timestamps; a millisecond or second timestamp passed in silently lands your data in 1970 or the far future. Be explicit about the precision unit at the write boundary and assert on it in tests.
• Values come back loosely typed. PHPStan level 6 raised confidence inside the package, not at the InfluxDB response boundary — results arrive as strings/floats and aggregations may be null. Cast and handle null explicitly.
• Debugging failures: enable query/HTTP logging, and log the InfluxDB response body on non-2xx — the status code alone rarely tells you whether it was a bad query, wrong database, or auth problem. Check auth token vs username/password mode, since those are configured differently.
• Extension points to reach for before forking: the container bindings in the service provider (swap the client/connection), a custom FailureStore implementation, and config-level connection arrays. If you find yourself copying vendor code, you've probably missed a binding.
• Documentation lag: the v0.2.0 notes are heavy on internal "tech debt" and CI churn with little user-facing guidance. Read the tests and the config file as the source of truth, and treat the README as a sketch.