DISCLAIMER

The Sugoi framework is still under heavy development and breaking changes will be introduced.

COMING SOON

No source is available for installing the framework yet, this will be provided once a stable API has been implemented.

Getting started

To get started you simply need to set up a new project using composer with PSR-4 autoloading.

composer init \
    --require faylite/sugoi-php=dev-main \
    -a src/ --type project \
    --name=myproject/api

Next you'll need to make a "main" script at the root of your project, which is used to start the service and run other useful commands provided by the framework. For consistency, we recommend calling this file app.

./app

#!/usr/bin/env php
<?php

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

(new \SugoiCloud\Application)->run();

And that's it! Now you can start your new API by executing the app script. The service will then be running on port 3000 by default.

./app

TIP

SwaggerUI is bundled and can be opened through: http://localhost:3000/swagger-ui/index.html

Some features are automatically enabled for you out of the box for HTTP services. In particular SwaggerUI is bundled within the framework and auto-generates documentation based on the framework attributes.

Name	Path
Swagger-UI	/swagger-ui/index.html
OpenAPI Spec JSON	/swagger-ui/docs
Health Check	/health

Config

You'll probably also want to do some configuration. The framework supports two primary sources of configuration, the YAML configuration files, or the environment overrides.

The app.yml config files are mostly intended to be checked into version control and set up basic configuration. The env overrides are intended for sensitive configuration required for the deployments themselves, in particular for containerized environments.

A good rule of thumb is to make sure that your baseline app.yml configuration is all that is needed to actually start your API, this will make onboarding new developers much easier.

Cheatsheet

Quick overview of the configuration sources, and the load order from lowest to highest precedence.

Source	Description
./app.yml	Default configuration, should always be in version control.
./app.[profile].yml	Configuration for a specific environment, should probably be in version control.
./app.[profile].local.yml	Local overrides for a specific environment, should not be in version control.
System Environment	Environment variables have the highest precedence, use these for deployments.

TIP

Looking for .env files? In cloud environments there are several toolchains to build environment variables based on .env/.properties files for deployment pipelines, we recommend leveraging those to dynamically build your environment overrides instead.

Config options

The configuration system leverages Sugoi's internal DTO parsing and schema registry. This means you can generate complete schemas for all configuration classes in the code-base, including third-party.

./app dump:config

$schema: .sugoi/app.schema.json # Refer to the dumped configuration schema for full auto-complete and documentation.

sugoi:
    application:
        name: my-namespace-api # Application name to show in the log output
        prod: false # Production mode
    http:
        address: 0.0.0.0 # Address to bind to, generally should be kept to 0.0.0.0 for non-windows environments.
        port: 8080 # Override the default port.
        path: /api # Relative base path for the entire service.
    database: # Optional, configures the Illuminate DB Facade for you.
        driver: pgsql
        host: localhost
        port: 5432
        database: sugoi
        username: sugoi
        password: secret
        pool: 4
    messaging: # Optional, messaging/broker configuration.
        kafka: # Kafka is already here!
            brokers: localhost:9092
            group-id: my-namespace-api
    swagger-ui: # Optional, if you'd like to customize Swagger-UI
        display-operation-id: false

Environment overrides can be applied through UPPER_CASE variable names and are automatically parsed on startup. Dashes should also be replaced by underscores.

SUGOI_APPLICATION_NAME=my-namespace-api-001
SUGOI_HTTP_PORT=3000
SUGOI_SWAGGER_UI_DEEP_LINKING=false

Custom config options

Need your own configuration options? These are simple to add, all you need to do add a configuration data class and annotate it with the Config attribute. That's it! Now this class will be automatically parsed and validated on startup, and the config can be injected on demand.

Make sure to namespace configuration using the prefix, this way you'll avoid conflicts later down the line.

All configuration is piped through the same DTO parsing and schema registry regardless of where it came from. This means if you use the Tensei DTO / Schema attributes you can properly document all your configuration, and it will be included in the ./app dump:config schemas.

#[Config(prefix: 'myapi.myorder')
readonly class MyOrder {
    public function __construct(
        #[Property(example: 'Pizza', required: true)]
        public string $dish,
        public int $cost,
        public ?string $optional,
        public bool $noPickles = true,
    ) {
    }
}

To supply your configuration, simply add it to the relevant app.yml file, or supply it through the environment.

sugoi:
    application:
        name: my-namespace-api
myapi:
    myorder:
        dish: Cheeseburger
        cost: 70
        no-pickles: false

Data

Data schemas are generated automatically based on the actual data classes, Sugoi provides a wide range of attributes allowing you to customize the output.

In addition to (de)serialization, contracts and validation, these schemas are also used to auto-generate documentation for your entire API with OpenAPI compliant output by default.

TIP

All data objects are assumed immutable by default. The base Data class is a convenience, not a requirement if you'd rather use a readonly class.

src/Data/Project.php

