- How do I install reindert-vetter/api-version-control in a Laravel app?
- Install it with composer require reindert-vetter/api-version-control, then publish the package configuration and register its middleware alias in your HTTP kernel or bootstrap file. The package is a thin middleware plus a static version resolver, so setup is measured in minutes rather than in restructuring your routing. Because release 2.3.3 ships an empty changelog, pin a version and review the diff before rolling it into production.
- How does the package determine the API version of an incoming request?
- It reads the version from the Accept header using a vendor media type such as application/vnd.{vendor}.v2+json, or from a dedicated Accept-Version header. A regex-driven resolver extracts the version token and the request is then dispatched to the matching version-specific controller or route. Headers are untrusted input, so validate how malformed or spoofed Accept strings are handled in your own tests.
- Does this package support URI or path-based versioning like /v2/users?
- Not as its primary model. The package is built around header and content-negotiation versioning, and the technical evaluation notes it adds little value if your architecture uses path-based /v2/... routes. If you want URI versioning you are usually better off with plain Laravel route groups and prefixes. Choose this package only when header negotiation is genuinely part of your API contract.
- Which Laravel and PHP versions does version 2.3.3 support?
- Check the composer.json of the actual 2.3.3 artifact rather than trusting the changelog, which is empty apart from a compare link. The package is single-maintainer and low cadence, so Laravel major-version support can lag behind the framework. Confirm your Laravel and PHP versions against the declared constraints and run your suite in CI before adopting.
- How do I register the middleware so requests reach the right version?
- Add the package middleware alias to your HTTP kernel or, on Laravel 11 and later, to the withMiddleware configuration in bootstrap/app.php. Then attach it to the api middleware group or to specific route groups where version negotiation applies. It composes with existing Sanctum, rate limiting, and API Resource stacks because it runs as ordinary route middleware before controller resolution.
- What version is used when a client sends no version header?
- Resolution typically falls back to a default version, which is convenient but makes mis-versioned traffic invisible. Decide explicitly what that default should be, and set it equal to your current behaviour so no existing client breaks on day one. Log or monitor requests that hit the fallback path so you can see which consumers are not sending a version.
- Can I keep separate controllers and routes per API version?
- Yes, that is the package's core idea: version-specific controllers and routes, with the middleware dispatching each request to the matching set. This keeps v1 logic untouched while v2 evolves, instead of filling controllers with conditional version checks. It does not provide version-to-route mapping or lifecycle primitives, so you still organise route files and namespaces yourself.
- How should I test versioned API endpoints in Laravel?
- Write feature tests that send the Accept or Accept-Version header and assert the response matches the expected version's contract. Cover the fallback case where the header is missing or malformed, since that path is the most likely to hide bugs. Because parsing is regex-based, include unusual and spoofed Accept strings as negative cases in your suite.
- Do I need Vary: Accept when using header version negotiation behind a CDN?
- Yes. If any HTTP cache, reverse proxy, or CDN sits in front of your API, responses that differ by Accept header must declare Vary: Accept. Otherwise a cached v2 response can be served to a client requesting v1, which is a subtle and hard-to-debug production incident. This is a property of content negotiation generally, not something the package handles for you.
- Is reindert-vetter/api-version-control actively maintained, and what are the alternatives?
- It is a small, single-maintainer package with a low commit cadence; that is acceptable at this size but means Laravel compatibility releases may lag. Release 2.3.3 has an empty changelog body, so treat it as a low-information patch. Alternatives include plain URI versioning with route prefixes, or Laravel's own route grouping and API Resources, which need no extra dependency. Keep a fallback owner in mind in case upstream support stalls.