Actuator Doctrine Bundle Laravel Package

Getting Started

This bundle plugs a Doctrine DBAL health indicator into the Actuator bundle, so your /actuator/health endpoint reports whether Doctrine can actually reach the database — not just whether the kernel boots. As of v1.1.0 it supports Symfony 7.0 alongside the existing 5.x/6.x range.

Install and register:

composer require symsensor/actuator-doctrine-bundle

If you're on Symfony Flex, the bundle should be auto-discovered. Otherwise register it manually:

// config/bundles.php
return [
    // ...
    SymSensor\ActuatorDoctrineBundle\ActuatorDoctrineBundle::class => ['all' => true],
];

Make sure symsensor/actuator-bundle is already installed and its routes are imported — the Doctrine bundle adds an indicator, it does not create an endpoint on its own. On Symfony 7 you'll need PHP 8.2+ and a symsensor/actuator-bundle version that is itself Symfony 7 compatible; Composer will resolve the constraint for you, but check composer why-not symsensor/actuator-bundle if resolution stalls.

Where to look first:

1. config/routes.yaml — confirm the actuator routes are loaded (typically /_actuator or /actuator).
2. The bundle's DependencyInjection/ directory — check the extension class to see which service IDs it wires and whether there are configuration options (e.g. connection name, timeout).
3. The indicator service itself (something like DoctrineHealthIndicator) — read it to see exactly what query it runs and what it returns.

First use case — quick smoke test:

curl -s http://localhost:8000/actuator/health | jq

You should see the Doctrine entry flipped from UP to DOWN when you stop your database container. That's the whole point of the bundle: turn a "silent" DB outage into a failing health check that your orchestrator (Kubernetes liveness/readiness, load balancer, uptime monitor) can act on.

Implementation Patterns

Wire it into container orchestration probes. The most common pattern is exposing a separate liveness vs. readiness probe. Use a shallow actuator endpoint for liveness (process is up) and a deep one including Doctrine for readiness (can serve traffic). This avoids restart-loops when the DB has a transient hiccup:

# kubernetes deployment snippet
readinessProbe:
  httpGet:
    path: /actuator/health
    port: 8080
  initialDelaySeconds: 10
  periodSeconds: 15
livenessProbe:
  httpGet:
    path: /actuator/health/liveness
    port: 8080

Aggregate multiple Doctrine connections. If you have read replicas or multi-tenant connections, rely on the bundle's indicator being registered per-connection. Iterate over doctrine.connections in your own config if the bundle only wires the default — or write a small decorator that loops the connections and reports each:

final class MultiConnectionDoctrineIndicator implements HealthIndicatorInterface
{
    public function __construct(private ManagerRegistry $registry) {}

    public function check(): Health
    {
        $details = [];
        foreach ($this->registry->getConnections() as $name => $conn) {
            try {
                $conn->executeQuery('SELECT 1');
                $details[$name] = 'UP';
            } catch (\Throwable $e) {
                $details[$name] = 'DOWN: ' . $e->getMessage();
            }
        }
        // return Health::up(...) / Health::down(...) based on $details
    }
}

Gate it behind the actuator's info/metrics subsystem. Pair the health indicator with an actuator metric or info contributor that exposes the Doctrine DB name/version. Useful for ops dashboards — but keep secrets out by hashing or truncating.

CI integration. Add a health-check step after migrate in your deployment pipeline:

until curl -sf http://localhost/actuator/health | grep -q '"status":"UP"'; do
  sleep 2
done

This catches "container started but migrations failed" before your smoke tests run.

Compose with the base indicator. The Doctrine bundle's indicator runs whatever query the bundle author chose (SELECT 1 most likely). If you need a different probe (e.g. SHOW SLAVE STATUS), extend or replace the service via a compiler pass rather than patching vendor code.

Gotchas and Tips

Bundle registration is not free on older Symfony. If composer require did not add the bundle to config/bundles.php, silently no indicator appears — the route will 200 but never touch Doctrine. First debugging step: bin/console debug:container --tag=actuator.health_indicator (tag name may differ — inspect the bundle's services.xml/services.yaml).

Symfony 7 compatibility is new — verify it, don't assume it. v1.1.0's only stated change is "Implement Symfony7.0 compatibility." That likely means an updated composer.json constraint plus any return-type/attribute fixes, but the rest of the bundle was written against 5.x/6.x APIs. After upgrading, re-run your smoke test on a Symfony 7 app specifically: container compilation, service tags, and the health endpoint all still behave. If the base Actuator bundle isn't also Symfony 7-ready, you may end up in an inconsistent state — pin both together.

Health checks hit the DB on every probe. Kubernetes probes every 15s × N pods = real load. Keep the probe query trivial and make sure your doctrine.dbal.server_version is set correctly so DBAL doesn't issue a version-detection round-trip on each request.

Timeouts vs. probe timeouts. A hung DB connection means the health endpoint itself hangs. Set doctrine.dbal.connect_timeout (and options for PDO::ATTR_TIMEOUT if applicable) to something smaller than your probe timeoutSeconds, otherwise Kubernetes will kill the probe with a generic failure and you lose the DOWN signal.

Exceptions may or may not be caught. Some indicator implementations re-throw ConnectionException, hoping the framework converts it. Verify with bin/console debug:container --show-private and read the class. Test explicitly by stopping the DB. If it 500s instead of returning DOWN, wrap or decorate the indicator.

Cache warmup runs health checks in some setups. Avoid making DB connectivity a hard boot dependency — the indicator should be lazy (tagged service resolved on demand). If the bundle registers a non-lazy connection check via a kernel.request listener, disable it or gate it on the actuator route only.

Maintenance profile is still small. v1.1.0 keeps the package alive and current with Symfony 7, which is a meaningful signal, but it remains a zero-star, single-purpose bundle with a narrow release cadence — treat it as a thin convenience layer, not a strategic dependency. Pin the version in composer.json and be prepared to fork. The logic is almost certainly ~50 lines; if you're already nervous about the dependency, writing a 20-line HealthIndicatorInterface implementation directly in your app remains a fine trade-off. (If you do fork, you now have a concrete upstream to diff against on the 7.x line.)

Extension points. Look for a compiler pass or a public service alias for the indicator. Replacing the indicator (rather than disabling and re-registering) is the cleanest override:

# config/services.yaml
services:
  SymSensor\ActuatorDoctrineBundle\Health\DoctrineIndicator:
    class: App\Health\CustomDoctrineIndicator
    arguments: ['@doctrine.dbal.default_connection']

Don't rely on it for migration awareness. A SELECT 1 succeeds against a schema that's missing your new columns. Pair the health check with a migration-status assertion (e.g. doctrine:migrations:up-to-date) in your deploy, not in the liveness probe.

Debugging checklist when the indicator won't appear:

1. bin/console debug:router | grep actuator — route exists?
2. bin/console debug:container | grep -i doctrine.*health — service registered?
3. bin/console debug:event-dispatcher actuator.health — indicator collected?
4. Check config/packages/actuator.yaml for any health: allow-list that excludes the Doctrine indicator (the base bundle often supports an explicit indicators list).
5. composer show symsensor/actuator-doctrine-bundle symsensor/actuator-bundle — confirm you actually resolved to v1.1.0 and a mutually compatible Actuator bundle version (especially post-Symfony 7 upgrade).