Download the PHP package shaggy8871/yurly without Composer

Yurly

Yurly is a lightweight web MVC routing library for PHP 7. It's easy to get started, requires almost zero configuration, and can run within existing projects without a major rewrite.

It also supports a multi-site implementation right out of the box.

Table of Contents

1. Installation
2. Basic Routing
3. Route Parameters
4. Accepting Multiple Request Types
5. Middleware
6. Custom Request/Response Classes
7. Dependency Injected Parameters
8. Custom Route Resolvers
9. Multi-site Setup
10. Using ymake Helper
11. Unit Testing

Installation:

In composer.json:

Replace Myapp with the name of your project.

Then run:

Create your project

Once composer dependencies are installed, run the following to create a basic project file structure, along with your first set of controllers and tests:

If all works as planned, you should see output as follows:

To test the website, run the following:

Then open http://localhost:8000/ in your browser.

To run unit tests:

Basic Routing

By default, routes are determined based on the controller class name and method name.

Controllers must extend the Yurly\Core\Controller class, and must contain at least one method name prefixed with the word route.

Request and Response classes can be injected into any route method. The first Response class found will be used to render any value returned from the route* method.

Example src/Controllers/Index.php file:

Route Parameters

Route parameters can be specified using a @canonical docblock statement above the route.

In the example above, calling /example/hello/world will return a JSON response as follows:

Accepting Multiple Request Types

The generic Request class has helper functions that can be used to extract multiple request types.

Middleware

Yurly exposes options for middleware code to run before and after a route is called.

@before

For each route, adding a @before docblock above the method declaration will run the designated methods before calling the route. This may, for instance, be used to point the user to an alternative route, or to look up additional metadata before the route code runs. Middleware may be specified as either the name of the method to call, or if outside the controller, in the form Controller::method. Multiple methods may be specified as a comma-delimited list and will be run in the order supplied.

To alter the route that gets rendered, middleware should return an alternative route as a string in the form Controller::routeMethod.

To run code before all routes in a controller are called, add a beforeAllRoutes() method to the controller. This will be run before all @before docblock methods are called.

@after

The @after docblock will call the designated class methods after the route has run. Each middleware method will receive a copy of the response, and may alter it before it renders to the browser. Multiple methods may be specified as a comma-delimited list and will be run in the order supplied.

To run middleware after all routes in a controller are called, add an afterAllRoutes() method to the controller. This code will be run before all @after docblock methods are called.

src/Myapp/Middleware/Auth.php:

src/Myapp/Controllers/Admin.php:

MiddlewareState

Middleware methods are able to use a class called MiddlewareState to check the response from the previous middleware method, and to stop the router from calling subsequent middleware methods if need be.

Calling stop() does not prevent the route from being called. It only prevents subsequent middleware methods from being called.

src/Myapp/Controllers/Admin.php:

Custom Request/Response Classes

Custom Request and Response classes may be created to supply additional functionality not already supplied by the built-in classes. Examples include additional input sources, improved input sanitisation and output data mapping.

Model Lookup and Data Mapper Example

src/Myapp/Models/User.php:

src/Myapp/Inject/Request/UserFinder.php:

src/Myapp/Inject/Response/UserJsonDataMapper.php:

src/Myapp/Controllers/User.php:

Dependency Injected Parameters

Yurly does not include native support for dependency injection outside of Request and Response classes, but it's easy enough to add a PSR-11 compatible DI solution through composer. Here's an example using PHP-DI:

composer.json

src/Myapp/Config.php:

src/Myapp/Controllers/Index.php:

Custom Route Resolvers

If you have routes that don't follow the controller/method approach, it's easy to create a custom route resolver class that can handle custom routing.

Create a class called RouteResolver at the base of your project directory, and ensure it implements RouteResolverInterface. It must contain one method called resolve that returns a route in the format Controller::method. Any other return value will be ignored.

Multi-site Setup

In composer.json, add a psr-4 autoload for each unique namespace, for example:

In public/index.php, enter a project row for each unique domain:

Create a Controllers directory within both /src/Site1 and /src/Site2 and add your Index.php controller class. You may also create Models, Views and any other directories as may be required.

If you need to support multiple hosts for a project, you can either pass in an array of hosts, or use a RegExp helper class as follows:

or

Using ymake Helper

Yurly ships with a helper application called ymake. You can use the helper to create a project, set of controller, model and view files, or an index.php file.

1. Add an autoload namespace to composer.json, for example:

2. Run the appropriate command to generate scripts:

You will be prompted for further details based on the command used.

Unit Testing

Yurly extends PHPUnit's TestCase class with additional methods to help with testing of routes. Here's a simple example:

If you prefer to capture the full route response output, just call the route as follows:

You can mock request classes in order to test your controllers with different inputs.

The class type declared in the route method cannot be changed.

To test generic Request classes (where the request method is unknown in advance, or where multiple inputs are expected within a single request), use the setTypeProps method to configure props for each request type. To set the default request method, pass requestMethod via array as a second parameter to the $this->setUrl() method.

You can mock the response class as well, and capture the output before it renders.

You cannot pass a mock Request class to getRouteResponse as it already uses one to capture the output. Instead, use the callRouteWithMocks method.