How would you implement API versioning in a PHP application?

API versioning in PHP can be effectively implemented using URL, header, or query parameter approaches, with URL and header versioning being most recommended. 1. For URL-based versioning, include the version in the route (e.g., /v1/users) and organize controllers in versioned directories, routing requests via framework route groups (e.g., Laravel’s prefix). 2. For header-based versioning, use the Accept or a custom header (e.g., X-API-Version: 1), then read the header in middleware to route requests accordingly. 3. Query parameter versioning involves appending version=1 to URLs, extracting it from $_GET, and routing dynamically. Best practices include avoiding breaking changes, deprecating fields instead, documenting versions with OpenAPI, supporting fallbacks to the latest stable version, and returning deprecation warnings in headers. Structure code using namespaces (e.g., App\Api\V1\Controllers) for separation, and consider using version-specific transformers over duplicated logic. Consistency and forward planning are key to maintaining scalable and maintainable APIs.

API versioning in a PHP application helps maintain backward compatibility and allows gradual updates without breaking existing clients. Here’s how you can implement it effectively:

1. URL-Based Versioning

One of the most common and straightforward approaches is including the version in the URL.

Example:

https://api.example.com/v1/users
https://api.example.com/v2/users

Implementation:

• Organize your code by version in directories:

  

  /api/v1/UsersController.php
  /api/v2/UsersController.php

• Route requests based on the URL segment using a router (e.g., Slim, Laravel, or custom dispatcher).

• In a framework like Laravel:

  Route::prefix('v1')->group(function () {
      Route::get('/users', [V1\UsersController::class, 'index']);
  });
  
  Route::prefix('v2')->group(function () {
      Route::get('/users', [V2\UsersController::class, 'index']);
  });

✅ Simple and intuitive
❌ Can clutter URLs and may complicate caching or SEO (less relevant for APIs)

2. Header-Based Versioning

Pass the API version in a request header, such as Accept or a custom header.

Example:

Accept: application/vnd.example.v1 json
OR
X-API-Version: 1

Implementation:

• Read the header in middleware or bootstrap:

  $version = $_SERVER['HTTP_ACCEPT'] ?? '';
  if (strpos($version, 'v1') !== false) {
      // Route to v1
  } elseif (strpos($version, 'v2') !== false) {
      // Route to v2
  }

• Use content negotiation to decide controller or serializer.

✅ Keeps URLs clean
❌ Less visible and harder to test/debug directly in browser

3. Query Parameter Versioning

Include version as a query parameter.

Example:

https://api.example.com/users?version=1
https://api.example.com/users?api_version=2

Implementation:

• Extract version from $_GET:

  $version = $_GET['version'] ?? '1';

• Use a factory or router to instantiate the correct controller.

✅ Easy to test and implement
❌ Not RESTful; version becomes part of state, not resource

4. Best Practices & Recommendations

• Use URL or Header versioning — these are most widely accepted.
• Avoid breaking changes in the same version. Deprecate fields instead.
• Document versions clearly — use OpenAPI/Swagger to track changes.
• Support version fallbacks — default to latest stable if no version is specified.
• Deprecation strategy — return Warning headers or sunset dates.

For example:

Warning: 299 - "API version v1 is deprecated. Use v2 by 2025-01-01."

5. Structure Your Code for Scalability

Use namespaces and service layers:

namespace App\Api\V1\Controllers;
class UserController { ... }

namespace App\Api\V2\Controllers;
class UserController { ... }

This keeps logic separated and avoids conflicts.

You can also use a version-agnostic core with version-specific transformers or serializers to format output differently per version.

Basically, pick a method that fits your team and clients. URL-based is often easiest for public APIs, while header-based is cleaner for machine-to-machine communication. The key is consistency and planning for evolution.

The above is the detailed content of How would you implement API versioning in a PHP application?. For more information, please follow other related articles on the PHP Chinese website!