webx/routes

Wednesday, November 15, 2017
by niclaslindberg
Repository
1 Watchers
2 Stars
184 Installations

PHP
1 Dependents
0 Suggesters
1 Forks
0 Open issues
63 Versions
0 % Grown

The README.md

WebX-Routes - A PHP controller framework

Main features and design goals of webx-routes: * Simplicity - Easy to follow request/response routes to business logic in a natural hierarchical model. * Scalability - never load unnecessary files * Dependency injection (IOC) everywhere. * Testability - clear separation of view- and business objects by glueing it all together., _(*1)

Getting started

In composer.json add:, _(*2)

 {
    "require" : {
        "webx/routes" : "major.minor.patch"
    }
 }

Writing your first Routes index.php `public/index.php`

    use WebX\Routes\Api\RoutesBootstrap;
    use WebX\Routes\Api\Response;

    require_once "../vendor/autoload.php"; // $_SERVER["DOCUMENT_ROOT"] points to 'public' folder.

    RoutesBootstrap::run(function(Response $response) {
        $response->typeJson([
            "user" =>
                ["name" => "Mr. Andersson"]
            ]
        ]);
        $response->data(1998,"user.popular"); //Merges the data into 'user.popular'
    });

Will generate JSON response:, _(*3)

    {
        "user" : {
            "name" => "Mr. Andersson",
            "popular" => 1998
        }
    }

Built-in ResponseTypes in Routes

Routes supports the following ResponseTypes out of the box * JsonResponse Renders data as Json (Default ResponseType). * TemplateResponseType Renders data with a template (Twig) * RawResponseType Renders data as is. * DownloadResponseType Renders data as a downloadable file. * RedirectResponseType 301 or 302 redirect to a different url. * FileContentResponseType Sends a file's content to browser with auto detecting content-type., _(*4)

Routing in Routes

    use WebX\Routes\Api\RoutesBootstrap;
    use WebX\Routes\Api\Routes;
    use WebX\Routes\Api\Response;

    RoutesBootstrap::run(function(Routes $routes) {

        $routes->onSegment("api",function(Routes $routes) {

            $routes->onMatch("v(?P<version>\d+)$",function(Routes $routes,$version) {
                $routes->load("api_v{$version}");                      // $version from RegExp

            })->onAlways(Response $response) {
                $response->typeJson(["message"=>"Not a valid API call"]);
            });

        })->onAlways(function(Response $response){
            $response->typeRaw();
            $response->data("Sorry, page not found.");
            $response->status(404);

        })
    });

