Streetlamp

Table of Contents

• 1. Introduction
• 2. Prerequisites
• 3. Setup
• 3.1. Installing the library
• 3.2. Application Wrapper
• 3.3 Creating a Controller
• 3.4. Creating a Route
• 4. PSR Compliance
• 5. Further Reading

1. Introduction

Streetlamp is a simple routing library that allows you to quickly prototype APIs. This library was built around the basic concepts of annotative routing, commonly found in Java libraries such as JAX-RS and Spring. Although the way it works is inspired from the aforementioned Java libraries, it has a slightly unique implementation more fitting the PHP language.

2. Prerequisites

To keep up with modern standards this library was built using PHP 8.4 and therefore will only run in said environment or greater. Due to the speed of which PHP is evolving, it is recommended to always use the latest stable version of PHP. Finally, this project requires composer and the PSR-4 Autoload standard.

3. Setup

3.1. Installing the library

Simply include Streetlamp in your project with the composer command:

composer require willitscale/streetlamp

3.2. Application Wrapper

To run your application through the Streetlamp wrapper all you need to do is instantiate the Router class and call route. The Router will use a RouteBuilder to scan all of your namespaces in the composer.json (excluding test namespaces by default) and setup corresponding routes.

Here's all the code you need to get going:

<?php declare(strict_types=1);

require_once 'vendor/autoload.php';

use willitscale\Streetlamp\Router;

new Router()->route();

This will use a simple out of the box configuration, if you require any customisation this can be achieved with the RouterConfig. There's a comprehensive guide on configuration in the Configuration page.

3.3 Creating a Controller

A controller can be defined by simply giving a class the attribute of RouteController.

<?php declare(strict_types=1);

namespace Example;

use willitscale\Streetlamp\Attributes\Controller\RouteController;

#[RouteController]
class MyRouteClass {
}

Only classes with the RouteController attribute will be scanned for routes.

3.4. Creating a Route

Each public method within a RouteController can be annotated as a route. There's three requirements to transform a method into a route:

• add a HTTP method attribute to the method,
• a path attribute to the method or class and
• return the ResponseBuilder object.

Let's say we want to create a route for the request GET /hello HTTP/1.1, we would need to attribute our route method with the Get and Path attributes.

Here's what that would look like in code:

<?php declare(strict_types=1);

namespace Example;

use Psr\Http\Message\ResponseInterface;use willitscale\Streetlamp\Attributes\Controller\RouteController;use willitscale\Streetlamp\Attributes\Path;use willitscale\Streetlamp\Attributes\Route\Method;use willitscale\Streetlamp\Builders\ResponseBuilder;use willitscale\Streetlamp\Enums\HttpMethod;use willitscale\Streetlamp\Enums\HttpStatusCode;

#[RouteController]
class MyRouteClass
{
    #[Path('/hello')]
    #[Method(HttpMethod::GET)]
    public function simpleGet(): ResponseInterface
    {
        return new ResponseBuilder()
            ->setData('world')
            ->setHttpStatusCode(HttpStatusCode::HTTP_OK)
            ->build();
    }
}

You could also apply the #[Path('/hello')] attribute to the RouteController class itself. In this case, all routes defined within the controller will have that path prefixed automatically, so you do not need to apply a path to each method individually.

4. PSR Compliance

PSR Standard	Description	Streetlamp Compliance
PSR-1	Basic Coding Standard	✅
PSR-3	Logger Interface	✅
PSR-4	Autoloading Standard	✅
PSR-6	Caching Interface	❌
PSR-7	HTTP Message Interface	✅
PSR-11	Container Interface	❌
PSR-12	Extended Coding Style Guide	✅
PSR-13	Hypermedia Links	❌
PSR-14	Event Dispatcher	❌
PSR-15	HTTP Handlers	✅
PSR-16	Simple Caching	✅
PSR-17	HTTP Factories	❌
PSR-18	HTTP Client	❌

5. Further Reading

• Routing Attributes
• Custom Attributes
• Input Attributes
• Data Mapping
• Server Sent Events
• Validators
• Caching
• Configuration
• Setup
• Testing
• Error Codes
• Commands
• Performance
• TODO