README

Nette Extension for integration of SLIM for API

This extension brings the power of Slim for applications using Nette DI. It enables you to easily work with Slim middleware stack and develop your API easily.

The general idea has been discussed in this article. (Czech language)

Philosophy

Single Responsibility

The main idea is to delegate responsibilities of the code handling requests to separated middlewares. For example:

authentication
validation
business logic

How middlewares in Slim work is described here.

Easy configuration

Empowered by Nette DI and it's neon configuration syntax this package provides powerful and easy way to define your API.

Usage

So let's start!

composer require brandembassy/slim-nette-extension

Extension

Now register new extension by adding this code into your config.neon:

extensions:
    slimApi: BrandEmbassy\Slim\DI\SlimApiExtension # Register extension

slimApi: # Configure it
    slimConfiguration:
        settings:
            removeDefaultHandlers: true # It's recommended to disable original error handling 
                                        # and use your own error handlers suited for needs of your app. 

    apiDefinitionKey: api # Your API definition will be under this key in "parameters" section.

First API endpoint

Now let's say you want to make a REST endpoint creating channels, [POST] /new-api/2.0/channels

You need to define in parameters.api section in config.neon.

Both services and middlewares must be registered services in DI Container.

parameters:
    api:
        handlers:
            notFound: App\NotFoundHandler # Called when not route isn't matched by URL
            notAllowed: App\NotAllowedHandler # Called when route isn't matched by method
            error: App\ApiErrorHandler # Called when unhandled exception bubbles out

        routes:
            new-api: # This is name of your API
                "2.0": # Version of your API
                    '/channels': # Matched URL will be "your-domain.org/new-api/2.0/channels"
                        post:
                            # This is service will be invoked to handle the request
                            service: App\CreateChannelAction
                            
                            # Here middleware stack is defined. It's evaluated from bottom to top. 
                            middleware:
                                - App\SomeOtherMiddleware # last in row
                                - App\UsuallyRequestDataValidationMiddleware # second in row
                                - App\SomeAuthMiddleware # this one is called first 

        beforeRouteMiddlewares:
            # this is called for each route, before route middlewares
            - App\SomeBeforeRequestMiddleware 
            
        beforeRequestMiddlewares:
            # this is called for each request, even when route does NOT exist (404 requests)
            - App\SomeBeforeRouteMiddleware tests/Dummy/BeforeRequestMiddleware.php

You can also reference the named service by it's name.

See tests/SlimApplicationFactoryTest.php and tests/config.neon for more examples.

Execution

Now you can simply get SlimApplicationFactory class from your DI Container (or better autowire it), create app and run it.

$factory = $container->getByType(SlimApplicationFactory::class);
$factory->create()->run();

brandembassy / slim-nette-extension

Maintainers

Details