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).

Creating controllers

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.
}

Adding routes

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' );

Template routes

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:

• title - text used as the page title and menu label;
• 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.

REST API routes

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.

Customizing routes

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;
	}
);