Building RESTful APIs with PHP: Best Practices

Creating robust RESTful APIs in PHP requires careful planning and adherence to best practices. Here’s how to build professional-grade APIs.

Basic API Structure

// public/index.php
require __DIR__ . '/../vendor/autoload.php';

$request = Laminas\Diactoros\ServerRequestFactory::fromGlobals();
$router = new League\Route\Router;

$router->map('GET', '/api/products', [ProductController::class, 'index']);
$router->map('POST', '/api/products', [ProductController::class, 'create']);

$response = $router->dispatch($request);
(new Laminas\HttpHandlerRunner\Emitter\SapiEmitter)->emit($response);

RESTful Design Principles

• Use HTTP methods properly (GET, POST, PUT, PATCH, DELETE)
• Return appropriate HTTP status codes
• Version your API (e.g., /api/v1/products)
• Use plural nouns for resources (/products not /product)
• Support filtering, sorting, and pagination

Response Formatting

class ApiResponse {
    public static function success($data, int $code = 200) {
        return new JsonResponse([
            'success' => true,
            'data' => $data
        ], $code);
    }

    public static function error(string $message, int $code = 400) {
        return new JsonResponse([
            'success' => false,
            'error' => $message
        ], $code);
    }
}

Authentication

Common API authentication methods:

// JWT Authentication Middleware
class AuthMiddleware implements MiddlewareInterface {
    public function process(
        ServerRequestInterface $request, 
        RequestHandlerInterface $handler
    ): ResponseInterface {
        if (!$request->hasHeader('Authorization')) {
            return ApiResponse::error('Unauthorized', 401);
        }
        
        // Validate JWT token
        return $handler->handle($request);
    }
}

Documentation

Always document your API with:

• Endpoint descriptions
• Request/response examples
• Authentication requirements
• Error responses

Tools like OpenAPI/Swagger can automate documentation generation.