Comment on page
Controllers
In HivePress, controllers are PHP classes that are used to define URL routes and implement actions corresponding to them. For example, the
Listing
controller contains all the routes and actions related to listings (e.g. viewing, creating, updating and deleting).If you are developing a HivePress extension that requires custom URL routes, you should create a new controller. To do this, create a new
class-{extension-name}.php
file (use lowercase letters, numbers, and hyphens only) in the includes/controllers
extension subdirectory and HivePress will load it automatically.Then, define the controller PHP class. The class name should be based on the file name but with underscores instead of hyphens and no lowercase restriction (e.g.
Foo_Bar
class for the class-foo-bar.php
file). Pick a name that is unique enough to avoid conflicts with other HivePress controllers.<?php
namespace HivePress\Controllers;
use HivePress\Helpers as hp;
// Exit if accessed directly.
defined( 'ABSPATH' ) || exit;
final class Foo_Bar extends Controller {
public function __construct( $args = [] ) {
$args = hp\merge_arrays(
[
'routes' => [
// Define custom URL routes here.
],
],
$args
);
parent::__construct( $args );
}
// Implement the route actions here.
}
Each URL route is defined as an array of parameters in the controller's class constructor and can have the redirect and action functions implemented as the class methods.
If you add new or change any of the existing URL routes, don't forget to refresh permalinks in the Settings > Permalinks section.
Once you add a custom route, you can get its URL anywhere by the route name:
$url = hivepress()->router->get_url( 'my_custom_route' );
These routes are used for redirecting and rendering the page templates. For example, when you visit the listing edit page, the
listing_edit_page
route checks if you have permission to edit this listing (or redirects you otherwise) and then renders the page template.To define a new URL route, add an array of the following parameters:
- path - the relative route URL path (starts with a slash);
- base - the route name to inherit the
path
from; - redirect - points to the route redirect function;
- action - points to the route action function.
The code below defines a route with the
/custom-route
URL that checks if the current user is logged in and, if so, redirects to the account page. If not, it renders the login page template.'custom_route' => [
'title' => 'Custom Title',
'path' => '/custom-route',
'redirect' => [ $this, 'custom_redirect' ],
'action' => [ $this, 'custom_action' ],
],
The redirect and action functions can be implemented below the class constructor:
public function custom_redirect() {
// Perform checks and return the redirect URL.
if ( is_user_logged_in() ) {
return hivepress()->router->get_url( 'user_account_page' );
}
// Return false to prevent the redirect.
return false;
}
public function custom_action() {
// Return the rendered page template.
return ( new HivePress\Blocks\Template(
[
'template' => 'user_login_page',
]
) )->render();
}
In the same way, you can add URL routes for any pages required for your extension.
These routes are used for receiving HTTP requests, performing specific actions and returning a JSON response. For example, when you edit a listing, the form sends a request to the
listing_update_action
route, updating the listing based on the field values.To define a new REST API route, add an array with the following parameters:
- path - the relative route URL path (starts with a slash);
- base - the route name to inherit the
path
from; - method - the accepted HTTP method (e.g.
GET
,POST
); - action - points to the route action function;
- rest - flag required for REST API routes.
The code below defines a REST API route with the
/wp-json/hivepress/v1/custom-route
URL, accepts requests via the POST
method and calls the custom_action
function.'custom_route' => [
'path' => '/custom-route',
'method' => 'POST',
'action' => [ $this, 'custom_action' ],
'rest' => true,
],
The action function can be implemented below the class constructor:
public function custom_action( $request ) {
// Perform some actions based on the request.
if ( ! $request->get_param( 'custom_parameter' ) ) {
// Return the error code and message.
return hp\rest_error( 400, 'Custom error message' );
}
// Return the response code and data.
return hp\rest_response(
200,
[
'custom_result' => 123,
]
);
}
Similarly, you can add REST API routes for any actions required for your extension.
You can customize any of the available URL routes via the
hivepress/v1/routes
filter hook. For example, the code below changes the Add Listing page URL:add_filter(
'hivepress/v1/routes',
function( $routes ) {
$routes['listing_submit_page']['path'] = '/custom-slug-here';
return $routes;
}
);
Last modified 1yr ago