README

A lightweight PHP library for building REST APIs using an attribute-based routing system. Define endpoints, middleware, and handle HTTP requests with minimal boilerplate.

Features

• 🎯 Attribute-based routing - Define routes using PHP 8 attributes
• 🔧 Middleware system - CORS, file validation, caching, and custom middleware
• 🚀 Response caching - Built-in HTTP response caching with tag-based invalidation
• 📦 Multiple response types - JSON, HTML, redirects, and custom responses
• 🛣️ Dynamic routing - URL parameters and wildcard matching
• ✅ Type-safe - Leverages PHP 8+ type system

Requirements

• PHP 8.1 or higher
• Composer

Installation

composer require baukasten/webservice

Quick Start

1. Create a Controller

<?php

use Baukasten\Webservice\Controller\Controller;
use Baukasten\Webservice\Attribute\Endpoint\Get;
use Baukasten\Webservice\Attribute\Endpoint\Post;
use Baukasten\Webservice\Request;
use Baukasten\Webservice\Response\JsonResponse;
use Baukasten\Webservice\Response\Response;

class ApiController extends Controller
{
 public function __construct()
 {
 parent::__construct('api'); // All routes prefixed with 'api/'
 }

 #[Get("hello")]
 public function hello(Request $request): Response
 {
 return new JsonResponse(['message' => 'Hello World!']);
 }

 #[Get("users/{id}")]
 public function getUser(Request $request): Response
 {
 $id = $request->getUrlParams()['id'];
 return new JsonResponse(['user_id' => $id]);
 }

 #[Post("users")]
 public function createUser(Request $request): Response
 {
 $data = json_decode($request->getBody(), true);
 return new JsonResponse(['created' => $data], 201);
 }
}

2. Bootstrap Your Application

<?php
// index.php

require_once __DIR__ . '/vendor/autoload.php';

use Baukasten\Webservice\Router;

Router::handleRequest([
 ApiController::class,
 // Add more controllers here
]);

3. Test Your API

curl http://localhost/api/hello
# {"message":"Hello World!"}

curl http://localhost/api/users/123
# {"user_id":"123"}

Core Concepts

Controllers

Controllers group related endpoints and define a route prefix.

class UserController extends Controller
{
 public function __construct()
 {
 parent::__construct('users'); // Prefix: /users
 }

 // Optional: Pre-execution hook for auth, validation, etc.
 public function prepare(Request $request): ?Response
 {
 // Check authentication
 if (!$this->isAuthenticated($request)) {
 return new ErrorResponse('Unauthorized', 401);
 }
 return null; // Continue to endpoint
 }

 #[Get("")]
 public function list(Request $request): Response
 {
 return new JsonResponse($this->getAllUsers());
 }

 #[Get("{id}")]
 public function get(Request $request): Response
 {
 $id = $request->getUrlParams()['id'];
 return new JsonResponse($this->findUser($id));
 }
}

Endpoint Attributes

Define HTTP methods and paths with attributes:

#[Get("path")] // HTTP GET
#[Post("path")] // HTTP POST
#[Put("path")] // HTTP PUT
#[Delete("path")] // HTTP DELETE

Route Patterns

URL Parameters:

#[Get("users/{id}")] // Matches: /users/123
#[Get("posts/{postId}/comments/{id}")] // Matches: /posts/5/comments/10

Wildcards:

#[Get("blog/*")] // Matches: /blog/2024/post, /blog/article
#[Get("api/*/details")] // Matches: /api/foo/bar/details

Accessing Parameters:

#[Get("users/{id}")]
public function getUser(Request $request): Response
{
 $params = $request->getUrlParams();
 $id = $params['id'];
 // ...
}

Request Object

The Request object provides access to all request data:

