Download the PHP package ginger-tek/routy without Composer

Getting Started

Composer

Starter Example

Handlers for each route can be any kind of callable, such as regular functions, arrow functions, closure variables, or static class methods.

Configurations

You can pass an associative array of optional configurations to the constructor.

• root to set the root app directory when running from a sub-directory, i.e. public/. Defaults to current directory.
• base to set a global base URI when running from a sub-directory
• render to set a default template rendering strategy to use in the render() response method. Defaults to false.

If you need to use any of these configuration values later on, you can access them using getConfig(); however, you can not update configurations after instantiation.

Features

Method Wrappers

Use the method wrappers for routing GET, POST, PUT, PATCH, or DELETE method requests. There is also a catch-all wrapper for matching on all standard HTTP methods, including HEAD and OPTIONS.

Use * for the route argument to match on any route.

Custom Routing

You can also use the route() method directly, which is what the common method wrappers use underneath, to craft more specific method conditions on which to match.

Dynamic Routes

To define dynamic route parameters, use the :param syntax and access them via the getParam() method on the $app context. The values are URL-decoded automatically.

Middleware

Global Middleware

If you want to define global middleware, you can use the use() method. Any middleware or route handler callable must have one argument to accept the current Routy instance.

(See Context Sharing about sharing data between middleware/handlers)

Route Middleware

All arguments set after the URI string argument are considered middleware functions, including the route handler, so you can define as many as needed.

Context Sharing

To share data between handlers/middleware or provide a global resource to the instance, use the setCtx() and getCtx(). Any data type can be passed in for the value.

Route Groups

You can define route groups using the group() method.

You can also add middleware to your nested routes, which will apply it to all the routes nested within.

Fallback Routes

Fallbacks are used for returning custom 404 responses, or to perform other logic before returning.

To set a fallback route, use the fallback() method to set a handler function, which will automatically have the HTTP 404 response header set.

Fallback routes are scoped to wherever they are defined, and will only be reached if they match the incoming URI's parent path.

Serve Static Files (SPA)

To serve static files from a specified directory via a proxy route, use the serveStatic() method after all other normal route definitions. You can use this to serve asset files or a whole SPA from the same app. If the requested URI is a directory, an index.html file will be served, if one exists, and client-side routing will take over. Otherwise, if any requested file is not found, a generic 404 response with be sent back.

NOTE: Serving static files is typically best performed by a web server (Apache/nginx/Caddy) via rewrite rules, so this is a convienence for less demanding applications. Consider your performance requirements in production scenarios when using this feature.

Request Properties

You can access the incoming request via the uri and method properties on the $app instance.

Request Helper Methods

There are a few helper methods for handling incoming requests.

getQuery()

Use to retrieve an incoming URL query parameter. Key lookup is case-sensitive. Returns false if not found.

getParam()

Use to retrieve an incoming URI request parameter. Key lookup is case-sensitive. Returns false if not found.

getBody()

Use to retrieve the incoming payload data. JSON data will automatically be decoded and form data will be cast to a standard object for cleaner syntax. For all other data types, body data will be left as is.

getHeader()

Use to retrieve an incoming HTTP header by name. Lookup is case-insensitive, i.e. both Content-Type and content-type will work.

getFiles()

Use to retrieve uploaded files from multipart/form-data requests. Returns an object array of all files.

Response Helper Methods

There are plenty of helper methods for handling responses.

sendData()

Use to return string data or a file's raw contents.

If the data is a file path, the Content-Type will be automatically detected, if it has a known MIME type.

Otherwise, the Content-Type can be specified explicitly.

sendJson()

Use to return data as a JSON string

render()

Use to render a view file, calling the configured render strategy callback. Template rendering strategy is left up to the developer, allowing for the use any kind of templating engine.

To configure a template rendering strategy, set the render option on your Routy instance to a callback. This callback must follow this argument signature:

The callback must return a string value of your rendered content, which will be returned as the response. The app instance can be useful for acceessing the root path when dealing with nested directory structures.

Below is an example using Twig:

Another example using plain PHP templating:

status()

Use to set the HTTP status code. This method can chained to other response methods.

redirect()

Use to send a temporary or permanent redirect to a new URL.

end()

Use to return immediately with an optional HTTP status code.