#[Schema]
readonly class Project
{
    public function __construct(
        #[Property(example: 1, required: true, access: 'read-only')]
        public ?int      $id,

        #[Property(example: 'Sugoi Cloud')]
        public string    $name,

        #[Property(example: 'A type-safe PHP framework for the cloud-native future!')]
        public string    $description,

        #[PropertyAlias('demo_url')]
        #[Property(example: 'https://sugoi.cloud')]
        public ?string   $demoUrl,

        #[PropertyDateTime]
        public ?DateTime $createdAt,
    )
    {
    }
}

Your data objects do not require attributes to work, schemas will be inferred on the fly depending on the context, the attributes are primarily used for overriding defaults or adding more explicit information.

Jutsu

Protocol, techniques and programming patterns are called Jutsu in Sugoi. They are generally agnostic and re-usable across different transport protocols or integrated services. All Jutsu implementations are design to completely de-couple business concerns from actual API interfaces similar to other big enterprise frameworks.

Distributed tracing is supported out of the box through the use of Span natively in the framework. All tracing information will be initialised with sane defaults out of the box. Each HTTP SpanHttp request will receive a new standardized traceparent automatically, each WebSocket SpanWebSocket connection will be attached to a trace on connect, etc.

These simple spans contain basic context information, such as who's making the request (auth user), where it came from (original protocol), a unique trace ID and arbitrary manually defined metadata. These spans are encapsulated, so they can be passed around in async contexts if required without losing the original origin metadata data or trace. They are also used for direct logging, so there's no need for a logging facade, call-traces are automatically calculated.

The protocol layer will also handle all transformation, validation and (de)serialisation of request/response data before handlers are invoked. This means your DTOs are ready for consumption before ever hitting your controllers and can immediately be used in the business context.

HTTP

HTTP uses traditional controller patterns, while using attributes to do auto-discovery, and automatically generate OpenAPI documentation without any work required by the developer.

For the HTTP protocol there are 3 flavours of controllers.

Type	Description
ApiController	REST controllers
WebController	Traditional view controllers for HTML pages
CmdController	Practically web-hooks, simple RPC patterns for invoking commands.

Sugoi does not use traditional middleware patterns, and opted instead of a "Hint" pattern to abstract cross-cutting concerns into declarative nuggets of functionality. This keeps the data immutable to a certain extent.

Hints are registered using attributes similarly to controllers and only apply to controllers of the same type/group. This allows you to address cross-cutting concerns based on the implementation type, for example using JWT authentication through the ApiControllerHint and using cookies through the WebControllerHint, and perhaps a generic API token for the CmdControllerHint.

API Routing

Controllers are declared using attributes for routing. The Controller attribute is required for the controller to be discovered through auto-discovery.

TIP

Properties from a controller will be used as prefixes for the operation routes in the controller.

Everything in the controller layer requires explicit attributes except the SpanHttp contextual object that can be injected through the controller method. The variables injected through the controller method are the only instances that are scoped to the current request. The SpanHttp can be used to retrieve additional request data, or the authenticated user data if provided.

INFO

An OpenAPI spec will be automatically generated based on the class structures. In particular, operationIds are always generated based on the controller and method names without common suffixes, i.e "Controller".

This is enforced to support OpenAPI CodeGen out of the box.

[MethodName][ControllerName]

Example: ProjectsController@list => listProjects

Also note that, the Response and ResponseArray attributes are purely informational and is only used to generate response types for the generated OpenAPI spec.

src/Api/Http/ProjectsController.php

#[ApiController(path: 'projects', tag: 'Projects')]
class ProjectsController
{
    #[RouteGet]
    #[ResponseArray(200, 'List of projects', Project::class)]
    public function list(): array
    {
        return Project::collect(DB::table('projects')->select([
            'id',
            'name',
            'description',
            'demo_url',
            'created_at',
        ])->get()->toArray());
    }