public function handle(Request $request): Response
{
 // HTTP method
 $method = $request->getMethod(); // GET, POST, PUT, DELETE

 // URL path
 $path = $request->getPath(); // /api/users/123
 $segments = $request->getPathSegments(); // ['api', 'users', '123']

 // URL parameters (from route pattern)
 $urlParams = $request->getUrlParams(); // ['id' => '123']

 // Query parameters (?page=1&limit=10)
 $queryParams = $request->getQueryParams();
 $page = $queryParams['page'] ?? 1;

 // POST data
 $postParams = $request->getPostParams();

 // All parameters (query + POST)
 $allParams = $request->getAllParams();

 // Raw request body
 $body = $request->getBody();
 $data = json_decode($body, true);

 // HTTP headers
 $headers = $request->getHeaders();
 $contentType = $headers['Content-Type'] ?? '';

 // Uploaded files
 $files = $request->getFiles();
 $file = $request->getFile('avatar');

 return new JsonResponse(['status' => 'ok']);
}

Response Types

JsonResponse:

return new JsonResponse(['key' => 'value'], 200);

HtmlResponse:

return new HtmlResponse('<h1>Hello</h1>', 200);

ErrorResponse:

return new ErrorResponse('Not Found', 404);
// Returns: {"error":"Not Found"}

Redirect:

return new Redirect('/login', 302);

Custom Response:

return new Response('Plain text', 200, [
 'Content-Type' => 'text/plain',
 'X-Custom-Header' => 'value'
]);

Middleware

Middleware are attributes that execute before your controller methods.

Built-in Middleware

CORS

Enable Cross-Origin Resource Sharing:

use Baukasten\Webservice\Attribute\Middleware\Cors;

#[Get("api/data")]
#[Cors(allowedOrigins: ['https://example.com'], allowedMethods: [HttpMethod::GET, HttpMethod::POST])]
public function getData(Request $request): Response
{
 return new JsonResponse(['data' => 'value']);
}

// Allow all origins
#[Cors(allowedOrigins: ['*'])]

MaxFileSize

Validate uploaded file sizes:

use Baukasten\Webservice\Attribute\Middleware\MaxFileSize;

#[Post("upload")]
#[MaxFileSize(fileKey: 'avatar', maxFileSize: 5242880)] // 5MB
public function upload(Request $request): Response
{
 $file = $request->getFile('avatar');
 // Process file
 return new JsonResponse(['uploaded' => true]);
}

Cacheable

Cache GET request responses:

use Baukasten\Webservice\Attribute\Middleware\Cacheable;

#[Get("users")]
#[Cacheable(ttl: 3600, tags: ['users'])]
public function listUsers(Request $request): Response
{
 return new JsonResponse($this->getAllUsers());
}

See the Response Caching section for details.

Custom Middleware

Create your own middleware by extending the Middleware class:

<?php

use Baukasten\Webservice\Attribute\Middleware\Middleware;
use Baukasten\Webservice\Request;
use Baukasten\Webservice\Response\Response;
use Baukasten\Webservice\Response\ErrorResponse;
use Attribute;

#[Attribute(Attribute::TARGET_METHOD)]
class RequireAuth extends Middleware
{
 public function __construct(
 private string $role = 'user'
 ) {}

 public function __invoke(Request $request): ?Response
 {
 $token = $request->getHeaders()['Authorization'] ?? '';

 if (!$this->validateToken($token)) {
 return new ErrorResponse('Unauthorized', 401);
 }

 if (!$this->hasRole($token, $this->role)) {
 return new ErrorResponse('Forbidden', 403);
 }

 return null; // Continue to controller
 }

 private function validateToken(string $token): bool
 {
 // Your validation logic
 return !empty($token);
 }

 private function hasRole(string $token, string $role): bool
 {
 // Your role checking logic
 return true;
 }
}

Usage:

#[Get("admin/users")]
#[RequireAuth(role: 'admin')]
public function adminUsers(Request $request): Response
{
 return new JsonResponse($this->getAllUsers());
}

Response Caching