Routing in Routes - with url parameters example

    use WebX\Routes\Api\RoutesBootstrap;
    use WebX\Routes\Api\Routes;
    use WebX\Routes\Api\Response;

    RoutesBootstrap::run(function(Routes $routes) {
        $routes->onAlways(function(Response $response, $myParam="default") {
            $response->typeRaw($myParam);
        }
    });

Will render: * hello for request on /hello * default for request on /, _(*5)

Route switches:

Route switches are evaluated top-down. If a route-switch is executed no further switches, in same the scope, are evaluated and executed., _(*6)

The following route switches are supported * onAlways($action) Executes without evaluation. * onTrue($expression,$action) Executes if $expression evaluates to true * onSegment("url-segment",$action) Evaluates the current url segment (complete url exploded by /). Within a route-switch match the current url-segment will advance one position. * onMatch("reg-exp",$action) Evaluates the reg-exp against a string (url is default). Matched parameters in the reg-exp will be used if the same variable name is used in the $action;, _(*7)

Using Twig

page.twig, _(*8)

    <html>
        <body>
            <h1>Welcome {{user.name}}</h1>
            Your input was {{input}}
        </body>
    </html>

    use WebX\Routes\Api\RoutesBootstrap;
    use WebX\Routes\Api\Response;
    use WebX\Routes\Api\Request;

    RoutesBootstrap::run(function(Response $response, Request $request) {
          $response->typeTemplate()->id("page");
          $response->data(["name"=>"Mr. Andersson"],"user");
          $response->data($request->parameter("input"), "input");
    });

Reading input

Routes provides a unified and type-safe way to read request input from query parameters and json- form-encoded requests., _(*9)

    use WebX\Routes\Api\RoutesBootstrap;
    use WebX\Routes\Api\Response;
    use WebX\Routes\Api\Request;

    RoutesBootstrap::run(function(Response $response, Request $request) {
          $reader = $request->reader(Request::INPUT_AS_JSON);
          $response->typeJson(["greeting"=>"Hello, {$reader->asString("user.name")}"]);
    });

Configuring Twig

Load a configuration changetwig (can be any name) at Bootstrap time., _(*10)

Example: To change Twigs tag-delimeters to {{{ and }}} (To simplify mixed Angular and Twig in the same page)., _(*11)

    use WebX\Routes\Api\RoutesBootstrap;
    use WebX\Routes\Api\Routes;
    use WebX\Routes\Api\Response;

    RoutesBootstrap::run([function(Routes $routes) {

        $routes->onAlways(function(Response $response) {
              $response->templateType()->id("page");
              $response->data(["name"=>"Mr. Andersson"],"user");
        })

    },"changetwig"]);

Override the setting for TemplateResponseType to add a configurator for Twig config/changetwig.php:, _(*12)

    return [
        "responseTypes" => [
            "WebX\\Routes\\Api\\ResponseTypes\\TemplateResponseType" => [
                "config" => [
                    "configurator" => function(Twig_Environment $twig) {
                        $lexer = new Twig_Lexer($twig, array(
                            'tag_variable'  => array('{{{', '}}}')
                        ));
                        $twig->setLexer($lexer);
                    },
                    "options" => [    // Passed as second argument to Twig_Environment
                        "cache" => "/tmp/twig_cache"
                    ]
                ]
            ]
        ]
    ]

Loading configurations and the IOC container

All logic, in Routes, is executed in actions. An action can be either a: * \Closure * string (In format "ControllerClass#method"), _(*13)

To support lazy loading of configurations Routes allows actions to be defined as an array in the format: [$action,"config1","config2","configN"], _(*14)

src/MyBusiness/Impl/Services/AdminService.php, _(*15)

    use MyBusiness\Api\Services\IAdminService;

    class AdminService implements IAdminService {
        public function __construct() {}

        public function countAdmins() {
            return 3;
        }
    }

config/admin.php:, _(*16)

    use MyBusiness\Impl\Services\AdminService;

    return [
        "ioc" => [
            "register" => [
                [AdminService::class]
            ]
        ]
    ]

    use WebX\Routes\Api\RoutesBootstrap;
    use WebX\Routes\Api\Routes;
    use WebX\Routes\Api\Response;
    use MyBusiness\Api\Services\IAdminService;

    RoutesBootstrap::run(function(Routes $routes) {

        $routes->onSegment("admin",[function(Response $response, IAdminService $adminService) {
              $response->data($adminService->countAdmins(),"count");
        },"admin"]);

        // The admin-configuration is only loaded if routes matched the `admin` segment.
    });

Config file anatomy

The config files, that may be loaded at any level, are normal php files that are expected to return an array., _(*17)

Minimal config file (that does nothing):, _(*18)

Ioc container

The WebX-Ioc container is embedded in the WebX-Routes framework. WebX-Routes supports dynamic registration / static invokation of services in the config ioc section., _(*19)

Dynamically register a service with the WebX-Ioc container. config/someconfig.php, _(*20)

<?php

return [
    "ioc" => [
        "register" => [ // The classes will be scanned for all their implemented interfaces.
            [MyClass:class],
            [MyOtherClass:class]
        ],
        "initStatic" => [ //
            [MyValueObject::class,"initMethod"] // The static "initMethod" will be invoked with declared dependencies.
        ]
    ],
    "mappings" => [
        "closureParameterName" => "iocInstanceId"
    ]

]

Working with Controllers

Routes support a more traditional controller structure as well. Controllers are simple classes with their methods and constructors invoked with IOC support., _(*21)

Routes supports $action to be defined as a string in the format ControllerClass#method, _(*22)

    use WebX\Routes\Api\RoutesBootstrap;
    use WebX\Routes\Api\Routes;

    RoutesBootstrap::run(function(Routes $routes) {

        $routes->onSegment("admin",['MyBusiness\\Controllers\\AdminCtrl','adminConfig']
        // The admin-configuration is only loaded if routes matched the `admin` segment. Methods on the
        // controller will automatically be mapped by the next available segment

        // If no next segment exist Routes will map the request to `index()` of the controller instance
    });

src/MyBusiness/Controllers/AdminController.php, _(*23)


    namespace MyBusiness\Controllers;

    class AdminController {

        private $logService;

        public function __construct(ILogService $logService) {
            $this->logService = $logService;
        }

        public function countAdmins(Response $response, RawResponseType $responseType, IAdminService $adminService) {
            $response->type($responseType);
            $response->data("Hello there " + $adminService->countAdmins() + " admin(s)");
        }
    }
    #Controller functions can be invoked with user parameters. Parameters, taking precedence over IOC injected ones,
    #can be defined in the last arguemnt `$parameters` array or with parametes defiend in the `onMatch` switch.

Defining default namespaces for loading controllers

Full class names can be skipped by adding namespaces in the namespaces section of a dynamic configuration., _(*24)

config/admin.php:, _(*25)

    return [
        "namespaces" => ["MyBusiness\\Controllers"]
    ]

Creating your own `ResponseType`

To implement your own ResponseType simply create an interface that extends ResponseType with an implementation configure it with ioc/register in a config file. See bootstrap_config.php of how to configure., _(*26)

Configuring your own ResponseType in your config file:, _(*27)

    return [
        "responseTypes" => [
            "YourNamespace\\YourResponseTypeInterface" => [
                "class" => "YourNamespace\\YourResponseTypeClass",
                "config" => [
                    "yourSetting" => false // Will be available by Configuration to ResponseType.
                ]
            ]
        ]
    ]

Configuring Routes

Standard configuration in Routes is based on the applications directory relativly to the $_SERVER['DOCUMENT_ROOT']., _(*28)

Configuring RoutesBootstrap, _(*29)

    RoutesBootstrap::run($action,[
        "home" => "../"         // Default.
                                // Use '/' to have application in same directory
                                // as public files (not recommended).
    ]);

The default directory structure for a Routes application:, _(*30)

    /
        /config          (Config files loaded by [$action, "someconfig"]
            someconfig.php

        /routes          (Files loaded by Routes->load("someroute")
            someroute.php

        /templates       (Templates loaded by TemplateResponse->setTemplate("sometemplate")
            sometemplate.twig

        /public          ($_SERVER['DOCUMENT_ROOT'])
            index.php

        /vendor          (Composer)
            /webx
                /routes
                /ioc

Tests

Execute in root directory, _(*31)

    phpunit -c tests

The Versions

15/11 2017

dev-master

9999999-dev

library routes

webx/routes

The README.md

WebX-Routes - A PHP controller framework

Getting started

Writing your first Routes index.php public/index.php

Built-in ResponseTypes in Routes

Routing in Routes

Routing in Routes - with url parameters example

Route switches:

Using Twig

Reading input

Configuring Twig

Loading configurations and the IOC container

Config file anatomy

Ioc container

Working with Controllers

Defining default namespaces for loading controllers

Creating your own ResponseType

Configuring Routes

Tests

The Versions

dev-master

The Requires

The Development Requires

by Nillsoft AB

2.0.10

The Requires

The Development Requires

by Nillsoft AB

2.0.9

The Requires

The Development Requires

by Nillsoft AB

2.0.8

The Requires

The Development Requires

by Nillsoft AB

2.0.7

The Requires

The Development Requires

by Nillsoft AB

2.0.6

The Requires

The Development Requires

by Nillsoft AB

2.0.5

The Requires

The Development Requires

by Nillsoft AB

2.0.4

The Requires

The Development Requires

by Nillsoft AB

2.0.3

The Requires

The Development Requires

by Nillsoft AB

2.0.2

The Requires

The Development Requires

by Nillsoft AB

2.0.1

The Requires

The Development Requires

by Nillsoft AB

2.0.0

The Requires

The Development Requires

by Nillsoft AB

dev-rework

The Requires

The Development Requires

by Nillsoft AB

0.6.9

The Requires

The Development Requires

by Nillsoft AB

0.6.8

The Requires

Writing your first Routes index.php `public/index.php`

Creating your own `ResponseType`