PHPackages                             makiomar/woo-order-dashboard - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Admin Panels](/categories/admin)
4. /
5. makiomar/woo-order-dashboard

ActiveLibrary[Admin Panels](/categories/admin)

makiomar/woo-order-dashboard
============================

A Laravel package for displaying WooCommerce orders in your Laravel admin panel

0214PHP

Since Aug 4Pushed 9mo agoCompare

[ Source](https://github.com/MakiOmar/WooCommerce-by-Laravel)[ Packagist](https://packagist.org/packages/makiomar/woo-order-dashboard)[ RSS](/packages/makiomar-woo-order-dashboard/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependenciesVersions (3)Used By (0)

WooCommerce Order Dashboard for Laravel
=======================================

[](#woocommerce-order-dashboard-for-laravel)

A powerful Laravel package that provides a clean and efficient dashboard for managing WooCommerce orders. This package is designed to work seamlessly with your existing WooCommerce installation while providing enhanced performance and functionality.

⚠️ IMPORTANT: Required Database Configuration
---------------------------------------------

[](#️-important-required-database-configuration)

**Before using this package, you MUST configure the WooCommerce database connection in your Laravel application. This is a critical step that cannot be skipped.**

**If you encounter "Undefined array key driver" errors, it means you haven't properly configured the database connection.**

**See the [Database Connection Configuration](#-critical-database-connection-configuration) section below for detailed instructions.**

Features
--------

[](#features)

- 🚀 High-performance order management with Eloquent ORM
- 📊 Real-time order statistics and analytics
- 🔍 Advanced order filtering and search
- 🎯 Smart caching system with multiple driver support
- 🛠️ Comprehensive Eloquent models for WooCommerce data
- 📱 Responsive and modern UI
- 🔒 Safe integration with WooCommerce (no database modifications by default)
- 📦 Optional database optimizations for new installations
- 🛣️ Clean, unprefixed routing system
- ✨ Order creation and management interface
- 🔄 Bulk operations support
- 🌐 **WooCommerce REST API Integration**: Optional API-based order creation for better integration
- **Order Management**: View, create, and manage WooCommerce orders
- **Dynamic Status Management**: Automatically fetch order statuses from WooCommerce database
- **AJAX Tab Loading**: Load order details, customer info, and notes dynamically
- **Status Change**: Change order status directly from the order detail page
- **Performance Optimized**: Cached queries and optimized database operations
- **Responsive Design**: Bootstrap 4 based responsive interface
- **Loading Indicators**: Comprehensive loading state management for AJAX operations

Requirements
------------

[](#requirements)

- PHP 7.4 or higher
- Laravel 8.0 or higher
- WordPress with WooCommerce installed
- MySQL 5.7+ or MariaDB 10.2+

### Required Dependencies

[](#required-dependencies)

The package requires the following dependencies in your main Laravel project:

```
# Required for timezone handling and date management
composer require nesbot/carbon

# Optional but recommended for better performance
composer require predis/predis  # For Redis cache driver
```

**Note**: The `nesbot/carbon` package is automatically included when you install this package, but you may need to run `composer update` in your main project to ensure it's available.

Installation
------------

[](#installation)

1. Install the package via Composer:

```
composer require makiomar/woo-order-dashboard
```

2. Publish the package assets and configurations:

```
# Publish all package assets
php artisan vendor:publish --tag=woo-order-dashboard

# Or publish specific components:
php artisan vendor:publish --tag=woo-order-dashboard-config
php artisan vendor:publish --tag=woo-order-dashboard-views
php artisan vendor:publish --tag=woo-order-dashboard-assets
php artisan vendor:publish --tag=woo-order-dashboard-migrations
```

3. Run the migrations (optional):

```
php artisan migrate --path=vendor/makiomar/woo-order-dashboard/database/migrations
```

4. **⚠️ CRITICAL STEP**: Configure the WooCommerce database connection (see [Database Connection Configuration](#-critical-database-connection-configuration) below)

**This step is REQUIRED and must be completed before using the package.**

Publishing Commands
-------------------

[](#publishing-commands)

The package provides several publish tags for different components:

### Using Provider-Based Commands (Recommended)

[](#using-provider-based-commands-recommended)

```
# Publish all package assets
php artisan vendor:publish --provider="Makiomar\WooOrderDashboard\WooOrderDashboardServiceProvider"

# Publish specific components:
php artisan vendor:publish --provider="Makiomar\WooOrderDashboard\WooOrderDashboardServiceProvider" --tag="config"
php artisan vendor:publish --provider="Makiomar\WooOrderDashboard\WooOrderDashboardServiceProvider" --tag="views"
php artisan vendor:publish --provider="Makiomar\WooOrderDashboard\WooOrderDashboardServiceProvider" --tag="assets"
php artisan vendor:publish --provider="Makiomar\WooOrderDashboard\WooOrderDashboardServiceProvider" --tag="migrations"
php artisan vendor:publish --provider="Makiomar\WooOrderDashboard\WooOrderDashboardServiceProvider" --tag="routes"
php artisan vendor:publish --provider="Makiomar\WooOrderDashboard\WooOrderDashboardServiceProvider" --tag="pagination"
```

### Using Tag-Based Commands (Alternative)

[](#using-tag-based-commands-alternative)

```
# Publish all package assets
php artisan vendor:publish --tag=woo-order-dashboard

# Or publish specific components:
php artisan vendor:publish --tag=woo-order-dashboard-config
php artisan vendor:publish --tag=woo-order-dashboard-views
php artisan vendor:publish --tag=woo-order-dashboard-assets
php artisan vendor:publish --tag=woo-order-dashboard-migrations
php artisan vendor:publish --tag=woo-order-dashboard-routes
```

### Configuration

[](#configuration)

```
php artisan vendor:publish --provider="Makiomar\WooOrderDashboard\WooOrderDashboardServiceProvider" --tag="config"
```

Publishes the configuration file to `config/woo-order-dashboard.php`

### Views

[](#views)

```
php artisan vendor:publish --provider="Makiomar\WooOrderDashboard\WooOrderDashboardServiceProvider" --tag="views"
```

Publishes Blade views to `resources/views/vendor/woo-order-dashboard/`

### Assets

[](#assets)

```
php artisan vendor:publish --provider="Makiomar\WooOrderDashboard\WooOrderDashboardServiceProvider" --tag="assets"
```

Publishes CSS and JS assets to `public/vendor/woo-order-dashboard/`

### Migrations

[](#migrations)

```
php artisan vendor:publish --provider="Makiomar\WooOrderDashboard\WooOrderDashboardServiceProvider" --tag="migrations"
```

Publishes optional database migrations to `database/migrations/optional/`

### Routes

[](#routes)

```
php artisan vendor:publish --provider="Makiomar\WooOrderDashboard\WooOrderDashboardServiceProvider" --tag="routes"
```

Publishes routes file to `routes/woo-dashboard.php` for customization

#### ⚠️ IMPORTANT: Middleware Requirements for Manual Routes

[](#️-important-middleware-requirements-for-manual-routes)

**If you are manually defining routes in your Laravel application instead of using the package's automatic route registration, you MUST include the required middleware:**

```
// In your routes/web.php or routes/api.php
Route::group(['middleware' => ['web', 'auth:admin', 'woo.language']], function() {
    // Your order management routes here
    Route::get('/orders', [WooOrderDashboardController::class, 'index'])->name('orders.index');
    Route::get('/orders/create', [OrdersController::class, 'create'])->name('orders.create');
    // ... other routes
});
```

**Required Middleware:**

- `web` - Laravel web middleware group
- `auth:admin` - Authentication middleware (adjust according to your auth setup)
- `woo.language` - **Language switching middleware (REQUIRED for multilingual support)**

**Without the `woo.language` middleware:**

- Language switching will not work
- URL parameters like `?lang=ar` or `?lang=en` will be ignored
- The language switcher component will not function
- All text will remain in the default language

**To manually register the middleware (if not using the package's ServiceProvider):**

```
// In app/Http/Kernel.php
protected $routeMiddleware = [
    // ... other middlewares
    'woo.language' => \Makiomar\WooOrderDashboard\Http\Middleware\LanguageMiddleware::class,
];
```

### Pagination

[](#pagination)

```
php artisan vendor:publish --provider="Makiomar\WooOrderDashboard\WooOrderDashboardServiceProvider" --tag="pagination"
```

Publishes Bootstrap 4 pagination views to `resources/views/vendor/pagination/` for customization

### Data Files

[](#data-files)

```
php artisan vendor:publish --provider="Makiomar\WooOrderDashboard\WooOrderDashboardServiceProvider" --tag="data"
```

Publishes data files (like continent-country mapping) to `storage/app/woo-order-dashboard/` for customization

### All Assets

[](#all-assets)

```
php artisan vendor:publish --provider="Makiomar\WooOrderDashboard\WooOrderDashboardServiceProvider"
```

Publishes all package assets (config, views, assets, migrations)

### Available Tags Summary

[](#available-tags-summary)

- `config` - Configuration file
- `views` - Blade templates
- `assets` - CSS and JavaScript files
- `migrations` - Optional database migrations
- `routes` - Routes file for customization
- `pagination` - Bootstrap 4 pagination views
- `data` - Data files (continent-country mapping)
- No tag - All assets (recommended for first-time setup)

⚠️ CRITICAL: Database Connection Configuration
----------------------------------------------

[](#️-critical-database-connection-configuration)

**This step is REQUIRED for the package to work properly. Without this configuration, you will get "Undefined array key driver" errors.**

### Step 1: Add WooCommerce Database Connection

[](#step-1-add-woocommerce-database-connection)

You **MUST** add the WooCommerce database connection to your Laravel `config/database.php` file. This is not optional and must be done before using the package.

Open your `config/database.php` file and add the following connection to the `connections` array:

```
'connections' => [
    // ... your existing connections (mysql, sqlite, etc.)

    'woocommerce' => [
        'driver' => 'mysql',
        'host' => env('WOO_DB_HOST', env('DB_HOST', '127.0.0.1')),
        'port' => env('WOO_DB_PORT', env('DB_PORT', '3306')),
        'database' => env('WOO_DB_DATABASE', env('DB_DATABASE')),
        'username' => env('WOO_DB_USERNAME', env('DB_USERNAME')),
        'password' => env('WOO_DB_PASSWORD', env('DB_PASSWORD')),
        'charset' => 'utf8mb4',
        'collation' => 'utf8mb4_unicode_ci',
        'prefix' => env('WOO_DB_PREFIX', 'wp_'),
        'strict' => true,
        'engine' => null,
    ],
],
```

### Step 2: Add WooCommerce Database Credentials

[](#step-2-add-woocommerce-database-credentials)

Add the following environment variables to your `.env` file:

```
# WooCommerce Database Configuration (REQUIRED)
WOO_DB_HOST=127.0.0.1
WOO_DB_PORT=3306
WOO_DB_DATABASE=your_woocommerce_db
WOO_DB_USERNAME=your_username
WOO_DB_PASSWORD=your_password
WOO_DB_PREFIX=wp_
```

### Step 3: Verify Configuration

[](#step-3-verify-configuration)

After adding the database connection, you can verify it's working by running:

```
php artisan tinker
>>> DB::connection('woocommerce')->getPdo();
```

If you see a PDO object returned, your connection is working correctly.

### Troubleshooting Database Connection Issues

[](#troubleshooting-database-connection-issues)

If you encounter "Undefined array key driver" errors:

1. **Check that you added the 'woocommerce' connection to `config/database.php`**
2. **Verify your `.env` file has the correct WooCommerce database credentials**
3. **Clear Laravel's configuration cache:**```
    php artisan config:clear
    php artisan cache:clear
    ```
4. **Restart your web server/development server**

WooCommerce REST API Configuration (Optional)
---------------------------------------------

[](#woocommerce-rest-api-configuration-optional)

The package supports creating orders via the WooCommerce REST API for better integration and compatibility with WooCommerce plugins.

### API Configuration

[](#api-configuration)

Add the following environment variables to your `.env` file:

```
# WooCommerce API Configuration
WOO_API_ENABLED=false
WOO_SITE_URL=https://your-woocommerce-site.com
WOO_CONSUMER_KEY=ck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
WOO_CONSUMER_SECRET=cs_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
WOO_API_VERSION=wc/v3
WOO_API_TIMEOUT=30
WOO_API_MAX_RETRIES=3
WOO_API_RETRY_DELAY=2
WOO_API_VERIFY_SSL=true
WOO_API_DEFAULT_CURRENCY=USD
```

### Getting API Credentials

[](#getting-api-credentials)

1. **Log in to your WooCommerce admin panel**
2. **Go to WooCommerce → Settings → Advanced → REST API**
3. **Click "Add Key"**
4. **Fill in the details:**
    - Description: "Laravel Dashboard API"
    - User: Select an admin user
    - Permissions: "Read/Write"
5. **Click "Generate API Key"**
6. **Copy the Consumer Key and Consumer Secret**

### Testing the API Connection

[](#testing-the-api-connection)

Run the following command to test your API configuration:

```
php artisan woo:test-api
```

### Usage Modes

[](#usage-modes)

#### Database Method (Default)

[](#database-method-default)

By default, orders are created and deleted using direct database insertion:

```
WOO_API_ENABLED=false
```

#### API Method

[](#api-method)

To use the WooCommerce REST API for order creation and deletion:

```
WOO_API_ENABLED=true
```

**Note**: Payment method and order status are taken from the form submission, not from environment variables. This ensures that users can select the appropriate payment method and order status for each order.

### Supported Operations

[](#supported-operations)

The API integration supports the following operations:

- **Order Creation**: Create new orders via WooCommerce REST API
- **Order Deletion**: Delete orders via WooCommerce REST API (including bulk deletion)
- **Connection Testing**: Test API connectivity before operations

### Benefits

[](#benefits)

**API Method Benefits:**

- Better integration with WooCommerce plugins
- Automatic cache updates and lookup table management
- Triggers all WooCommerce hooks and filters
- Data validation by WooCommerce

**Database Method Benefits:**

- Faster performance
- Works offline
- More control over data structure
- No API rate limits

For detailed API configuration instructions, see [WOOCOMMERCE\_API\_CONFIG.md](WOOCOMMERCE_API_CONFIG.md).

Bootstrap 4 Pagination
----------------------

[](#bootstrap-4-pagination)

The package includes Bootstrap 4 pagination views that are automatically used when you call `{{ $orders->links() }}` or any other pagination links.

### Available Pagination Views

[](#available-pagination-views)

1. **Default Bootstrap 4 Pagination** (`bootstrap-4.blade.php`)

    - Full pagination with page numbers
    - Previous/Next buttons with icons
    - Results count display
    - Centered layout
2. **Simple Bootstrap 4 Pagination** (`simple-bootstrap-4.blade.php`)

    - Previous/Next buttons only
    - Page count display
    - Compact layout

### Using Different Pagination Styles

[](#using-different-pagination-styles)

To use a specific pagination style, you can specify it in your Blade templates:

```
{{-- Use default Bootstrap 4 pagination --}}
{{ $orders->links() }}

{{-- Use simple pagination --}}
{{ $orders->links('vendor.pagination.simple-bootstrap-4') }}

{{-- Use custom pagination view --}}
{{ $orders->links('vendor.pagination.custom-view') }}
```

### Customizing Pagination

[](#customizing-pagination)

After publishing the pagination views, you can customize them:

```
# Publish pagination views
php artisan vendor:publish --provider="Makiomar\WooOrderDashboard\WooOrderDashboardServiceProvider" --tag="pagination"
```

The pagination views will be published to `resources/views/vendor/pagination/` where you can modify them to match your design requirements.

### Pagination Configuration

[](#pagination-configuration)

You can configure pagination settings in your Laravel application:

```
// In config/pagination.php
return [
    'default' => 'bootstrap-4',
    'path' => resource_path('views/vendor/pagination'),
];
```

### Features

[](#features-1)

- **Responsive Design**: Works on all screen sizes
- **Accessibility**: Includes proper ARIA labels and semantic HTML
- **FontAwesome Icons**: Uses chevron icons for navigation
- **Bootstrap 4 Classes**: Fully compatible with Bootstrap 4 styling
- **Customizable**: Easy to modify and extend

Assets Configuration
--------------------

[](#assets-configuration)

The package provides flexible control over external asset loading to avoid conflicts with existing CSS frameworks.

### Bootstrap CSS Configuration

[](#bootstrap-css-configuration)

By default, Bootstrap CSS is **disabled** to prevent conflicts with existing Bootstrap installations:

```
# Enable Bootstrap CSS (disabled by default)
WOO_BOOTSTRAP_CSS_ENABLED=false

# Custom Bootstrap CSS URL (optional)
WOO_BOOTSTRAP_CSS_URL=https://cdn.jsdelivr.net/npm/bootstrap@4.6.2/dist/css/bootstrap.min.css
```

### Font Awesome Configuration

[](#font-awesome-configuration)

Font Awesome is enabled by default but can be disabled if you have your own icon library:

```
# Enable Font Awesome (enabled by default)
WOO_FONTAWESOME_ENABLED=true

# Custom Font Awesome URL (optional)
WOO_FONTAWESOME_URL=https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/all.min.css
```

### Usage Scenarios

[](#usage-scenarios)

#### Scenario 1: Using Your Own Bootstrap

[](#scenario-1-using-your-own-bootstrap)

If you already have Bootstrap CSS loaded in your application:

```
WOO_BOOTSTRAP_CSS_ENABLED=false
```

#### Scenario 2: Using Package Bootstrap

[](#scenario-2-using-package-bootstrap)

If you want to use the package's Bootstrap CSS:

```
WOO_BOOTSTRAP_CSS_ENABLED=true
```

#### Scenario 3: Custom Bootstrap Version

[](#scenario-3-custom-bootstrap-version)

If you want to use a different Bootstrap version:

```
WOO_BOOTSTRAP_CSS_ENABLED=true
WOO_BOOTSTRAP_CSS_URL=https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css
```

### Benefits

[](#benefits-1)

- **No Conflicts**: Prevents CSS conflicts with existing frameworks
- **Flexible**: Choose which assets to load
- **Customizable**: Use your own CDN URLs
- **Performance**: Only load what you need

Route Configuration
-------------------

[](#route-configuration)

The package provides clean, unprefixed routes for easy integration:

### Available Routes

[](#available-routes)

```
// Order Management
GET /orders                    - List all orders (orders.index)
GET /orders/{id}              - View order details (orders.show)
GET /orders/create            - Create new order form (orders.create)
POST /orders                  - Store new order (orders.store)

// AJAX Search Routes
GET /products/search          - Search products (products.search)
GET /customers/search         - Search customers (customers.search)

// Bulk Operations
POST /orders/bulk-delete      - Delete multiple orders (orders.bulk-delete)
```

### Route Registration

[](#route-registration)

Routes are automatically registered with the following middleware:

- `web` - Web middleware group
- `auth:admin` - Authentication middleware (customize as needed)

You can customize the middleware in `routes/web.php`:

```
Route::group(['middleware' => ['web', 'auth:admin']], function() {
    // Your custom routes here
});
```

Database Architecture
---------------------

[](#database-architecture)

This package uses Eloquent ORM models to interact with WooCommerce data, providing a more Laravel-native approach:

### Core Models

[](#core-models)

- `Order` - WooCommerce orders (posts table)
- `OrderItem` - Order line items (woocommerce\_order\_items table)
- `OrderItemMeta` - Order item metadata (woocommerce\_order\_itemmeta table)
- `Product` - WooCommerce products (posts table)
- `Customer` - WooCommerce customers (users table)
- `PostMeta` - WordPress post metadata (postmeta table)
- `UserMeta` - WordPress user metadata (usermeta table)
- `Comment` - WordPress comments (comments table)

### Database Compatibility

[](#database-compatibility)

The package supports both traditional WooCommerce installations (using `posts` table for orders) and High-Performance Order Storage (HPOS) setups. The models automatically adapt to your database schema.

Configuration
-------------

[](#configuration-1)

### Basic Configuration

[](#basic-configuration)

The package supports extensive configuration through the `config/woo-order-dashboard.php` file:

```
return [
    'cache' => [
        'enabled' => env('WOO_CACHE_ENABLED', true),
        'driver' => env('WOO_CACHE_DRIVER', 'file'),
        'prefix' => env('WOO_CACHE_PREFIX', 'woo_'),
        'ttl' => [
            'order' => env('WOO_CACHE_TTL_ORDER', 60),
            'product' => env('WOO_CACHE_TTL_PRODUCT', 300),
            'customer' => env('WOO_CACHE_TTL_CUSTOMER', 300),
        ],
    ],

    'order_statuses' => [
        'pending', 'processing', 'on-hold', 'completed',
        'cancelled', 'refunded', 'failed'
    ],

    'status_colors' => [
        'pending' => 'warning',
        'processing' => 'info',
        'on-hold' => 'secondary',
        'completed' => 'success',
        'cancelled' => 'danger',
        'refunded' => 'info',
        'failed' => 'danger',
    ],

    'meta_keys' => [
        '_order_total' => 'Order Total',
        '_billing_first_name' => 'Billing First Name',
        '_billing_last_name' => 'Billing Last Name',
        '_billing_email' => 'Billing Email',
        '_billing_phone' => 'Billing Phone',
        '_shipping_first_name' => 'Shipping First Name',
        '_shipping_last_name' => 'Shipping Last Name',
    ],
];
```

### Environment Variables

[](#environment-variables)

```
# Cache Settings
WOO_CACHE_ENABLED=true
WOO_CACHE_DRIVER=file
WOO_CACHE_PREFIX=woo_
WOO_CACHE_TTL_ORDER=60
WOO_CACHE_TTL_PRODUCT=300
WOO_CACHE_TTL_CUSTOMER=300

# Database Settings
WOO_DB_HOST=127.0.0.1
WOO_DB_PORT=3306
WOO_DB_DATABASE=your_woocommerce_db
WOO_DB_USERNAME=your_username
WOO_DB_PASSWORD=your_password
WOO_DB_PREFIX=wp_

# Assets Settings
WOO_BOOTSTRAP_CSS_ENABLED=false
WOO_BOOTSTRAP_CSS_URL=https://cdn.jsdelivr.net/npm/bootstrap@4.6.2/dist/css/bootstrap.min.css
WOO_FONTAWESOME_ENABLED=true
WOO_FONTAWESOME_URL=https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/all.min.css

# Shipping Settings
WOO_SHIPPING_CART_TOTAL_FILTERING=true
WOO_SHIPPING_SA_LOW_THRESHOLD=499
WOO_SHIPPING_SA_MEDIUM_THRESHOLD=999
WOO_SHIPPING_SA_LOW_COST=21.74
WOO_SHIPPING_SA_MEDIUM_COST=8.70
WOO_SHIPPING_SA_HIGH_COST=0.00
WOO_SHIPPING_OTHER_LOW_THRESHOLD=499
WOO_SHIPPING_OTHER_MEDIUM_THRESHOLD=999
```

Shipping Configuration
----------------------

[](#shipping-configuration)

The package includes advanced shipping method filtering based on cart total, similar to your WordPress theme logic. This feature is **enabled by default** but can be customized or disabled.

### Shipping Method Filtering

[](#shipping-method-filtering)

The shipping filtering works as follows:

#### For Saudi Arabia (SA):

[](#for-saudi-arabia-sa)

- **Cart total < 499 SAR**: Shows only methods with cost 21.74 SAR
- **Cart total 499-998 SAR**: Shows only methods with cost 8.70 SAR
- **Cart total ≥ 999 SAR**: Shows only methods with cost 0.00 SAR (free shipping)

#### For Other Countries:

[](#for-other-countries)

- **Cart total < 499**: Excludes specific methods based on configuration
- **Cart total 499-998**: Excludes different methods based on configuration
- **Cart total ≥ 999**: Excludes specific methods based on configuration

#### Always Included Methods:

[](#always-included-methods)

- Redbox pickup delivery methods
- Local pickup methods
- Any methods specified in the configuration

### Disabling Shipping Filtering

[](#disabling-shipping-filtering)

To disable cart total-based filtering and show all available shipping methods:

```
WOO_SHIPPING_CART_TOTAL_FILTERING=false
```

### Customizing Shipping Thresholds

[](#customizing-shipping-thresholds)

You can customize the cart total thresholds and shipping costs:

```
# Saudi Arabia thresholds and costs
WOO_SHIPPING_SA_LOW_THRESHOLD=499
WOO_SHIPPING_SA_MEDIUM_THRESHOLD=999
WOO_SHIPPING_SA_LOW_COST=21.74
WOO_SHIPPING_SA_MEDIUM_COST=8.70
WOO_SHIPPING_SA_HIGH_COST=0.00

# Other countries thresholds
WOO_SHIPPING_OTHER_LOW_THRESHOLD=499
WOO_SHIPPING_OTHER_MEDIUM_THRESHOLD=999
```

### Advanced Configuration

[](#advanced-configuration)

For advanced customization, you can modify the `config/woo-order-dashboard.php` file to:

- Change which countries exclude DHL Express
- Modify which methods are excluded for different cart totals
- Add or remove methods that should always be included

Language Configuration
----------------------

[](#language-configuration)

The package supports multilingual interfaces with Arabic and English. Arabic is the default language.

### Language Settings

[](#language-settings)

```
# Language Settings
WOO_DEFAULT_LANGUAGE=ar
```

### Available Languages

[](#available-languages)

- **Arabic (ar)**: العربية - Default language with RTL support
- **English (en)**: English - LTR language

### Language Switching

[](#language-switching)

Users can switch languages using the language switcher in the interface. The selected language is stored in the session and persists across requests.

### RTL Support

[](#rtl-support)

Arabic language automatically enables RTL (Right-to-Left) layout support, including:

- Text direction
- Form layouts
- Navigation elements
- Table structures

### Adding New Languages

[](#adding-new-languages)

To add new languages:

1. Create language files in `src/Resources/lang/{language_code}/`
2. Add the language code to the configuration
3. Update the language names and RTL settings

Status Management
-----------------

[](#status-management)

The package includes a comprehensive `StatusHelper` that dynamically manages WooCommerce order statuses by merging predefined default statuses with custom statuses from your database.

### StatusHelper Features

[](#statushelper-features)

The `StatusHelper` provides several methods for managing order statuses:

```
use Makiomar\WooOrderDashboard\Helpers\Orders\StatusHelper;

// Get all statuses (merged: default + database)
$allStatuses = StatusHelper::getAllStatuses();

// Get only predefined default statuses
$defaultStatuses = StatusHelper::getDefaultStatuses();

// Get only database statuses
$databaseStatuses = StatusHelper::getDatabaseStatuses();

// Get statuses with metadata (custom vs default, color classes)
$statusesWithMetadata = StatusHelper::getAllStatusesWithMetadata();

// Get statuses with wc- prefix for database queries
$statusesWithPrefix = StatusHelper::getAllStatusesWithPrefix();

// Prefix handling methods
$statusWithPrefix = StatusHelper::getStatusWithPrefix('processing'); // Returns 'wc-processing'
$statusWithoutPrefix = StatusHelper::removeStatusPrefix('wc-processing'); // Returns 'processing'

// Get status label by key
$label = StatusHelper::getStatusLabel('processing');

// Check if status exists
$exists = StatusHelper::statusExists('custom-status');

// Check if status is custom (not in default statuses)
$isCustom = StatusHelper::isCustomStatus('custom-status');
```

### Default Statuses

[](#default-statuses)

The package includes predefined default statuses that are always available:

```
'default_order_statuses' => [
    'pending' => 'Pending payment',
    'processing' => 'Processing',
    'on-hold' => 'On hold',
    'completed' => 'Completed',
    'cancelled' => 'Cancelled',
    'refunded' => 'Refunded',
    'failed' => 'Failed',
    'checkout-draft' => 'Checkout draft',
    'auto-draft' => 'Auto draft',
],
```

### Custom Statuses

[](#custom-statuses)

Custom statuses are automatically detected from your WooCommerce database and merged with the default statuses. Database statuses take precedence over default statuses with the same key.

### WooCommerce Status Prefix Handling

[](#woocommerce-status-prefix-handling)

WooCommerce stores order statuses in the database with a `wc-` prefix (e.g., `wc-processing`, `wc-completed`). The StatusHelper provides methods to handle this prefix automatically:

```
// Add wc- prefix for database queries
$statusWithPrefix = StatusHelper::getStatusWithPrefix('processing'); // Returns 'wc-processing'

// Remove wc- prefix for display
$statusWithoutPrefix = StatusHelper::removeStatusPrefix('wc-processing'); // Returns 'processing'

// Get all statuses with wc- prefix for database operations
$statusesWithPrefix = StatusHelper::getAllStatusesWithPrefix();
```

This ensures consistent handling of WooCommerce status prefixes throughout your application.

### Status Metadata

[](#status-metadata)

The `getAllStatusesWithMetadata()` method provides detailed information about each status:

```
$statusesWithMetadata = StatusHelper::getAllStatusesWithMetadata();

// Example output:
[
    'processing' => [
        'label' => 'Processing',
        'is_custom' => false,
        'is_default' => true,
        'color_class' => 'primary',
    ],
    'custom-status' => [
        'label' => 'Custom Status',
        'is_custom' => true,
        'is_default' => false,
        'color_class' => 'secondary',
    ],
]
```

### Caching

[](#caching)

All status queries are cached for 1 hour to improve performance. The cache is automatically invalidated when the helper methods are called.

Cache Management
----------------

[](#cache-management)

The package implements comprehensive cache clearing strategies to ensure data consistency:

### Cache Clearing Triggers

[](#cache-clearing-triggers)

- **Order Creation**: Clears order list cache and statistics cache
- **Order Updates**: Clears specific order cache and order list cache
- **Order Deletion**: Clears specific order caches and order list cache
- **Status Changes**: Clears specific order cache, order list cache, and status cache

### Cache Helper Methods

[](#cache-helper-methods)

```
// Clear all order-related cache
CacheHelper::clearOrderCache();

// Clear specific order cache
CacheHelper::clearOrderCacheById($orderId);

// Clear cache on specific events
CacheHelper::clearCacheOnOrderCreate();
CacheHelper::clearCacheOnOrderUpdate($orderId);
CacheHelper::clearCacheOnOrderDelete($orderIds);
CacheHelper::clearCacheOnOrderStatusChange($orderId);
```

### Manual Cache Clearing

[](#manual-cache-clearing)

You can manually clear cache using the helper methods:

```
use Makiomar\WooOrderDashboard\Helpers\CacheHelper;

// Clear all WooCommerce dashboard cache
CacheHelper::clearAllWooCommerceCache();

// Clear specific cache types
CacheHelper::clearOrderListCache();
CacheHelper::clearStatusCache();
CacheHelper::clearStatisticsCache();
```

Performance Optimizations
-------------------------

[](#performance-optimizations)

Usage
-----

[](#usage)

### Order Management with Eloquent Models

[](#order-management-with-eloquent-models)

```
use Makiomar\WooOrderDashboard\Models\Order;
use Makiomar\WooOrderDashboard\Models\Product;
use Makiomar\WooOrderDashboard\Models\Customer;

// Get orders with relationships
$orders = Order::with(['meta', 'items.meta', 'comments'])
    ->where('post_status', 'wc-completed')
    ->orderBy('post_date_gmt', 'desc')
    ->paginate(15);

// Get order details
$order = Order::with(['meta', 'items.meta', 'comments'])->find($orderId);

// Get order meta
$orderTotal = $order->meta->where('meta_key', '_order_total')->first()->meta_value ?? 0;

// Get order items
$orderItems = $order->items;

// Search products
$products = Product::where('post_title', 'like', '%search term%')
    ->where('post_type', 'product')
    ->get();

// Get customers
$customers = Customer::with('meta')->get();
```

### Creating Orders

[](#creating-orders)

```
use Makiomar\WooOrderDashboard\Models\Order;
use Makiomar\WooOrderDashboard\Models\OrderItem;

// Create a new order
$order = new Order();
$order->post_title = 'Order – January 1, 2024 @ 12:00 PM';
$order->post_content = '';
$order->post_status = 'wc-processing';
$order->post_type = 'shop_order';
$order->post_date = now();
$order->post_date_gmt = now()->utc();
$order->post_modified = now();
$order->post_modified_gmt = now()->utc();
$order->save();

// Add order meta
$order->meta()->create([
    'meta_key' => '_order_total',
    'meta_value' => 99.99
]);

// Add order items
$orderItem = new OrderItem();
$orderItem->order_id = $order->ID;
$orderItem->order_item_name = 'Product Name';
$orderItem->order_item_type = 'line_item';
$orderItem->save();
```

### Order Status Management

[](#order-status-management)

The package provides dynamic status management with the ability to change order statuses directly from the order detail page:

#### Viewing Order Status

[](#viewing-order-status)

- Order statuses are automatically fetched from the WooCommerce database
- Statuses are displayed with color-coded badges
- Both default and custom statuses are supported

#### Changing Order Status

[](#changing-order-status)

1. Navigate to an order detail page (`/orders/{id}`)
2. In the "Order Status" section at the top of the page, click the "Change Status" dropdown
3. Select the new status from the dropdown
4. Confirm the status change
5. The status will be updated via AJAX with automatic cache clearing

#### Status Change Features

[](#status-change-features)

- **Confirmation Dialog**: Prevents accidental status changes
- **Loading States**: Visual feedback during status updates
- **Success/Error Messages**: Clear feedback on operation results
- **Automatic Cache Clearing**: Ensures data consistency
- **Order Notes**: Status changes are automatically logged as order notes
- **Page Refresh**: Ensures all data is updated after status change

### AJAX Tab Loading

[](#ajax-tab-loading)

Loading Indicators
------------------

[](#loading-indicators)

The package includes a comprehensive loading state management system for AJAX operations, providing visual feedback to users during data loading and form submissions.

### Features

[](#features-2)

- **Input Loading**: Spinning indicators for search inputs during AJAX requests
- **Button Loading**: Loading states for buttons during form submissions
- **Overlay Loading**: Full-page overlay for major operations
- **Row Loading**: Individual table row loading states
- **Automatic Management**: Centralized loading state management
- **Error Handling**: Proper cleanup on errors

### Demo Page

[](#demo-page)

Visit `/loading-demo` to see all loading indicators in action and test their functionality.

### Usage

[](#usage-1)

#### 1. Include the Loading Utilities

[](#1-include-the-loading-utilities)

Add the loading utilities script to your views:

```

```

#### 2. HTML Structure

[](#2-html-structure)

For input loading indicators:

```

```

For buttons (no special HTML required):

```

     Save

```

#### 3. JavaScript Usage

[](#3-javascript-usage)

```
// Show input loading
loadingManager.showInputLoading('#product-search');

// Hide input loading
loadingManager.hideInputLoading('#product-search');

// Show button loading
loadingManager.showButtonLoading('#submit-btn', 'Saving...');

// Hide button loading
loadingManager.hideButtonLoading('#submit-btn');

// Show overlay
loadingManager.showOverlay('Processing data...');

// Hide overlay
loadingManager.hideOverlay();

// Show row loading
loadingManager.showRowLoading('#row-1');

// Hide row loading
loadingManager.hideRowLoading('#row-1');

// Hide all active loaders
loadingManager.hideAll();
```

#### 4. AJAX Integration Example

[](#4-ajax-integration-example)

```
// Product search with loading indicator
$('#product-search').on('input', function() {
    var query = $(this).val();
    if (query.length