The library includes powerful response caching with tag-based invalidation.

Setup

Initialize caching in your bootstrap file:

<?php
// index.php

use Baukasten\Webservice\ResponseCache;
use Baukasten\Cache\Buckets\FileBucket;

// Option 1: Auto-initialize with defaults (FileBucket in temp dir)
ResponseCache::init();

// Option 2: Custom file cache directory
ResponseCache::init([
 'cache_dir' => '/var/cache/my-app/responses'
]);

// Option 3: Redis cache
use Baukasten\Cache\Buckets\RedisBucket;

$redis = new RedisBucket(
 host: '127.0.0.1',
 port: 6379,
 password: null,
 database: 0,
 prefix: 'api:',
 defaultTtl: 3600
);

ResponseCache::init([
 'bucket' => $redis,
 'bucket_name' => 'api_cache'
]);

// Then handle requests
Router::handleRequest([MyController::class]);

Basic Caching

use Baukasten\Webservice\Attribute\Middleware\Cacheable;

#[Get("products")]
#[Cacheable(ttl: 3600)] // Cache for 1 hour
public function listProducts(Request $request): Response
{
 return new JsonResponse($this->getAllProducts());
}

Cacheable Parameters

#[Cacheable(
 ttl: 3600, // Time-to-live in seconds
 tags: ['products'], // Tags for invalidation
 ignoreQueryParams: false, // Include query params in cache key
 keyGenerator: null, // Custom key generator callable
 bucket: null, // Custom cache bucket name
 addHttpHeaders: true, // Add Cache-Control, ETag headers
 varyHeaders: [], // Headers to include in cache key
 cacheOnlySuccessful: true // Only cache 2xx responses
)]

Tag-Based Invalidation

Use tags to group and invalidate related cache entries:

class ProductController extends Controller
{
 #[Get("products")]
 #[Cacheable(ttl: 3600, tags: ['products'])]
 public function listProducts(Request $request): Response
 {
 return new JsonResponse($this->getAllProducts());
 }

 #[Get("products/{id}")]
 #[Cacheable(ttl: 1800, tags: ['products', 'product:{id}'])]
 public function getProduct(Request $request): Response
 {
 $id = $request->getUrlParams()['id'];
 return new JsonResponse($this->findProduct($id));
 }

 #[Post("products")]
 public function createProduct(Request $request): Response
 {
 $data = json_decode($request->getBody(), true);
 $product = $this->create($data);

 // Invalidate all product caches
 ResponseCache::invalidateByTag('products');

 return new JsonResponse($product, 201);
 }

 #[Put("products/{id}")]
 public function updateProduct(Request $request): Response
 {
 $id = $request->getUrlParams()['id'];
 $data = json_decode($request->getBody(), true);
 $product = $this->update($id, $data);

 // Invalidate specific product and list
 ResponseCache::invalidateByTag('product:' . $id);
 ResponseCache::invalidateByTag('products');

 return new JsonResponse($product);
 }
}

Tag placeholders are automatically resolved:

• tags: ['product:{id}'] → tags: ['product:123'] when id=123

Query Parameters

Include query params in cache key (default):

#[Cacheable(ttl: 3600)]
public function search(Request $request): Response
{
 // /api/search?q=foo and /api/search?q=bar cache separately
}

Ignore query params (useful for tracking params):

#[Cacheable(ttl: 3600, ignoreQueryParams: true)]
public function getStats(Request $request): Response
{
 // /api/stats?utm_source=email and /api/stats?utm_source=twitter
 // share the same cache
}

Vary by Headers

Cache different versions based on request headers:

#[Cacheable(
 ttl: 3600,
 varyHeaders: ['Accept-Language']
)]
public function getContent(Request $request): Response
{
 $lang = $request->getHeaders()['Accept-Language'] ?? 'en';
 // Returns different cached responses for different languages
}

Custom Cache Keys

Define your own cache key logic:

