dokan-backend-dev

Dokan Backend Development

This skill provides guidance for developing Dokan Lite backend PHP code according to project standards.

When to Use This Skill

Invoke this skill before:

• Writing new PHP unit tests
• Creating new PHP classes or services
• Modifying existing backend PHP code
• Adding hooks, filters, or REST endpoints

Namespace & File Structure

• Root namespace: WeDevs\Dokan\
• PSR-4 autoloading: WeDevs\Dokan\ maps to includes/
• File path follows namespace: WeDevs\Dokan\Order\Manager → includes/Order/Manager.php
• Third-party (Mozart): WeDevs\Dokan\ThirdParty\Packages\ → lib/packages/

Class Conventions

Method & Property Naming

• Methods: snake_case (WordPress convention) — e.g., register_routes(), get_stores()
• Properties: typed (PHP 7.4+) — e.g., protected bool $should_adjust_refund = true;
• Constants: UPPER_SNAKE_CASE

Manager Pattern

Most subsystems use a Manager class as the primary facade:

namespace WeDevs\Dokan\Order;

class Manager {
    public function all( $args = [] ) { ... }
    public function get( $id ) { ... }
    public function create( $args ) { ... }
}

Access via: dokan()->order->all()

Hookable Interface

Classes that register WordPress hooks should implement Hookable:

namespace WeDevs\Dokan\Product;

use WeDevs\Dokan\Contracts\Hookable;

class Hooks implements Hookable {
    public function register_hooks(): void {
        add_action( 'save_post_product', [ $this, 'handle_product_save' ], 10, 2 );
        add_filter( 'dokan_product_listing_args', [ $this, 'filter_listing_args' ] );
    }
}

Classes implementing Hookable are auto-registered in CommonServiceProvider — their hooks load automatically.

Dependency Injection

Uses League Container v4 (namespaced under WeDevs\Dokan\ThirdParty\Packages\League\Container).

Registering Services

Add to the appropriate ServiceProvider in includes/DependencyManagement/Providers/:

// In ServiceProvider.php (main) for core services:
protected $services = [
    'my_service' => \WeDevs\Dokan\MyDomain\Manager::class,
];

// In CommonServiceProvider.php for Hookable classes:
protected $services = [
    \WeDevs\Dokan\MyDomain\Hooks::class,
];

Accessing Services

// Via magic getter (most common)
dokan()->order->get( $order_id );
dokan()->vendor->get( $vendor_id );

// Via container directly
dokan()->get_container()->get( 'order' );

Base Service Provider Helper

Use share_with_implements_tags() to auto-tag services by their interfaces:

$this->share_with_implements_tags( MyService::class );

REST API Controllers

Controller Hierarchy

WP_REST_Controller (WordPress core)
└── DokanBaseController (dokan/v1)
    ├── DokanBaseAdminController (dokan/v1/admin) — admin-only endpoints
    ├── DokanBaseVendorController (dokan/v1) — vendor endpoints (uses VendorAuthorizable trait)
    └── DokanBaseCustomerController (dokan/v1) — customer endpoints

Choose the appropriate base class:

