Routes

Each request is mapped to a Page, API or Controller Handler based on the URL.

Page Routes #

The diagram below shows a URL for a Page Handler.

The router will look for a file at /pages/issue/index.php or /lib/pkp/pages/issue/index.php, which loads the correct handler.

switch ($op) {
	case 'view':
		define('HANDLER_CLASS', 'IssueHandler');
		import('pages.issue.IssueHandler');
		break;
}

All ops for a page are usually managed by the same Handler. However, it is possible to direct each op to a different handler.

switch ($op) {
	case 'view':
		define('HANDLER_CLASS', 'IssueHandler');
		import('pages.issue.IssueHandler');
		break;
	case 'archive':
		define('HANDLER_CLASS', 'ArchiveHandler');
		import('pages.issue.ArchiveHandler');
		break;
}

This is not possible for API or Controller routes.

API Routes #

The diagram below shows a URL for an API Handler.

The router will look for a file at /api/v1/submissions/index.php, which loads the correct handler.

return new \APP\API\v1\submissions\SubmissionHandler();

The router will not find a file at /lib/pkp/api/v1/submissions/index.php.

Controller Routes #

The diagram below shows a URL for a Controller Handler.

The router will look for and load a Handler at /controllers/grid/issues/BackIssueGridHandler.php.

Controller URLs are derived from the Handler class name. The Handler suffix is dropped and the remaining name is transformed from PascalCase to kebab-case.

Writing URLs

Never manually write a URL path because the application can be run without the URL routing enabled. When the config option disable_path_info is turned on, URL routing will use query parameters.

http://example.org/?journal=publicknowledge&page=issue&op=view&path[]=1

URLs should always be generated by the Router’s url method. You can retrieve the appropriate Router from the Request object.

$url = $request->getRouter()->url($request, null, 'issue', 'view', 1);

The Request object will be available from the Handler. See Handlers.

The Request object will always return a Router type which matches the current route and generates URLs for that type. In a Page Handler it will return a PageRouter.

$pageUrl = $request->getRouter()->url($request, null, 'issue', 'view', 1);

In an API Handler it will return an APIRouter.

$apiUrl = $request->getRouter()->url($request, null, 'issues/1');

In a Controller Handler it will return a PKPComponentRouter.

$controllerUrl = $request->getRouter()->url($request, null, 'grid.issues.IssueGridHandler', 'editIssue', [1]);

If you need to get a URL for a different router, use the Dispatcher.

$pageUrl = $request->getDispatcher()->url($request, ROUTE_PAGE, 'issue', 'view', 1);
$apiUrl = $request->getDispatcher()->url($request, ROUTE_API, $context->getPath(), 'issues/1');
$controllerUrl = $request->getDispatcher()->url($request, ROUTE_COMPONENT, null, 'grid.issues.IssueGridHandler', 'editIssue', [1]);

Learn about how Handlers respond to the request.