Skip to content

Commit ba955fe

Browse files
committed
Added documentation for v3
1 parent f098d9c commit ba955fe

14 files changed

Lines changed: 382 additions & 175 deletions

File tree

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
name: "Continuous Integration"
2+
3+
on:
4+
pull_request:
5+
push:
6+
branches:
7+
tags:
8+
9+
jobs:
10+
ci:
11+
uses: laminas/workflow-continuous-integration/.github/workflows/continuous-integration.yml@1.x

.github/workflows/cs-tests.yml

Lines changed: 0 additions & 47 deletions
This file was deleted.

.github/workflows/docs-build.yml

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
name: docs-build
2+
3+
on:
4+
release:
5+
types: [published]
6+
workflow_dispatch:
7+
8+
jobs:
9+
build-deploy:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- name: Build Docs
13+
uses: dotkernel/documentation-theme/github-actions/docs@main
14+
env:
15+
DEPLOY_TOKEN: ${{ secrets.GITHUB_TOKEN }}
16+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/static-analysis.yml

Lines changed: 0 additions & 47 deletions
This file was deleted.

.github/workflows/unit-test.yml

Lines changed: 0 additions & 48 deletions
This file was deleted.

README.md

Lines changed: 16 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
# dot-controller
22

3-
This package contains controller like middleware to be used inside a DotKernel or Mezzio application. It provides base classes for action based controllers similar to Laminas controller component. It is more lightweight though, but supports controller plugins.
3+
This is DotKernel's controller package that can be use like middleware inside DotKernel or Mezzio application.
4+
It provides base classes for action based controllers similar to Laminas controller component. It is more lightweight though, but supports controller plugins and event listeners
45

56
![OSS Lifecycle](https://img.shields.io/osslifecycle/dotkernel/dot-controller)
67
![PHP from Packagist (specify version)](https://img.shields.io/packagist/php-v/dotkernel/dot-controller/3.4.3)
@@ -17,11 +18,10 @@ This package contains controller like middleware to be used inside a DotKernel o
1718

1819
## Installation
1920

20-
Run the following composer command in your project directory
21-
```bash
21+
Install `dot-controller` by executing the following Composer command:
22+
```bash
2223
$ composer require dotkernel/dot-controller
2324
```
24-
Merge the `ConfigProvider` to your configuration aggregate.
2525

2626
## Usage
2727

@@ -32,7 +32,7 @@ Middleware controllers act as a handler for multiple routes. Some conventions we
3232

3333
In order to create your action based controllers, you must extend the abstract class `DotKernel\DotController\AbstractActionController`
3434

35-
##### Example 1
35+
##### Example
3636
Creating a UserController with default action and a register action. Will handle routes `/user` and `/user/register`
3737

3838
##### UserController.php
@@ -56,38 +56,21 @@ class UserController extends AbstractActionController
5656

5757
Then register this controller as a routed middleware in file `RoutesDelegator.php` just like a regular middleware.
5858

59+
```php
60+
//Example from a DotKernel RoutesDelegator
61+
$app->route(
62+
'/user[/{action}]',
63+
UserController::class,
64+
[RequestMethodInterface::METHOD_GET, RequestMethodInterface::METHOD_POST],
65+
'user'
66+
);
67+
```
68+
5969
### Multiple controllers for the same route
6070

6171
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
6272
- create your own controller, independent of the package's controller which adds more actions
6373
- Mezzio lets you define an array of middleware for a route, so you can register this controller before the package's controller
6474

65-
Now when a request for this route comes in, your controller will run first. DotKernel 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.
75+
Now when a request for this route comes in, your controller will run first. DotKernel 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.
6676
If this is the last controller, and action does not match here, it will go to the default 404 Not found page(handled by NotFoundDelegate)
67-
68-
## Controller plugins
69-
70-
Controllers support controller plugins, much like controllers in a Laminas application. The module comes packed with a few common plugins, but you can extend controller functionality with your own plugins too.
71-
72-
### Usage
73-
74-
Controller plugins must implement `Dot\Controller\Plugin\PluginInterface`. You can add them to the config file, at key `['dk_controller']['plugin_manager']`. The design pattern uses the `AbstractPluginManager` provided by Laminas 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`.
75-
76-
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)
77-
78-
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.
79-
80-
##### Example
81-
```php
82-
//inside a controller
83-
//assume we've already registered a plugin called testPlugin
84-
$this->testPlugin(); //will return the TestPlugin class so you can call any public defined method on it
85-
$this->testPlugin()->someMethod();
86-
```
87-
88-
### Built-in plugins
89-
Note: Each of these plugins requires the associated Mezzio packages to be installed and available in your project.
90-
Although these are optional, if a package is missing, the controller will not have the associated functionality available
91-
92-
- `template` wraps TemplateInterface provided by Mezzio, to make template engine accessible to any controller
93-
- `url` wraps the UrlHelper class provided by Laminas helpers package. Used to generate URIs from routes

docs/book/index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../README.md

docs/book/v3/configuration.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Configuration
2+
3+
After installation, the package can be used immediately but if you want to use all features of the package, like plugins and events you need to register the `ConfigProvider` in your project by adding the below line to your configuration aggregator (usually: `config/config.php`):
4+
5+
\Dot\Controller\ConfigProvider::class

0 commit comments

Comments
 (0)