class CacheKeys
{
 public static function userSpecific(Request $request): string
 {
 $userId = $request->getHeaders()['X-User-ID'] ?? 'anonymous';
 $path = $request->getPath();
 return "user:{$userId}:{$path}";
 }
}

#[Get("profile")]
#[Cacheable(
 ttl: 300,
 keyGenerator: 'CacheKeys::userSpecific'
)]
public function getProfile(Request $request): Response
{
 // Each user gets their own cached response
}

HTTP Cache Headers

When addHttpHeaders: true (default), the following headers are added:

Cache-Control: public, max-age=3600
ETag: "5d41402abc4b2a76b9719d911017c592"
X-Cache-Status: HIT|MISS
Vary: Accept-Language (if varyHeaders specified)

Disable HTTP headers:

#[Cacheable(ttl: 3600, addHttpHeaders: false)]
public function getData(Request $request): Response
{
 // Cache internally but don't send cache headers to client
}

Cache Management

Invalidate by tag:

use Baukasten\Webservice\ResponseCache;

ResponseCache::invalidateByTag('users');
ResponseCache::invalidateByTag('user:123');

Clear all cached responses:

ResponseCache::clear();

Clear specific bucket:

ResponseCache::clear('custom_bucket');

Disable caching globally:

// Caching is disabled by default until init() is called
// ResponseCache::init() automatically enables caching

// Disable caching after initialization (useful for development)
ResponseCache::disable();

// Re-enable when needed
ResponseCache::enable();

// Check if enabled
if (ResponseCache::isEnabled()) {
 // ...
}

Example: Disable caching in development:

// index.php
use Baukasten\Webservice\ResponseCache;

// Initialize caching (this enables caching automatically)
ResponseCache::init();

// Disable in dev environment
if ($_ENV['APP_ENV'] === 'dev') {
 ResponseCache::disable();
}

Note: Caching is disabled by default until ResponseCache::init() is called. Calling init() automatically enables caching. You can then disable it with disable() if needed.

Cache Backends

FileBucket (default):

• Stores cache on disk
• Survives server restarts
• Good for single-server setups

MemoryBucket:

• In-memory storage (lost when process ends)
• Fastest option
• Good for development/testing

RedisBucket:

• Shared across multiple servers
• Persistent and fast
• Best for production multi-server environments

Complete Example

Here's a full REST API example with caching, CORS, and error handling:

<?php
// src/Controllers/ApiController.php

use Baukasten\Webservice\Controller\Controller;
use Baukasten\Webservice\Attribute\Endpoint\{Get, Post, Put, Delete};
use Baukasten\Webservice\Attribute\Middleware\{Cacheable, Cors};
use Baukasten\Webservice\Request;
use Baukasten\Webservice\Response\{JsonResponse, ErrorResponse, Response};
use Baukasten\Webservice\ResponseCache;
use Baukasten\Webservice\HttpMethod;

class ApiController extends Controller
{
 public function __construct()
 {
 parent::__construct('api/v1');
 }

 // Optional: Authentication check for all endpoints
 public function prepare(Request $request): ?Response
 {
 // Allow public endpoints
 $publicPaths = ['/api/v1/health', '/api/v1/products'];
 if (in_array($request->getPath(), $publicPaths)) {
 return null;
 }

 // Check API key
 $apiKey = $request->getHeaders()['X-API-Key'] ?? '';
 if (!$this->isValidApiKey($apiKey)) {
 return new ErrorResponse('Invalid API key', 401);
 }

 return null;
 }

 #[Get("health")]
 #[Cors(allowedOrigins: ['*'])]
 public function health(Request $request): Response
 {
 return new JsonResponse([
 'status' => 'ok',
 'timestamp' => time()
 ]);
 }

