Docbundle Laravel Package

Getting Started

Install and register

composer require ops-talent/docbundle

Because this package modifies Nelmio’s doc extractor, you almost always need Nelmio present in the same app:

composer require nelmio/api-doc-bundle

Register the bundle in config/bundles.php (order matters — after Nelmio if it decorates services):

return [
    Nelmio\ApiDocBundle\NelmioApiDocBundle::class => ['all' => true],
    OpsTalent\DocBundle\OpsTalentDocBundle::class => ['all' => true],
];

Where to look first

1. Resources/config/ (or config/ in newer layouts) — the service wiring tells you exactly which Nelmio service is being replaced or decorated.
2. The DependencyInjection/ extension class — reveals configurable options and compiler passes.
3. The Extractor/ namespace — the actual modified extraction logic; diff it against vendor/nelmio/api-doc-bundle/Extractor/ to see what was changed. That diff is the real documentation for this package.

First use case

The typical intent of a "doc extractor modification" fork is to change how annotations/attributes are parsed into swagger documentation — for example, custom handling of a route annotation, a different grouping strategy, or additional metadata on generated docs. Once registered, running:

bin/console nelmio:apidoc:dump --format=json

should produce output that reflects the modified extractor rather than vanilla Nelmio. If output is identical to vanilla Nelmio, the bundle is not actually taking effect — check service wiring before going further.

Implementation Patterns

Decorate, don’t fork at the call site

If the bundle’s extractor is registered as a service, prefer Symfony service decoration over rewriting controllers:

# config/services.yaml
services:
    App\ApiDoc\CustomExtractor:
        decorates: nelmio_api_doc.extractor.api_doc_extractor
        arguments: ['@.inner']

This keeps the modification contained and lets you layer your own tweaks on top of the bundle’s behavior without touching vendor code.

Extend annotations/attributes centrally

Where the fork adds fields or changes how metadata is collected, keep custom annotation/attribute classes in one namespace and reference them consistently:

use OpsTalent\DocBundle\Annotation\CustomField;

/**
 * @CustomField(...)
 */
public function listAction(): Response { ... }

Consistency matters — mixing vanilla Nelmio annotations with this bundle’s extensions in the same codebase rapidly becomes unmaintainable and hard to debug.

Generate docs in CI

Wire doc generation into CI so drift is caught:

bin/console nelmio:apidoc:dump --format=html > public/api.html

Diff the generated file against a checked-in copy. Since the extractor is the whole point of this fork, a CI check that asserts output shape is your best regression guard.

Integrate with your API test suite

Have your functional tests assert that generated docs contain the routes your controllers actually expose. This catches the most common failure of custom extractors: silently dropping or duplicating endpoints when routing changes.

Gotchas and Tips

Version lock is the primary risk

This is a one-star fork with no dependents and no recent activity. Pin both this bundle and nelmio/api-doc-bundle to exact versions in composer.json, and vendor the lockfile. Any composer update that bumps Nelmio can break the extractor silently because service IDs and interfaces inside Nelmio have changed across major releases over the years.

Check the diff, not the README

Given the tiny footprint, the README (if present) is unlikely to keep up with Symfony/Nelmio API churn. The authoritative description of behavior is git diff against the upstream Nelmio source at the version this fork targeted. Read that diff before trusting the bundle in production.

Service wiring can silently not apply

A frequent symptom: docs generate fine, but they look exactly like stock Nelmio. That means the bundle’s services never overrode Nelmio’s. Verify with:

bin/console debug:container nelmio_api_doc.extractor.api_doc_extractor -vvv

You should see your bundle’s class, not Nelmio’s, or a decorator wrapping it.

Cache is a common source of confusion

Symfony caches compiled container and, in dev, sometimes routing/annotation metadata. If extractor changes appear not to take effect:

bin/console cache:clear
rm -rf var/cache/*

Especially when toggling between Nelmio configs in dev.

Config quirks

Bundle extension aliases (ops_talent_doc, opstalent_doc, etc.) are easy to get wrong — check the extension class’s getAlias(). Misnamed config keys are silently ignored in many Symfony setups, so validation via bin/console config:dump-reference <alias> is worth a minute.

Extension points to prefer

If you find yourself needing to change behavior already customized by this bundle, wrap it again via decoration rather than editing vendor files. Stack of two or three decorators is manageable; three parallel forks of Nelmio is not.

Debugging extraction issues

• nelmio:apidoc:dump with -vvv shows extraction errors.
• Log handler for nelmio channel captures annotation/attribute parsing warnings.
• Compare dump output between this bundle enabled vs. disabled — that diff isolates the fork’s contribution.

Abandonment contingency

Because there are no dependents and low maintenance activity, assume you may need to take ownership. Keep a small wrapper layer (decoration + tests) so that replacing the bundle with an equivalent in-house extractor later is a localized change rather than a project-wide rewrite.