Getting Started

javer/influxdb-odm-bundle is thin Symfony glue around an InfluxDB ODM: it registers connection and document-manager services from YAML and lets you map PHP classes to measurements. It is not Doctrine: there are no migrations, no relational associations, and no transactional unit of work. Think “annotated DTOs plus a small persistence API.”

As of v1.4.0, the bundle requires PHP 8.1+ and adds Symfony 7 support. It also no longer requires doctrine/annotations; use PHP attributes for mapping.

Minimal path:

Install and inspect constraints before committing. With limited adoption and a small release history, check PHP/Symfony compatibility first. For Symfony 7, pin v1.4.0+.

composer require javer/influxdb-odm-bundle:^1.4
composer show javer/influxdb-odm-bundle
php -v

// config/bundles.php
Javer\InfluxDBBundle\JaverInfluxDBBundle::class => ['all' => true],

Configure one connection and one document manager. The exact root key and option names are defined in DependencyInjection/Configuration.php; the shape is typically:

# config/packages/javer_influx_db.yaml
javer_influx_db:
    connections:
        default:
            host: '%env(INFLUXDB_HOST)%'
            port: 8086
            database: '%env(INFLUXDB_DATABASE)%'
            username: '%env(INFLUXDB_USER)%'
            password: '%env(INFLUXDB_PASSWORD)%'
            # timeout, retention_policy, precision where supported
    document_managers:
        default:
            connection: default
            mappings:
                App:
                    type: attribute
                    dir: '%kernel.project_dir%/src/Document'
                    prefix: 'App\Document'

Define your first measurement class. Mapping attribute names are owned by the underlying ODM (vendor/javer/influxdb-odm), so confirm exact namespaces there. v1.4.0 no longer pulls in doctrine/annotations; use attributes.

namespace App\Document;

use Javer\InfluxDB\ODM\Mapping\Annotation as ODM;

#[ODM\Measurement(name: 'api_request')]
class ApiRequest
{
    #[ODM\Tag]
    private string $route;

    #[ODM\Tag]
    private string $method;

    #[ODM\Field]
    private int $status;

    #[ODM\Field]
    private float $durationMs;

    #[ODM\Timestamp]
    private \DateTimeImmutable $occurredAt;

    // constructor and accessors
}

Write through the document manager:

use Javer\InfluxDB\ODM\DocumentManagerInterface;

final class RequestMetrics
{
    public function __construct(private DocumentManagerInterface $dm) {}

    public function record(ApiRequest $request): void
    {
        $this->dm->persist($request);
        $this->dm->flush();
    }
}

If autowiring fails, check the bundle service definitions and add an alias explicitly.

Read through a repository for simple lookups, and through the underlying connection/client for real InfluxQL:

$repo = $this->dm->getRepository(ApiRequest::class);
$rows = $repo->findBy(['route' => '/api/orders'], ['occurredAt' => 'DESC'], 100);

Where to look first

vendor/javer/influxdb-odm-bundle/DependencyInjection/Configuration.php — source of truth for config keys.
The bundle’s Resources/config/services.* — service ids and autowiring aliases.
vendor/javer/influxdb-odm/ — mapping classes, repository API, query builder if any.
Bundle tests, if present, for working examples.
The GitHub README and issues, but treat them as secondary to the code.

First use case: record HTTP request duration and status from a kernel.terminate listener or middleware, then query the last 24 hours for a dashboard. This exercises connection config, attribute mapping, batching, timestamp handling, and querying in one pass.

Implementation Patterns

Model one class per measurement. Keep measurement classes small and explicit. Tags are dimensions you filter or group by; fields are measured values; the timestamp should always be explicit. Encode units in field names (duration_ms, bytes_in) because InfluxDB stores no unit metadata.

Write in batches, flush deliberately. For high-volume writes, persist many documents and call flush() once per request or per batch rather than per point. Verify the ODM’s flush semantics first — if persist() writes immediately, the API behaves differently than Doctrine. For request-path metrics, flush after the response via kernel.terminate or a Messenger handler so InfluxDB latency never blocks users.

Make writes idempotent. InfluxDB overwrites points with the same measurement, tag set, and timestamp. For retries and backfills, set a deterministic timestamp and the same tags so replays do not duplicate data.

Use the repository for simple reads, raw InfluxQL for analytics. Repositories are convenient for “latest N by tag,” but time-series work usually means GROUP BY time(), downsampling, and aggregation. Get the connection/client service and issue InfluxQL directly; aggregate inside InfluxDB rather than pulling raw points into PHP.

