api.md

Dokan REST Controllers Documentation

Table of Contents

• Introduction
• Creating a REST Controller
  • Extending a Dokan Base Controller
  • Extending Other Controllers
• VendorAuthorizable Trait
• Example Implementations
  • Admin Controller Example
  • Vendor Controller Example

Introduction

Dokan REST Controllers provide a structured approach to managing REST API endpoints with role-based permissions. The hierarchy consists of a base controller, DokanBaseController, and role-specific controllers:

• DokanBaseAdminController
• DokanBaseVendorController
• DokanBaseCustomerController

These controllers extend the core WP_REST_Controller and provide predefined functionalities for different user roles.

Creating a REST Controller

To create a new REST controller, extend one of the Dokan base controllers.

Extending a Dokan Base Controller

When extending a Dokan base controller, ensure you override the prepare_item_for_response method and implement required route registrations.

Required Method Implementation

/**
 * Prepares the item for the REST response.
 *
 * @since DOKAN_SINCE
 *
 * @param mixed           $item    WordPress representation of the item.
 * @param WP_REST_Request $request Request object.
 * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
 */
public function prepare_item_for_response( $item, $request ) {
    return new WP_Error(
        'invalid-method',
        sprintf( __( "Method '%s' not implemented. Must be overridden in subclass." ), __METHOD__ ),
        array( 'status' => 405 )
    );
}

Extending Other Controllers

Dokan provides the VendorAuthorizable trait, which can be used to check vendor capabilities in custom controllers that do not directly extend a Dokan base controller.

VendorAuthorizable Trait

The VendorAuthorizable trait provides a way to check vendor permissions in REST controllers. It ensures that only authorized vendors can access or modify specific resources.

Usage

To use the VendorAuthorizable trait, simply include it in your controller class:

use WeDevs\Dokan\Traits\VendorAuthorizable;

class VendorProductController extends \WC_REST_Products_Controller {
    use VendorAuthorizable;
}

This trait provides a check_permission method, which can be used to verify if a user has the vendor(dokandar) capabilities to perform a given action.

Example Implementations

Admin Controller Example

use WeDevs\Dokan\REST\DokanBaseAdminController;

class ExampleAdminController extends DokanBaseAdminController {
    protected $namespace = 'dokan/v1'; // default namespace is 'dokan/v1/admin' in `DokanBaseAdminController`
    protected $rest_base = 'example-admin';

    public function register_routes() {
        register_rest_route(
            $this->namespace,
            '/' . $this->rest_base,
            [
                [
                    'methods'             => WP_REST_Server::READABLE,
                    'callback'            => [ $this, 'get_items' ],
                    'permission_callback' => [ $this, 'check_permission' ],
                    'args'                => $this->get_collection_params(),
                ]
            ]
        );
    }

    /**
     * Retrieve a single customer.
     *
     * @param WP_REST_Request $request Request details.
     * @return WP_Error|WP_REST_Response
     */
    public function get_item( $request ) {
        $id        = (int) $request['id'];
        $user_data = get_userdata( $id );

        if ( empty( $id ) || empty( $user_data->ID ) ) {
            return new WP_Error( 'woocommerce_rest_invalid_id', __( 'Invalid resource ID.', 'woocommerce' ), [ 'status' => 404 ] );
        }

        $customer = $this->prepare_item_for_response( $user_data, $request );
        return rest_ensure_response( $customer );
    }

    /**
     * Formats a single customer for response output.
     *
     * @param WP_User         $user_data User object.
     * @param WP_REST_Request $request   Request object.
     * @return WP_REST_Response Response data.
     */
    public function prepare_item_for_response( $user_data, $request ) {
        // TODO: Implement API response formatting
        return apply_filters( 'dokan_rest_prepare_admin', $response, $user_data, $request );
    }
}

This structure ensures that all controllers follow a standardized format while allowing flexibility and extendability.