Download the PHP package hebbinkpro/pmmp-webserver without Composer

PMMP WebServer

A verion for PocketMine-MP plugins to create a simple HTTP/1.1 web server.

Plugins

• This virion is used in my Dynmap like plugin, PocketMap. You can find the plugin here

How to install

• Download the latest phar build from Poggit CI
• or install it directly using composer: composer require hebbinkpro/pmmp-webserver

How to use

Creating a web server

For creating a web server, you have to register the WebServer and create a new instance of WebServer to start the server.

Note that if you want to access the server outside your localhost or local network, you may need to port-forward, otherwise it will not be available for the outside web!

Routing

Routes are used to let your web server be able to do things. By creating a Route you can make your webserver listen to different paths and respond to them.

Router

The router is used to register all your routes. the router will also handle all incoming requests and make sure they are handled by the correct Route.
You can access the router of your WebServer by calling:

Route

A route is used to perform an action on an incoming web request.

Route Action

The route action is the task performed when a new request is sent to the correct path. The syntax for an action is

• $request is the incoming request
• $response is the response that will be returned to the client
• ...$params is an array with all given parameters. The parameters are given at the end of a new Route.

You can add as many params as you want, if you only want 1 param, you can use new Route($method, $path, $action, $param1), but if you want more than 1, you can add them behind the first param. new Route($method, $path, $action, $param1, $param2, $param3). Adding no parameters is also an option, new Route($method, $path, $action).
To use the ...$params variable in the action, you can use it as an array, so $params[0] will return the first parameter, and $params[1] will give you the second, ect.
Do not put any code that makes use of the main thread INSIDE the action function. Actions have to be ThreadSafe, so only things that DO NOT depend on the PocketMine thread will work. If you want to use classes that do not extend pmmp\thread\ThreadSafe, you can use serialize(...) for the parameter and unserialize(...) inside the action function

Router methods to create HTTP request routes

For the most common methods there are functions inside the Router instance. These functions make it so that you don't have to input an HTTP method for every new Route you want to make
The available method function in Router are:

• GET, a route that only listens to GET requests - Router->get($path, $action, ...$params)
• POST, a route that only listens to POST requests - Router->post($path, $action, ...$params)
• HEAD, a route that only listens to HEAD requests - Router->head($path, $action, ...$params)
• PUT, a route that only listens to PUT requests - Router->put($path, $action, ...$params)
• DELETE, a route that only listens to DELETE requests - Router->delete($path, $action, ...$params)
• USE (also known as ANY or * in Hebbinkpro\WebServer\http\HttpMethod), a route that listens to ALL HTTP methods - Router->all($path, $action, ...$params)

You can find more info about HTTP request methods here

The path and action arguments inside the router functions are the same as the once in Router.

Other Route types

There are three types of routes you can use outside the default Route implementations in the Router:

• Route - A basic route that makes you able to create your own responses for a path
• FileRoute - A route that sends a file as response
• RouterRoute - A route that functions as a Router, but only for the specified path
• StaticRoute - A route that makes you able to share the content of complete folders without making a Route for each different path.
• You are not restricted to those routes, but you can also create your own routes. The only requirement is that your custom route has to extend (a child of) \Hebbinkpro\WebServer\route\Route. You can add an instance of a Route to the Router using

But there are also functions in Router to easily add a FileRoute, RouterRoute or StaticRoute.

FileRoute

RouterRoute

Static Route

Paths

Route paths are the paths in the URL, these paths are very important because they contain the information about the page a client wants to see. But to make sure the client sees the correct page, the path of this page needs to have a Route. This is why for every Route you create, if it is using functions in the Router or by creating a new Route instance, you HAVE to provide a VALID path, otherwise a client cannot find or request your page.

Default paths

A path is nothing more than everything after the first / up to the end or ? in the uri after the address of a side.

prefixes

Sometimes you want a Route that listens to all requests that start with /foo, so also to /foo/bar or /foo/bar/etc.
We can accomplish this by adding a /* to the end of a path.

parameters

Sometimes you want to have a prefix, but also a suffix. To accomplish this, we introduce parameters. A parameter is a part of the path which can be any kind of string, so a path /:var/a will listen to /foo/a but also in /bar/a. To make it even better, you can also request all variables inside an HttpRequest using HttpRequest->getPathParams(), this will return an array with the parameter name as key and the value set to the value in the path.

Queries

The query of a path is everything behind the ? in a path, so /?foo=bar. There can be multiple queries after the ? by using the & sign between two values. A single query is represented as <name>=<value>.
To request all queries you can use HttpURI->getQuery(), or to request only a single value you can use HttpURI->getQueryParam($name).

HTTPS

Since v1.0.0, the web server also supports SSL certificates which make it possible to run an HTTPS server for a more secure connection than HTTP.
For enabling HTTPS on your webserver you have to add SslSettings to the HttpServerInfo BEFORE you start the web server. This can be done in multiple ways.

1. Let the WebServer detect SSL certificates in the cert folder of your plugin data by calling: $webServer->detectSSL().
2. Create a new SslSettings by calling $ssl = new SslSettings(...) and add it to the HttpServerInfo: new HttpServerInfo(..., $ssl) or by calling $serverInfo->setSSL($ssl). If you add the SSL settings AFTER you started the server, HTTPS will not be applied and your server will function as a normal HTTP server.

Credits

• This virion makes use of Laravel\SerializableClosure for sharing the action functions given in the Router on the main thread with the http server thread.