Download the PHP package appserver-io/routlt without Composer

Rout.Lt 2

Introduction

Rout.Lt 2 provides a small, but very fast, implementation of a routing and controller implementation for usage with appserver.io based on a servlet.

Installation

If you want to write an application that uses Rout.Lt 2, you have to install it using Composer. To do this, simply add it to the dependencies in your composer.json

Configuration

Rout.Lt 2 comes with it's own annotations and configuration files.

Application

Therefore, it is necessary, that these annotations as well as all other framework specific configuration files will be initialized on application startup. To ensure this, you have to provide a custom META-INF/context.xml file with your application, which needs the additional <descriptors/> node for the object manager configuration

Servlet Engine

As Rout.Lt 2 is based on a servlet, you also need to provide an WEB-INF/web.xml your application.

Let's assume, you've installed appserver.io on Linux/Mac OS X under /opt/appserver and your application is named myapp you'll save the web.xml containing the following content in directory /opt/appserver/myapp/WEB-INF

Action Mapping

As Rout.Lt 2 provides annotations to configure routes and actions, the routlt.json configuration file, needed for version ~1.0, is not longer necessary nor supported.

Using Annotations

You have two annotations, namely @Path and @Action to configure the routing of your application. These annotations give you the possibility to map the Path Info of a request to a method in an action class. This mechanism is adopted by many of the available frameworks. The Path Info segments will be separated by a slash. The first segment has to map to the value of the @Path annotations name attribute, the second to one of the @Action annotations of one of methods.

For example, assuming you want to dispatch the URL http://127.0.0.1:9080/myapp/index.do/index/login, you need the implementation of an action class that looks like this.

After saving the above code to a file named /opt/appserver/webapps/myapp/WEB-INF/classes/MyApp/Actions/IndexAction.php and restarting, open the URL http://127.0.0.1:9080/myapp/index.do/index with your favorite browser. You should see Hello World! there.

If you don't specify the name attributes, depending on the annotation, Rout.Lt uses the class or the method name. As the Action suffix has to be cut off, it is important, that the action and the action methods always ends with Action and nothing else.

Wildcards

Up with version 2.2 you can also use wildcards in the @Action annotation's name attribute, e. g.

The values, mapped by the wildcards, are available, as usual request parameters, through the $servletRequest->getParameter() method, e. g.

Restrictions

Additionally to the wildcards it is possible to define restrictions for each wildcard like

If a restriction is defined, the variable is only mapped, if the restriction complies. The functionality behind the restrictions uses regular expressions to make sure, the passed value complies. Therefore, each restriction consist's of the wildcard name and the restriction term itself e. g. {"id", "\d+"}. The restriction term must be a valid regular expression term, like \d+ that makes sure, that the value MUST be a digit. If no restriction has been set, Rout.Lt assumes that the passed value is a string and uses the defaul \w+ term to check the consistency.

Defaults

Beside the restrictions it is possible to define default values for wildcards, like

If the relation has not been given in the path info, like /articles/3, the default value author will be set and is available as request parameter then.

Action -> Request Method Mapping

Sometimes it is necessary to allow action invocation only for selected request methods. For example, it has to be possible to configure the indexAction() only to be invoked on a POST request. To do this, you can add a @Post annotation to the methods doc block, like

Annotations are available for all request methods CONNECT, DELETE, GET, HEAD, OPTIONS, POST, PUT, PATCH and TRACE. If you don't add one of the above annotations, an action will be invoked on ALL of the request methods.

If you add one of them, the action will be invoked on that annotation only. On all other request methods, a AppserverIo\Psr\Servlet\ServletException with a 404 status code will be thrown, which results in a 404 error page.

Results

By specifying results with the @Results annotation, a developer is able to specify a post processor, to process action results, e. g. by a template engine. By default, Rout.Lt 2 provides a servlet that uses simple DHTML files as templates and processes them in the scope of the servlet's process() method. This allows access to servlet request/response instances as well as servlet configuration parameters.

The following example uses a @Results annotation, which contains a nested @Result annotation, to process the /path/to/my_template.dhtml after invoking the indexAction() method.

It is possible to specify as many @Result annotations as necessary to support allow result processing in different use cases. Which result has to be used, depends on the string value, returned by your action.

The DHTML file, that has to be stored under <PATH-TO-WEBAPP>/path/to/my_template.dhtml specified above will load the string, added as request attribute in the indexAction() method and renders it as a HTML document.

Limitations

Rout.Lt 2 starts with annotations as only configuration option. There is NO possiblity to configure the actions with a deployment descriptor. Issue #21 has already been created to find solution therefore.

External Links

• All about appserver.io at appserver.io