You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+21-16Lines changed: 21 additions & 16 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,28 +1,31 @@
1
-
# dk-controller
1
+
# dot-controller
2
2
3
-
This package contains controller like middleware to be used inside a DotKernel or Expressive application. It provides base classes for action based controllers similar to ZF3 controller component. It is more lightwight though, but supports controller plugins.
3
+
This package contains controller like middleware to be used inside a DotKernel or Expressive application. It provides base classes for action based controllers similar to ZF3 controller component. It is more lightweight though, but supports controller plugins.
4
4
5
5
## Installation
6
6
7
7
We use this in our web starter packages, so it will automatically be installed if you use them. For manual installation, just add the appropriate package to your `composer.json`
8
8
9
-
`composer install n3vrax/dk-controller`
9
+
```bash
10
+
$ composer require dotkernel/dot-controller
11
+
```
10
12
11
-
For default module dependencies, you need to merge the ConfigProvider class output to your config. Again, if you are using the web started packages, this is already handled.
13
+
For default module dependencies, you need to merge the ConfigProvider class output to your config. Again, if you are using the web starter packages(frontend, admin etc.), this is already handled.
12
14
13
-
By doing this, you "enable" the module to be available functionally for your project
15
+
By doing this, you "enable" the module to be available functionally for your project.
14
16
15
17
## Usage
16
18
17
19
Middleware controllers act as a handler for multiple routes. Some conventions were made:
18
-
- register controllers in the routes array just like any expressive middleware. The requirement is you should define an `action` route parameter(possibly optional) anywhere inside the route(e.g `/user[/{action}]`)
20
+
- register controllers in the routes array just like any expressive middleware. The requirement is that you should define an `action` route parameter(possibly optional) anywhere inside the route(e.g `/user[/{action}]`)
19
21
- action parameter value is converted to a method name inside the controller. Underscore, dot and line characters are removed and the action name is converted to camel-case suffixed by the string `Action`. For example a route and action pair like `/user/forgot-password` will be converted to method `forgotPasswordAction` inside a `UserController` class(as defined in routes config)
20
22
- the default action value, if not present in the URI is `index`, so you should always define an `indexAction` within your controllers for displaying a default page or redirecting.
21
23
22
24
In order to create your action based controllers, you must extend the abstract class `DotKernel\DotController\AbstractActionController`
23
25
24
26
##### Example 1
25
27
Creating a UserController with default action and a register action. Will handle routes `/user` and `/user/register`
28
+
26
29
##### UserController.php
27
30
```php
28
31
@@ -66,7 +69,7 @@ Then register this controller in the `routes` config(we assume you use FastRoute
66
69
67
70
Use case: You have defined a controller inside some package, with default actions. You want to add actions that fall into the same controller name(or route name more exactly). You want to do this without extending the controller provided by the package. In this case you can do the following
68
71
- create your own controller, independent of the package's controller which adds or overwrites actions
69
-
- ZE lets you define an array o middleware for a route, so you can register this controller before the package's controller
72
+
- ZE lets you define an array of middleware for a route, so you can register this controller before the package's controller
70
73
71
74
##### Example
72
75
```php
@@ -79,19 +82,20 @@ Use case: You have defined a controller inside some package, with default action
79
82
]
80
83
```
81
84
82
-
Now when a request for this route comes in, your controller will run first. Controllers are designed to ignore requests that cannot be matched to one of its methods, so if no action matches, it will call the next middleware, in our case, the second controller. If this is the last controller, and action does not match here, it will go to the default 404 Not found page. There is a simple middleware defined in dk-base that makes sure any request that does not match will be converted explicitly to a 404 error.
85
+
Now when a request for this route comes in, your controller will run first. Dot Controllers are designed to ignore requests that cannot be matched to one of its methods, so if no action matches, it will call the next middleware, in our case, the second controller.
86
+
If this is the last controller, and action does not match here, it will go to the default 404 Not found page. There is a simple middleware defined in dk-base that makes sure any request that does not match will be converted explicitly to a 404 error.
83
87
84
88
## Controller plugins
85
89
86
90
Controllers support controller plugins, much like controllers in a ZF3 application. The module comes packed with a few common plugins, but you can extend controller functionality with your own plugins too.
87
91
88
92
### Usage
89
93
90
-
Controller plugins must implement `DotKernel\DotController\Plugin\PluginInterface`. You can add them to the cconfig file, at key `['dk_controller']['plugin_manager']`. The design pattern uses the AbstractPluginManager provided by ZF3 service manager component. So, registration of a plugin under the aformentioned config key looks the same as the declaration of regular dependencies, as AbstractPluginManager actually extends ServiceManager.
94
+
Controller plugins must implement `DotKernel\DotController\Plugin\PluginInterface`. You can add them to the config file, at key `['dk_controller']['plugin_manager']`. The design pattern uses the `AbstractPluginManager` provided by ZF3 service manager component. So, registration of a plugin under the aforementioned config key looks the same as the declaration of regular dependencies, as `AbstractPluginManager` actually extends `ServiceManager`.
91
95
92
96
Once registered, a plugin can be directly accessed in any controller, by calling a method with the plugin's name(the service name or the key at which the plugin is registered inside the manager)
93
97
94
-
Controller plugins offer the advantage of globally accessible functionality in any controller without to manually inject dependencies. Plugins should be used for functions that are common to any controller. Do not clutter controller's code with unecessary plugins.
98
+
Controller plugins offer the advantage of globally accessible functionality in any controller without to manually inject dependencies. Plugins should be used for functions that are common to any controller. Do not clutter controller's code with unnecessary plugins.
95
99
96
100
##### Example
97
101
```php
@@ -101,12 +105,13 @@ $this->testPlugin(); //will return the TestPlugin class so you can call any publ
101
105
$this->testPlugin()->someMethod();
102
106
```
103
107
104
-
### Already provided plugins
105
-
Note: Each of these plugins requires the associated DK3 or ZE packages to be installed and available in your project.
106
-
Although these are optional, if a package is missing, the controller will not have the associated funcionality available
108
+
### Built-in plugins
109
+
Note: Each of these plugins requires the associated ZE packages to be installed and available in your project.
110
+
Although these are optional, if a package is missing, the controller will not have the associated functionality available
107
111
108
-
-`authentication` which wraps a AuthenticationInterface and defines methods `hadIdentity()` and `getIentity()`
109
-
-`authorization` which wraps an AuthorizationInterface and defines method `isGranted($permission, array $roles = [], $context = null)`
110
-
-`flashMessenger` wraps FlashMessenger for one time session based messages support
111
112
-`template` wraps TemplateInterface provided by ZE, to make template engine accessible to any controller
112
113
-`urlHelper` wraps the UrlHelper class provided by ZE helpers package. Used to generate URIs from routes
0 commit comments