• DokanBaseAdminController — For admin-only endpoints (dokan/v1/admin/*). Has built-in check_permission() checking manage_woocommerce capability.
• DokanBaseVendorController — For vendor endpoints. Includes VendorAuthorizable trait for store access checks.
• DokanBaseController — For general endpoints that don't fit the above.

Note: Some older controllers extend WP_REST_Controller directly (e.g., StoreController, WithdrawController). New controllers should extend one of the Dokan base classes.

Full Controller Example

namespace WeDevs\Dokan\REST;

use WP_Error;
use WP_REST_Request;
use WP_REST_Response;
use WP_REST_Server;
use WeDevs\Dokan\Traits\RESTResponseError;

class MyResourceController extends DokanBaseAdminController {

    use RESTResponseError;

    /**
     * Route base.
     *
     * @var string
     */
    protected $rest_base = 'my-resource';

    /**
     * Register routes.
     *
     * @return void
     */
    public function register_routes() {
        register_rest_route(
            $this->namespace, '/' . $this->rest_base, [
                [
                    'methods'             => WP_REST_Server::READABLE,
                    'callback'            => [ $this, 'get_items' ],
                    'args'                => array_merge(
                        $this->get_collection_params(),
                        [
                            'status' => [
                                'description' => __( 'Filter by status.', 'dokan-lite' ),
                                'type'        => 'string',
                                'enum'        => [ 'active', 'inactive' ],
                                'default'     => 'active',
                            ],
                        ]
                    ),
                    'permission_callback' => [ $this, 'check_permission' ],
                ],
                [
                    'methods'             => WP_REST_Server::CREATABLE,
                    'callback'            => [ $this, 'create_item' ],
                    'args'                => $this->get_endpoint_args_for_item_schema( WP_REST_Server::CREATABLE ),
                    'permission_callback' => [ $this, 'check_permission' ],
                ],
                'schema' => [ $this, 'get_item_schema' ],
            ]
        );

        register_rest_route(
            $this->namespace, '/' . $this->rest_base . '/(?P<id>[\d]+)', [
                'args' => [
                    'id' => [
                        'description' => __( 'Unique identifier for the object.', 'dokan-lite' ),
                        'type'        => 'integer',
                    ],
                ],
                [
                    'methods'             => WP_REST_Server::READABLE,
                    'callback'            => [ $this, 'get_item' ],
                    'permission_callback' => [ $this, 'check_permission' ],
                ],
                [
                    'methods'             => WP_REST_Server::EDITABLE,
                    'callback'            => [ $this, 'update_item' ],
                    'args'                => $this->get_endpoint_args_for_item_schema( WP_REST_Server::EDITABLE ),
                    'permission_callback' => [ $this, 'check_permission' ],
                ],
                [
                    'methods'             => WP_REST_Server::DELETABLE,
                    'callback'            => [ $this, 'delete_item' ],
                    'permission_callback' => [ $this, 'check_permission' ],
                ],
            ]
        );

        // Batch endpoint
        register_rest_route(
            $this->namespace, '/' . $this->rest_base . '/batch', [
                [
                    'methods'             => WP_REST_Server::EDITABLE,
                    'callback'            => [ $this, 'batch_items' ],
                    'permission_callback' => [ $this, 'check_permission' ],
                    'args'                => $this->get_public_batch_schema()['properties'],
                ],
                'schema' => [ $this, 'get_public_batch_schema' ],
            ]
        );
    }
}

Prepare Item for Response

Every controller must implement prepare_item_for_response(). This method transforms the internal data model into the REST API response shape, adds HATEOAS links, and applies an extensibility filter:

/**
 * Prepare a single item for response.
 *
 * @param MyModel         $item    Data object.
 * @param WP_REST_Request $request Request object.
 *
 * @return WP_REST_Response
 */
public function prepare_item_for_response( $item, $request ) {
    $data = [
        'id'          => absint( $item->get_id() ),
        'title'       => $item->get_title(),
        'status'      => $item->get_status(),
        'amount'      => floatval( $item->get_amount() ),
        'created'     => mysql_to_rfc3339( $item->get_date() ),
    ];

    $data = apply_filters( 'dokan_rest_prepare_my_resource_data', $data, $item, $request );

    $response = rest_ensure_response( $data );
    $response->add_links( $this->prepare_links( $item, $request ) );

    return apply_filters( 'dokan_rest_prepare_my_resource_object', $response, $item, $request );
}

Prepare Links (HATEOAS)

Provide self and collection links for discoverability:

/**
 * Prepare links for the request.
 *
 * @param MyModel         $item    Object data.
 * @param WP_REST_Request $request Request object.
 *
 * @return array Links for the given item.
 */
protected function prepare_links( $item, $request ) {
    return [
        'self'       => [
            'href' => rest_url( sprintf( '/%s/%s/%d', $this->namespace, $this->rest_base, $item->get_id() ) ),
        ],
        'collection' => [
            'href' => rest_url( sprintf( '/%s/%s', $this->namespace, $this->rest_base ) ),
        ],
    ];
}

Collection Response with Pagination

Use format_collection_response() (inherited from DokanBaseController) to add pagination headers:

public function get_items( $request ) {
    $args = [
        'number' => (int) $request['per_page'],
        'offset' => (int) ( $request['page'] - 1 ) * $request['per_page'],
    ];

    $items       = $this->get_my_items( $args );
    $total_items = $this->get_my_items_count( $args );

    $data = [];
    foreach ( $items as $item ) {
        $item_data = $this->prepare_item_for_response( $item, $request );
        $data[]    = $this->prepare_response_for_collection( $item_data );
    }

    $response = rest_ensure_response( $data );
    $response = $this->format_collection_response( $response, $request, $total_items );

    return $response;
}

format_collection_response() sets these headers automatically:

• X-WP-Total — Total item count
• X-WP-TotalPages — Total page count
• `Link: <url>; rel="pr

Content truncated.