    #[RouteGet("{id}")]
    #[Response(200, 'Project details', Project::class)]
    public function get(#[ParamPath] int $id): Project
    {
        return Project::from(DB::table('projects')
            ->where('id', '=', $id)
            ->select([
                'id',
                'name',
                'description',
                'demo_url',
                'created_at',
            ])
            ->firstOrFail()
        );
    }

    #[RoutePost]
    #[Response(200, 'Created project', Project::class)]
    public function create(#[RequestBody] Project $body): HttpResponse
    {
        return HttpResponseFactory::status(501);
    }

    #[RoutePut("{id}")]
    #[Response(200, 'Updated project details', Project::class)]
    public function update(#[ParamPath] int $id, #[RequestBody] Project $body): HttpResponse
    {
        return HttpResponseFactory::status(501);
    }

    #[RouteDelete("{id}")]
    #[Response(204, 'Deleted project')]
    public function delete(#[ParamPath] int $id): HttpResponse
    {
        return HttpResponseFactory::status(501);
    }
}

TIP

After setting up your first controller you can start testing the API through the bundled Swagger-UI. An API specification will be automatically generated on the fly when accessed.

Path: /swagger-ui/index.html

Web routing

Simple web pages can be made, Sugoi has built-in template rendering support using Latte, which has a short and simple template syntax that lends itself well to the rest of the framework, in addition to being very fast. But you can plug in whichever template rendering engine you want, and use a custom HttpResponse object to return it from the controller.

The template root directory is defaulted to src/views. But can be changed with the config property sugoi.http.views.

<h1>{$title}</h1>
<p>{$message}</p>

Notice how the ApiController attribute was also added here, if you wanted to (for some reason), you could in theory re-use all your controllers to render to either templates or JSON. The route discovery will always segregate controller hints by type regardless, so long as the routes themselves don't overlap this is completely valid usage.

#[WebController(path: '/')]
#[ApiController(path: '/api')]
class ExampleController
{
    #[RouteGet]
    #[RouteTemplate('home')]
    public function index(): array
    {
        return [
            'title' => 'Hello, World!',
            'message' => 'This works well you know!',
        ];
    }
}

Boundaries

Boundaries are used to handle cross-cutting concerns on a protocol level. Similar to middleware, but is modelled to be immutable "taps" by default.

All examples are written using the ApiBoundary, for WebBoundary you would do the exact same thing, there's no difference other than which controller they apply to.

TIP

A more generic HttpBoundary will likely be added in the future after support for more complicated priority orders and pattern matching has been implemented.

#[ApiBoundary]
class HttpConfig
{
}

Exception handlers

Exception handlers can be dynamically configured through the ExceptionHandler attribute. Any functions you register with this attribute will automatically be used to resolve http responses when that exception occurs.

The example provided demonstrates a simple way of handling failed authentication.

#[ApiBoundary]
class AuthorizationHandler
{
    #[OnException]
    public function handleAuthorizationException(AuthorizationException $ex): HttpResponse
    {
        return HttpResponseFactory::status(401);
    }
}

Enter Hooks (request interceptors)

Building on our exception handler example, let's define a request interceptor that handles basic token based authentication.

#[ApiBoundary]
class HttpConfig
{
    // Dependency injection is supported, but keep in mind that controller hints are
    // instantiated on startup and are not contextually exclusive to the current request.
    public function __construct(
        private readonly UserService $users,
    )
    {
    }

    /**
     * @throws AuthorizationException
     */
    #[OnEnter]
    public function checkAuthorization(SpanHttp $span): void
    {
        // Extract data from the original request.
        $token = Token::extract($span->getRequest()->header('Authorization'));

        // Check if we're authenticated.
        if ($token->isValid()) {
            // Set the auth context in the contextual Span to be used later.
            $span->setAuth(new AuthorizationProvider($this->users->get($token->sub)));
            return;
        }

        // Otherwise, check if the endpoints require authentication.
        if (!Str::startsWith($span->getRequest()->path(), ['/api/swagger-ui', '/api/health'])) {
            // If the endpoint is not public, throw an AuthorizationException for our
            // exception handler defined in the previous example.
            throw new AuthorizationException('Unauthenticated');
        }
    }
}

Exit Hooks (response interceptors)

Finally, response interceptors can be used to handle cross-cutting concerns that should happen after a request, such as logging, etc.

#[ApiBoundary]
class HttpConfig
{
    #[OnExit]
    public function logRequests(SpanHttp $span): void
    {
        // Example: log handled requests.
        // Tracing information included when logging through contextual spans.
        $span->debug($span->getRequest()->method() . " " . $span->getRequest()->path());
    }
}

Messaging

Kafka

Sugoi has built-in support for Kafka. You only need to install the rdkafka extension.

Consumers

This works the exact same way as the HTTP controllers. Use the KafkaConsumer to register your handler for auto-discovery.

#[KafkaConsumer]
class OrderHandler
{
    #[MessageSub(topic: 'orders')]
    public function onSomething(SpanKafka $span, Order $order): void
    {
        $span->debug('Order accepted', Tensei::toArray($order));
        $span->reject(); // Various Kafka specific message APIs are included on the Span.
    }
}

Producers

Client/producer implementations will be auto-generated by the framework, you only need to define your interfaces and the framework will handle the rest in the background.

#[KafkaProducer]
interface OrderProducer
{
    #[MessagePub(topic: 'orders')]
    public function onOrderCreated(Order $order);
}

WebSockets

WebSockets works pretty much the same way as Kafka out of the box.

Listening

This works the exact same way as the HTTP controllers. Use the WebSocketListener to register your handler for auto-discovery.

#[WebSocketListener]
class OrderListener
{
    #[MessagePub]
    public function onMessage(SpanWebSocket $span)
    {
        $span->getConnection()->send('custom payload');
    }
}

Broadcasting

As with Kafka, the client implementation is auto-generated by the framework. This also includes IPC routing of messages. Since WebSockets are open connections, sending a payload to a specific client needs to be sent from the server the connection is open on. Sugoi handles this automatically in the background out of the box with IPC messaging through Sugoi Chumon.

#[WebSocketClient]
interface WsClientTest
{
    #[MessagePub]
    public function publish(string $payload);
}