Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Simplify and clarify routing in quick start; remove default route #94

Merged
merged 3 commits into from
Jan 26, 2022
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 16 additions & 54 deletions docs/book/quick-start.md
Original file line number Diff line number Diff line change
Expand Up @@ -212,79 +212,41 @@ for more details.)

## Create a Route

Now that we have a controller and a view script, we need to create a route to it.
Routes determine which controller to call based on the URI and other information from the request.

> ### Default routing
>
> `LaminasSkeletonModule` ships with a "default route" that will likely get
> you to this action. That route is defined roughly as
> `/{module}/{controller}/{action}`, which means that the path
> `/laminas-user/hello/world` will map to `LaminasUser\Controller\HelloController::worldAction()`
> (assuming the module name were `LaminasUser`).
>
> We're going to create an explicit route in this example, as
> creating explicit routes is a recommended practice. The application will look for a
> `Laminas\Router\RouteStackInterface` instance to setup routing. The default generated router is a
> `Laminas\Router\Http\TreeRouteStack`.
>
> To use the "default route" functionality, you will need to edit the shipped
> routing definition in the module's `config/module.config.php`, and replace:
>
> - `/module-specific-root` with a module-specific root path.
> - `LaminasSkeletonModule\Controller` with `<YourModuleName>\Controller`.

Additionally, we need to tell the application we have a controller:

```php
// module.config.php
return [
'controllers' => [
'invokables' => [
'<module-namespace>\Controller\Index' => '<module-namespace>\Controller\IndexController',
// Do similar for each other controller in your module
],
],
// ... other configuration ...
];
```

> ### Controller services
>
> We inform the application about controllers we expect to have in the
> application. This is to prevent somebody requesting any service the
> `ServiceManager` knows about in an attempt to break the application. The
> dispatcher uses a special, scoped container that will only pull controllers
> that are specifically registered with it, either as invokable classes or via
> factories.

Open your `config/module.config.php` file, and modify it to add to the "routes"
and "controller" parameters so it reads as follows:
Configure a route and a controller:

```php
// config/module.config.php
return [
'router' => [
'routes' => [
'<module name>-hello-world' => [
'type' => 'Literal',
'options' => [
'route' => '/hello/world',
// route name: used to generate links, among other things
'hello-world' => [
'type' => Laminas\Router\Http\Literal::class, // exact match of URI path
'options' => [
'route' => '/hello/world', // URI path
'defaults' => [
'controller' => '<module name>\Controller\Hello',
'controller' => Application\Controller\HelloController::class, // unique name
'action' => 'world',
],
],
],
],
],
'controllers' => [
'invokables' => [
'<module-namespace>\Controller\Hello' => '<module-namespace>\Controller\HelloController',
// tell the application how to instantiate our controller class
'factories' => [
Application\Controller\HelloController::class => Laminas\ServiceManager\Factory\InvokableFactory::class,
],
],
// ... other configuration ...
];
```

When the URI path of the request matches `/hello/world`, the specified controller and action will be used. The controller name must be present in the `controllers` list. The associated class will then be instantiated and invoked.

Learn more about routing [here](https://docs.laminas.dev/laminas-router/routing).

## Tell the Application About our Module

One problem: we haven't told our application about our new module!
Expand Down