feat: Dokan Data Store

docs/data-store.md

@@ -0,0 +1,184 @@
+## Dokan Model & Data Store Documentation
+
+- [Data Model](#data-model)
+- [Data Store](#data-store)
+- [Uses of Models](#uses-of-models)
+
+## Data Model
+
+### Overview
+The Dokan Data Model class should follow a structure similar to the `WC_Product` class, where the data layer is abstracted through the **Data Store**. This separation ensures that the model class is used throughout the Dokan plugin without interacting directly with the database or Data Store.
+
+### Goal
+The goal is to minimize the use of raw queries and enhance performance across various parts of the plugin. The data model should efficiently manage storing and retrieving data from the database.
+
+### Implementation
+The model class should extend the [\WeDevs\Dokan\Models\BaseModel](../includes/Models/BaseModel.php) class. It includes the following key properties and methods:
+
+#### Properties
+- `protected $object_type`: The type of object, such as `product`.
+- `protected $data`: Holds the default data for the object.
+
+#### Methods
+- The `protected $data_store` property is initialized in the constructor.
+- Getter and Setter methods use the `get_{key}` and `set_{key}` conventions, leveraging the `get_prop( $prop_name, $context )` and `set_prop( $prop_name, $prop_value )` methods for interacting with data properties.
+
+Below is a sample class implementation:
+
+```php
+class Department extends \WeDevs\Dokan\Models\BaseModel {
+    protected $object_type = 'department';
+
+    protected $data = array(
+        'name' => '',
+        'date_created' => null,
+        'date_updated' => null,
+    );
+
+    /**
+     * Initialize the data store
+     */
+    public function __construct( int $item_id = 0 ) {
+        parent::__construct( $item_id );
+        $this->data_store = new \WeDevs\Dokan\Models\DataStore\DepartmentStore();
+
+        if ( $this->get_id() > 0 ) {
+            $this->data = $this->data_store->read( $this );
+        }
+    }
+
+    public function get_name( $context = 'view' ) {
+        return $this->get_prop('name', $context);
+    }
+
+    public function set_name( $name ) {
+        return $this->set_prop( 'name', $name );
+    }
+
+    /**
+     * @return \WC_DateTime|NULL Since the value was set by `set_date_prop` method
+     */
+    public function get_date_created( $context = 'view' ) {
+        return $this->get_prop('date_created', $context);
+    }
+
+    /**
+     * Set the date type value using the `set_date_prop` method.
+     */ 
+    public function set_date_created( $date_created ) {
+        return $this->set_date_prop( 'date_created', $date_created );
+    }
+
+    /**
+     * @return \WC_DateTime|NULL Since the value was set by `set_date_prop` method
+     */
+    public function get_date_updated( $context = 'view' ) {
+        return $this->get_prop('date_updated', $context);
+    }
+
+    public function set_date_updated( $date_updated ) {
+        return $this->set_date_prop( 'date_updated', $date_updated );
+    }
+
+    /**
+     * Set the updated date for the entity.
+     *
+     * This method is protected to ensure that only internal code like `set_props` method
+     * can set the updated date dynamically. External clients should use
+     * the `set_date_created` and `set_date_updated` methods to manage dates semantically.
+     *
+     * @param string|int|DateTime $date_created
+     */
+    protected function set_updated_at( $date_updated ) {
+        $this->set_date_updated( $date_updated );
+    }
+}
+```
+
+## Data Store
+
+- [Override DB Date Format](#override-db-date-format)
+- [Customizing the ID Field](#customizing-the-id-field)
+
+Your data store class should extend the [\WeDevs\Dokan\Models\DataStore\BaseDataStore](../includes/Models/DataStore/BaseDataStore.php) class and must implement the following methods:
+
+- `get_table_name`: Defines the table name in the database.
+- `get_fields_with_format`: Returns the fields with format as an array where key is the db field name and value is the format..
+
+Sample implementation:
+
+```php
+class DepartmentStore extends \WeDevs\Dokan\Models\DataStore\BaseDataStore {
+    public function get_table_name(): string {
+        return 'dokan_department';
+    }
+
+    public function get_fields_with_format(): array {
+        return [
+            'name' => '%s',
+            'date_created' => '%s',
+            'updated_at' => '%s',
+        ];
+    }
+
+    public function get_date_updated( $context = 'view' ) {
+        return $this->get_prop('date_updated', $context);
+    }
+}
+```
+
+### Override DB Date Format
+
+The Data Store first checks for the existence of the `get_{field_name}` method to map the data during insert or update operations. There are two ways to override the DB date format:
+
+**Option 1:**
+Override the `get_date_format_for_field` method to specify a custom format.
+```php
+protected function get_date_format_for_field( string $db_field_name ): string  {
+    return 'Y-m-d';
+}
+```
+
+**Option 2:**
+Create a custom method like `get_{db_field}` for more control over date formatting:
+```php
+protected function get_updated_at( Department $model, $context = 'edit' ): string {
+    return $model->get_date_updated( $context )->date('Y-m-d');
+}
+```
+> **Option 2** could be used to map the data during insert or update operations when Model's data key and Store's data key are different. 
+
+### Customizing the ID Field
+
+To customize the name and format of the ID field in the database, override the `get_id_field_name` and `get_id_field_format` methods. By default, the ID field is set to `id` and format is `%d`.
+
+## Uses of Models
+
+### Create a New Record
+```php
+$department = new Department();
+$department->set_name('Department 1');
+$department->save();
+```
+
+### Read a Record
+```php
+$department = new Department( $department_id );
+echo $department->get_name();
+```
+
+### Update a Record
+```php
+$department = new Department( $department_id );
+$department->set_name('Department 2');
+$department->save();
+```
+
+### Case Study
+Pls check the example [get_particulars](../includes/Models/VendorBalance.php#L16) & [set_perticulars](../includes/Models/VendorBalance.php#L146) methods of Model and  [get_perticulars](../includes/Models/DataStore/VendorBalanceStore.php#L35) method of Data Store.
+
+`perticulars` field name  in database is *typo* but I don't want to expose public method `get_perticulars` in Model class instead of `get_particulars`.
+
+We could do the same thing by overriding the following methods in Data Store.
+- `protected function map_model_to_db_data( BaseModel &$model ): array`: Prepare data for saving a BaseModel to the database.
+- `map_db_raw_to_model_data`: Maps database raw data to model data.

includes/Commission.php

@@ -4,7 +4,9 @@
 
 use WC_Order;
 use WC_Product;
+use WeDevs\Dokan\Models\VendorBalance;
 use WeDevs\Dokan\ProductCategory\Helper;
+use WeDevs\DokanPro\Modules\DeliveryTime\StorePickup\Vendor;
 use WP_Error;
 use WooCommerce\PayPalCommerce\WcGateway\Gateway\PayPalGateway;
 
@@ -97,15 +99,12 @@
                 [ '%d' ]
             );
 
-            $wpdb->update(
-                $wpdb->dokan_vendor_balance,
-                [ 'debit' => (float) $net_amount ],
-                [
-                    'trn_id'   => $tmp_order->get_id(),
-                    'trn_type' => 'dokan_orders',
-                ],
-                [ '%f' ],
-                [ '%d', '%s' ]
+            $vendor_balance_model = dokan()->get_container()->get( VendorBalance::class );
+
+            $vendor_balance_model->update_by_transaction(
+                $tmp_order->get_id(),
+                'dokan_orders',
+                [ 'debit' => (float) $net_amount ]
             );
 
             $tmp_order->update_meta_data( 'dokan_gateway_fee', $gateway_fee );
@@ -566,7 +565,7 @@
      *
      * @return float | null on failure
      */
     public function prepare_for_calculation( $callable, $product_id = 0, $product_price = 0 ) {
         do_action( 'dokan_before_prepare_for_calculation', $callable, $product_id, $product_price, $this );
 
         // If an order has been purchased previously, calculate the earning with the previously stated commission rate.

includes/DependencyManagement/Providers/ModelServiceProvider.php

@@ -0,0 +1,38 @@
+<?php
+
+namespace WeDevs\Dokan\DependencyManagement\Providers;
+
+use WeDevs\Dokan\DependencyManagement\BaseServiceProvider;
+
+class ModelServiceProvider extends BaseServiceProvider {
+    /**
+     * Tag for services added to the container.
+     */
+    public const TAG = 'ajax-service';
+
+	protected $services = [
+        \WeDevs\Dokan\Models\VendorBalance::class,
+        \WeDevs\Dokan\Models\DataStore\VendorBalanceStore::class,
+    ];
+
+	/**
+     * {@inheritDoc}
+     *
+     * Check if the service provider can provide the given service alias.
+     *
+     * @param string $alias The service alias to check.
+     * @return bool True if the service provider can provide the service, false otherwise.
+     */
+	public function provides( string $alias ): bool {
+		return in_array( $alias, $this->services, true );
+	}
+
+	/**
+     * Register the classes.
+     */
+	public function register(): void {
+        foreach ( $this->services as $service ) {
+            $this->getContainer()->add( $service, $service );
+        }
+    }
+}

includes/DependencyManagement/Providers/ServiceProvider.php

@@ -61,6 +61,7 @@ public function boot(): void {
 		$this->getContainer()->addServiceProvider( new FrontendServiceProvider() );
 		$this->getContainer()->addServiceProvider( new AjaxServiceProvider() );
 		$this->getContainer()->addServiceProvider( new AnalyticsServiceProvider() );
+		$this->getContainer()->addServiceProvider( new ModelServiceProvider() );
 	}
 
     /**

includes/Models/BaseModel.php

@@ -0,0 +1,104 @@
+<?php
+
+namespace WeDevs\Dokan\Models;
+
+use WC_Data;
+
+abstract class BaseModel extends WC_Data {
+	/**
+	 * Save should create or update based on object existence.
+	 *
+	 * @return int
+	 */
+	public function save() {
+		// wc_get_product()
+		if ( ! $this->data_store ) {
+			return $this->get_id();
+		}
+
+		/**
+		 * Trigger action before saving to the DB. Allows you to adjust object props before save.
+		 *
+		 * @param WC_Data          $this The object being saved.
+		 * @param WC_Data_Store_WP $data_store THe data store persisting the data.
+		 */
+		do_action( 'dokan_before_' . $this->object_type . '_object_save', $this, $this->data_store );
+
+		if ( $this->get_id() ) {
+			$this->data_store->update( $this );
+		} else {
+			$this->data_store->create( $this );
+		}
+
+		/**
+		 * Trigger action after saving to the DB.
+		 *
+		 * @param WC_Data          $this The object being saved.
+		 * @param WC_Data_Store_WP $data_store THe data store persisting the data.
+		 */
+		do_action( 'dokan_after_' . $this->object_type . '_object_save', $this, $this->data_store );
+
+		return $this->get_id();
+	}
+
+    /**
+	 * Delete an object, set the ID to 0, and return result.
+	 *
+	 * @param  bool $force_delete Should the date be deleted permanently.
+	 * @return bool result
+	 */
+	public function delete( $force_delete = false ) {
+		/**
+		 * Filters whether an object deletion should take place. Equivalent to `pre_delete_post`.
+		 *
+		 * @param mixed   $check Whether to go ahead with deletion.
+		 * @param Data $this The data object being deleted.
+		 * @param bool    $force_delete Whether to bypass the trash.
+		 *
+		 * @since 8.1.0.
+		 */
+		$check = apply_filters( "dokan_pre_delete_$this->object_type", null, $this, $force_delete );
+
+		if ( null !== $check ) {
+			return $check;
+		}
+
+		if ( $this->data_store ) {
+			$this->data_store->delete( $this, array( 'force_delete' => $force_delete ) );
+			$this->set_id( 0 );
+			return true;
+		}
+
+		return false;
+	}
+
+	/**
+	 * Delete raws from the database.
+	 *
+	 * @param array $data Array of args to delete an object, e.g. `array( 'id' => 1, status => ['draft', 'cancelled'] )` or `array( 'id' => 1, 'status' => 'publish' )`.
+	 * @return bool result
+	 */
+	public static function delete_by( array $data ) {
+		$object = new static();
+		return $object->data_store->delete_by( $data );
+	}
+
+	/**
+	 * Prefix for action and filter hooks on data.
+	 *
+	 * @return string
+	 */
+	protected function get_hook_prefix() {
+		return 'dokan_' . $this->object_type . '_get_';
+	}
+
+	/**
+	 * Get All Meta Data.
+	 *
+	 * @since 2.6.0
+	 * @return array of objects.
+	 */
+	public function get_meta_data() {
+		return apply_filters( $this->get_hook_prefix() . 'meta_data', array() );
+	}
+}