 #[Get("products")]
 #[Cors(allowedOrigins: ['*'])]
 #[Cacheable(ttl: 3600, tags: ['products'])]
 public function listProducts(Request $request): Response
 {
 $page = (int)($request->getQueryParams()['page'] ?? 1);
 $limit = (int)($request->getQueryParams()['limit'] ?? 20);

 $products = $this->productRepository->paginate($page, $limit);

 return new JsonResponse([
 'data' => $products,
 'page' => $page,
 'total' => count($products)
 ]);
 }

 #[Get("products/{id}")]
 #[Cors(allowedOrigins: ['*'])]
 #[Cacheable(ttl: 1800, tags: ['products', 'product:{id}'])]
 public function getProduct(Request $request): Response
 {
 $id = $request->getUrlParams()['id'];
 $product = $this->productRepository->find($id);

 if (!$product) {
 return new ErrorResponse('Product not found', 404);
 }

 return new JsonResponse($product);
 }

 #[Post("products")]
 #[Cors(
 allowedOrigins: ['https://admin.example.com'],
 allowedMethods: [HttpMethod::POST]
 )]
 public function createProduct(Request $request): Response
 {
 $data = json_decode($request->getBody(), true);

 if (!$this->validateProduct($data)) {
 return new ErrorResponse('Invalid product data', 400);
 }

 $product = $this->productRepository->create($data);

 // Invalidate product list cache
 ResponseCache::invalidateByTag('products');

 return new JsonResponse($product, 201);
 }

 #[Put("products/{id}")]
 #[Cors(
 allowedOrigins: ['https://admin.example.com'],
 allowedMethods: [HttpMethod::PUT]
 )]
 public function updateProduct(Request $request): Response
 {
 $id = $request->getUrlParams()['id'];
 $data = json_decode($request->getBody(), true);

 $product = $this->productRepository->update($id, $data);

 if (!$product) {
 return new ErrorResponse('Product not found', 404);
 }

 // Invalidate specific product and list
 ResponseCache::invalidateByTag('product:' . $id);
 ResponseCache::invalidateByTag('products');

 return new JsonResponse($product);
 }

 #[Delete("products/{id}")]
 #[Cors(
 allowedOrigins: ['https://admin.example.com'],
 allowedMethods: [HttpMethod::DELETE]
 )]
 public function deleteProduct(Request $request): Response
 {
 $id = $request->getUrlParams()['id'];
 $deleted = $this->productRepository->delete($id);

 if (!$deleted) {
 return new ErrorResponse('Product not found', 404);
 }

 // Invalidate caches
 ResponseCache::invalidateByTag('product:' . $id);
 ResponseCache::invalidateByTag('products');

 return new JsonResponse(['deleted' => true], 204);
 }

 private function isValidApiKey(string $apiKey): bool
 {
 // Your API key validation logic
 return $apiKey === 'your-secret-key';
 }

 private function validateProduct(array $data): bool
 {
 return isset($data['name']) && isset($data['price']);
 }
}

Bootstrap:

<?php
// public/index.php

require_once __DIR__ . '/../vendor/autoload.php';

use Baukasten\Webservice\Router;
use Baukasten\Webservice\ResponseCache;

// Initialize response caching
ResponseCache::init([
 'cache_dir' => __DIR__ . '/../cache/responses'
]);

// Handle requests
Router::handleRequest([
 ApiController::class,
 // Add more controllers
]);

Development

Running Tests

With Docker (recommended):

./run-phpunit.sh # Run all tests
./run-phpunit.sh --testsuite Unit # Run unit tests
./run-phpunit.sh --testsuite EndToEnd # Run integration tests
./run-phpunit.sh --filter RouteTest # Run specific test
./run-phpunit.sh --coverage-text # Generate coverage report

Without Docker:

COMPOSER=composer-dev.json composer update --ignore-platform-reqs
vendor/bin/phpunit

Installing Dependencies

# Development environment
COMPOSER=composer-dev.json composer update --ignore-platform-reqs

# Production
composer install --no-dev

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.