Separate connections by retention policy. Use multiple document managers for different data classes — e.g. short-retention operational metrics and long-retention business KPIs. Inject the specific manager service rather than relying on the default alias.

Use attributes, not annotations. v1.4.0 removes the doctrine/annotations requirement. New and migrated code should use PHP attributes. If you still have annotation-based documents, either add doctrine/annotations explicitly or migrate them before depending on v1.4.0.

Integration points that pay off

Messenger handler for RecordApiRequest messages, with retries and failure transport.
Console command for backfills and rollups, with explicit timestamps and precision.
Health-check command running SHOW DATABASES or a trivial query.
Kernel listener for write-behind metrics; avoid synchronous writes in hot paths.
A small wrapper service around the document manager to centralize error handling and fallback logging.

Testing pattern. Run InfluxDB 1.x in Docker, point when@test at a separate database, and drop or use unique measurements in setUp(). Assert through direct InfluxQL, not only through the repository, so you verify what was actually written. On Symfony 7, test against v1.4.0+ so you are exercising the supported combination.

Error handling. Wrap flush() in try/catch and log failures. Metrics loss is often acceptable; silent loss is not. Because there is no rollback, a failed batch may be partially written — retries must be safe.

Gotchas and Tips

v1.4.0 changes your compatibility floor. It requires PHP 8.1 and supports Symfony 7. If you are on PHP 8.0 or an older Symfony, stay on the previous bundle version or upgrade first. Pin ^1.4 when using Symfony 7.
doctrine/annotations is no longer pulled in. This is good for modern attribute mapping, but it can break legacy annotation-based documents. Migrate to attributes or add doctrine/annotations yourself if you still need annotation metadata.
InfluxDB version compatibility is still the first thing to verify. This ODM most likely targets the InfluxDB 1.x HTTP API with database/retention-policy semantics. InfluxDB 2.x/3.x use org/bucket/token and a different client. If you are on v2+, this bundle may not be usable without a compatibility layer; the official influxdata/influxdb-client-php is the safer path.
Treat it as low-support software. Limited adoption means little community safety net. Pin an exact version, read the source, and be prepared to fork. Do not put it on a critical path without a fallback write path.
Configuration.php beats the README. Config key names often drift (document_manager vs document_managers, mapping array shape, connection options). Read the configuration tree before debugging YAML.
Autowiring may not work out of the box. If DocumentManagerInterface cannot be injected, define an alias in services.yaml pointing at the bundle’s default manager service.
Clear the cache after mapping changes. Attribute metadata is cached; stale mappings produce confusing “class is not a valid document” errors. Run bin/console cache:clear in dev and warm up in prod.
No transactions, no rollback. A network error during flush() can leave a partial batch. Design for at-least-once delivery and idempotent points.
Timestamp precision bites. InfluxDB stores nanoseconds; a precision setting of seconds vs milliseconds can make data look off by 1000x. Use DateTimeImmutable in UTC and be consistent per measurement.
Tag cardinality is the classic production killer. Never tag request IDs, user IDs, raw URLs with IDs, exception messages, or anything unbounded. High cardinality causes memory exhaustion and slow queries. Put those in fields.
Field types are fixed per shard. The first write determines a field’s type for that shard. Writing a string where a float was written causes rejected or dropped points. Keep types stable and cast explicitly.
Measurement and tag names need care. Avoid spaces, quotes, and backslashes; prefer snake_case. InfluxQL requires quoting for special characters, and the ODM may not escape for you.
Retention is not automatic. The default policy may retain data forever. Set a retention policy in config or InfluxDB itself, and downsample with continuous queries if volume grows.
No schema migrations. Renaming a measurement or field creates new data; old data does not follow. Plan naming up front. Deletes are expensive and limited — design append-only.
Debug at the HTTP layer. Use curl -G 'http://localhost:8086/query?db=...' --data-urlencode "q=SHOW MEASUREMENTS", SHOW TAG KEYS, SHOW FIELD KEYS, and SELECT * LIMIT 5. Check HTTP status codes; write errors may be swallowed by the ODM.
Batch size limits. Very large POST bodies can be rejected by the server or proxy. Chunk writes.
No profiler integration. There is no data collector; instrument your wrapper service with timers and failure counters if you need visibility.
Extension points are limited. Custom repositories may be supported via mapping config; otherwise wrap the manager in your own service and keep ODM-specific code behind that boundary so you can replace it later.

Influxdb Odm Bundle Laravel Package

Getting Started

Implementation Patterns

Gotchas and Tips