Base Api Bundle Laravel Package

Getting Started

Before you write a line of code, understand what you're adopting. This bundle has 0 stars and 0 dependents, which means you are almost certainly the first production consumer. Treat it as first-party-but-unsupported code that you now own, not as a battle-tested dependency.

Minimal path:

1. composer require tpn/base-api-bundle (pin to an exact version — "tpn/base-api-bundle": "1.2.3" — no caret, because there is no community to catch a bad patch release).
2. Register the bundle in config/bundles.php:

   TPN\BaseApiBundle\TPNBaseApiBundle::class => ['all' => true],
   

3. Read DependencyInjection/Configuration.php first. It is the only authoritative document of what this bundle actually exposes. A base-API bundle typically defines a tpn_base_api: root with keys for serializer groups, error format, pagination, and versioning. The README (if any) will be thinner than this file.
4. Next, read Resources/config/services.yaml (and routing.yaml) to see what's public and what's tagged. Look for compiler passes — they change behavior invisibly.
5. Run bin/console debug:config tpn_base_api (or whatever the alias is) to dump the resolved configuration tree. This is your fastest feedback loop for "why is my setting ignored."
6. Run bin/console debug:container --show-private | grep -i tpn to enumerate what you can decorate.

First use case: wire it into a single non-critical endpoint. Base-API bundles usually give you an exception listener + serializer that turn exceptions into a consistent JSON error envelope. Point one controller at that path, assert the response shape with a test, and confirm it matches what your frontend already expects. Do not migrate existing endpoints until that contract is locked.

If the bundle ships abstract controllers or a ApiController base, read them end to end before extending. With no downstream users, the inheritance surface hasn't been stress-tested and you may find it's designed around a single internal use case.

Implementation Patterns

Extend, don't fight. Base bundles are usually meant to be extended (abstract controllers, base exceptions, a base entity normalizer). Subclass the provided base classes and add behavior; decorating a bundle's internal service works but couples you to private class names that can vanish in a patch release.

Configuration as the seam. Prefer overriding through config/packages/tpn_base_api.yaml over editing vendor code. If a setting you need doesn't exist, that's the point where you fork or vendor the bundle — with 0 dependents, upstreaming via PR is unlikely to be reviewed. Use Composer's repositories: { type: vcs } + a dev- constraint so your fork is explicit in composer.json.

Error contract first. The most common pattern: throw a domain exception, let the bundle's listener format it. Standardize on one exception base and one error payload shape early. Write a single functional test (KernelBrowser, assert JSON) that pins status, code/type, message, and errors[]. That test is your regression net when you later upgrade.

Serialization strategy. If the bundle supplies serializer groups or a normalizer, define your DTOs/entities against those group names rather than raw array shaping. Keep a serializer config in your own package config so you're not surprised when the bundle changes its default groups.

Versioning and routing. If the bundle provides versioned route loaders, isolate each API version in its own controller namespace and its own test suite. This makes a bundle upgrade a per-version decision rather than a global one.

Testing integration. Use KernelTestCase/WebTestCase against a small test kernel that registers the bundle. Because external coverage is zero, your tests are the only documentation. Assert on the behavior you depend on, not on internal implementation.

Isolate at the boundary. Wrap the bundle's services behind one or two of your own thin services (an ApiErrorFormatter interface, a ResponseFactory) so that replacing the bundle later is a one-file change rather than a codebase-wide search.

Gotchas and Tips

• Zero dependents is the headline risk. No one else has run this in production. Expect undocumented edge cases around content negotiation, null handling, and nested exception chains. Budget time for reading vendor source; you will read it.
• Bundle ordering. Symfony bundles are registered in the order PHP returns from config/bundles.php. If this bundle overrides serializer, validator, or framework config, it needs to load after the framework bundles. Misordering silently loses config.
• Config keys are not validated the way you hope. A typo in a yaml key is often ignored rather than rejected. Confirm with debug:config after every change; don't assume.
• Service decoration order. If you decorate a bundle service, be aware the bundle may itself decorate a framework service. Use debug:container --deprecations and debug:autowiring to check what your decoration is actually wrapping.
• Cache clearing is mandatory after touching bundle config or service definitions in dev — the container is compiled, and stale container state produces "class not found" errors that look unrelated.
• dev/prod divergence. Base bundles frequently branch on %kernel.debug% (verbose errors, stack traces). Test error paths in prod — that's where the response shape often differs from what you asserted in tests.
• Composer constraints. Check the symfony/* constraints the bundle declares; a ^5.4 constraint on a Symfony 6.4 app will make your resolution fragile. Lock versions with composer.lock committed and review the bundle's diff on every composer update.
• Escape hatch. Keep a written note of which classes you extend vs. decorate. If you extend five classes and decorate two services, the next release requires reading a diff for all seven. That list is your upgrade checklist.
• Debugging: enable framework: { profiler: ... } in dev and inspect the Exception/Serializer panels; the bundle's listener will show up as a decorated framework service, which is often the fastest way to see the format it produces.
• Before adopting in a new area, ask whether you need it at all. If it only contributes an exception listener and a serializer config, replicating that in ~60 lines of your own framework config may be cheaper than owning an unmaintained bundle.