enhance: Seperate dokan rest controller for role-wise API implementation.

docs/api/api.md

@@ -0,0 +1,272 @@
+# Dokan REST Controllers Documentation
+
+- [Introduction](#introduction)
+- [Base REST Controller](#base-rest-controller)
+- [1. Role-Specific Controllers.](#1-role-specifix-controllers)
+    - [Admin REST Controller.](#admin-rest-controller)
+    - [Vendor REST Controller.](#vendor-rest-controller)
+    - [Customer REST Controller.](#customer-rest-controller)
+
+## Introduction
+The Dokan REST Controllers provide a structured approach to handle REST API endpoints with role-based permissions. The hierarchy consists of a base controller (DokanBaseRESTController) and role-specific controllers (`DokanRESTAdminController`, `DokanRESTVendorController`, `DokanRESTCustomerController`).
+
+## Base REST Controller
+The `DokanBaseRESTController` extends WordPress's `WP_REST_Controller` and provides common functionality for all Dokan REST endpoints.
+
+### Base Controller Implementation
+```php
+abstract class DokanBaseRESTController extends WP_REST_Controller {
+    protected $namespace = 'dokan/v1';
+
+    public function format_collection_response( $response, $request, $total_items ) {
+        // Handles pagination and response formatting
+    }
+}
+```
+
+## Role-Specific Controllers
+
+### Admin REST Controller Implementation
+
+```php
+abstract class DokanRESTAdminController extends DokanBaseRESTController {
+    protected $namespace = 'dokan/v1/admin';
+
+    public function check_permission() {
+        return current_user_can( 'manage_woocommerce' );
+    }
+}
+```
+
+### How to extend the Admin REST Controller
+
+```php
+class ExampleAdminController extends DokanRESTAdminController {
+    protected $namespace = 'dokan/v1';
+    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(),
+                ]
+            ]
+        );
+    }
+
+    public function get_items( $request ) {
+        $items = []; // Your implementation
+        $total = count( $items );
+
+        $response = rest_ensure_response( $items );
+        return $this->format_collection_response( $response, $request, $total );
+    }
+}
+```
+
+### Override Admin REST Controller permission
+
+```php
+class ExampleAdminController extends DokanRESTAdminController {
+    protected $namespace = 'dokan/v1';
+    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(),
+                ]
+            ]
+        );
+    }
+
+    public function check_permission() {
+        // Custom permission check for multiple roles
+        return current_user_can( 'dokandar' ) || current_user_can( 'manage_woocommerce' );
+    }
+
+    public function get_items( $request ) {
+        $items = []; // Your implementation
+        $total = count( $items );
+
+        $response = rest_ensure_response( $items );
+        return $this->format_collection_response( $response, $request, $total );
+    }
+}
+```
+
+### Vendor REST Controller Implementation
+
+```php
+abstract class DokanRESTVendorController extends DokanBaseRESTController {
+    protected $namespace = 'dokan/v1';
+    protected $rest_base = 'vendor';
+
+    public function check_permission() {
+        return current_user_can( 'dokandar' );
+    }
+}
+```
+
+### How to extend the Vendor REST Controller
+
+```php
+class ExampleVendorController extends DokanRESTVendorController {
+    protected $namespace = 'dokan/v1';
+    protected $rest_base = 'example-vendor';
+
+    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(),
+                ]
+            ]
+        );
+    }
+
+    public function get_items( $request ) {
+        $items = []; // Your implementation
+        $total = count( $items );
+
+        $response = rest_ensure_response( $items );
+        return $this->format_collection_response( $response, $request, $total );
+    }
+}
+```
+
+### Override Vendor REST Controller permission
+
+```php
+class ExampleVendorController extends DokanRESTVendorController {
+    protected $namespace = 'dokan/v1';
+    protected $rest_base = 'example-vendor';
+
+    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(),
+                ]
+            ]
+        );
+    }
+
+    public function check_permission() {
+        // Custom permission check.
+        return current_user_can( 'dokandar' ) || is_user_logged_in();
+    }
+
+    public function get_items( $request ) {
+        $items = []; // Your implementation
+        $total = count( $items );
+
+        $response = rest_ensure_response( $items );
+        return $this->format_collection_response( $response, $request, $total );
+    }
+}
+```
+
+### Customer REST Controller Implementation
+
+```php
+abstract class DokanRESTCustomerController extends DokanBaseRESTController {
+    protected $namespace = 'dokan/v1';
+    protected $rest_base = 'customer';
+
+    public function check_permission() {
+        return is_user_logged_in();
+    }
+}
+```
+
+### How to extend the Customer REST Controller
+
+```php
+class ExampleCustomerController extends DokanRESTCustomerController {
+    protected $namespace = 'dokan/v1';
+    protected $rest_base = 'example-customer';
+
+    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(),
+                ]
+            ]
+        );
+    }
+
+    public function get_items( $request ) {
+        $items = []; // Your implementation
+        $total = count( $items );
+
+        $response = rest_ensure_response( $items );
+        return $this->format_collection_response( $response, $request, $total );
+    }
+}
+```
+
+### Override Customer REST Controller permission
+
+```php
+class ExampleCustomerController extends DokanRESTCustomerController {
+    protected $namespace = 'dokan/v1';
+    protected $rest_base = 'example-customer';
+
+    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(),
+                ]
+            ]
+        );
+    }
+
+    public function check_permission() {
+        // Custom permission check.
+        return is_user_logged_in() || dokan_is_seller_enabled( get_current_user_id() );;
+    }
+
+    public function get_items( $request ) {
+        $items = []; // Your implementation
+        $total = count( $items );
+
+        $response = rest_ensure_response( $items );
+        return $this->format_collection_response( $response, $request, $total );
+    }
+}
+```

includes/Abstracts/DokanBaseRESTController.php

@@ -0,0 +1,67 @@
+<?php
+
+namespace WeDevs\Dokan\Abstracts;
+
+use WP_REST_Controller;
+
+/**
+ * Base REST Controller for Dokan
+ *
+ * @since DOKAN_PRO_SINCE
+ *
+ * @package dokan
+ */
+abstract class DokanBaseRESTController extends WP_REST_Controller {
+
+    /**
+     * Endpoint namespace
+     *
+     * @var string
+     */
+    protected $namespace = 'dokan/v1';
+
+    /**
+     * Format item's collection for response
+     *
+     * @since DOKAN_PRO_SINCE
+     *
+     * @param object $response
+     * @param object $request
+     * @param array  $items
+     * @param int    $total_items
+     *
+     * @return object
+     */
+    public function format_collection_response( $response, $request, $total_items ) {
+        if ( $total_items === 0 ) {
+            return $response;
+        }
+
+        // Pagination values for headers.
+        $per_page = (int) ( ! empty( $request['per_page'] ) ? $request['per_page'] : 20 );
+        $page     = (int) ( ! empty( $request['page'] ) ? $request['page'] : 1 );
+
+        $response->header( 'X-WP-Total', (int) $total_items );
+
+        $max_pages = ceil( $total_items / $per_page );
+
+        $response->header( 'X-WP-TotalPages', (int) $max_pages );
+        $base = add_query_arg( $request->get_query_params(), rest_url( sprintf( '/%s/%s', $this->namespace, $this->base ) ) );
+
+        if ( $page > 1 ) {
+            $prev_page = $page - 1;
+            if ( $prev_page > $max_pages ) {
+                $prev_page = $max_pages;
+            }
+            $prev_link = add_query_arg( 'page', $prev_page, $base );
+            $response->link_header( 'prev', $prev_link );
+        }
+        if ( $max_pages > $page ) {
+            $next_page = $page + 1;
+            $next_link = add_query_arg( 'page', $next_page, $base );
+            $response->link_header( 'next', $next_link );
+        }
+
+        return $response;
+    }
+}