### Install Laravel-WHMCS Package

Source: https://context7.com/darthsoup/laravel-whmcs/llms.txt

Installs the Laravel-WHMCS package using Composer and publishes its configuration file for customization. This is the initial setup step for integrating WHMCS API into a Laravel project.

```bash
# Install the package
composer require darthsoup/laravel-whmcs

# Publish configuration file
php artisan vendor:publish --provider="DarthSoup\Whmcs\WhmcsServiceProvider"
```

--------------------------------

### Laravel WHMCS API - Common Operations Examples

Source: https://github.com/darthsoup/laravel-whmcs/blob/main/README.md

This snippet provides practical examples of using the WHMCS facade to perform various operations such as retrieving client domains, products, invoices, orders, and users. It also includes an example for calling custom endpoints.

```php
use \DarthSoup\Whmcs\Facades\Whmcs;

# Obtaining a list of domains purchased by the customer
\Whmcs::Client()->getClientsDomains(['clientid' => '1']);

# Obtaining a list of products purchased by the customer
\Whmcs::Client()->getClientsProducts(['clientid' => '12345']);

# Retrieve a specific invoice
\Whmcs::Billing()->getInvoice(['invoiceid' => '1337']);

# Retrieves all Orders from the system
\Whmcs::Orders()->getOrders();

# Obtain internal users
\Whmcs::Users()->getUsers(['search' => 'foo@bar.org']);

# Custom Method (in case you added custom endpoints) 
\Whmcs::Custom()-><myEndpoint>(['foo' => 'bar']);
```

--------------------------------

### Install Laravel WHMCS Package via Composer

Source: https://github.com/darthsoup/laravel-whmcs/blob/main/README.md

This snippet shows how to install the laravel-whmcs package using Composer. Ensure you have PHP ^7.4 | ^8.0 and Laravel 8 or higher installed.

```bash
composer require darthsoup/laravel-whmcs
```

--------------------------------

### Usage via Facade in Laravel

Source: https://github.com/darthsoup/laravel-whmcs/blob/main/README.md

This PHP code illustrates how to use the WHMCS facade to access API functionalities. It shows a basic example of retrieving client domains.

```php
use \DarthSoup\Whmcs\Facades\Whmcs;

\Whmcs::Client()->getClientsDomains(['clientid' => '1']);
```

--------------------------------

### Client Management - Retrieving Clients

Source: https://context7.com/darthsoup/laravel-whmcs/llms.txt

This section covers how to retrieve client information from WHMCS using the Laravel-WHMCS package. It includes examples for fetching all clients, searching by email, paginating results, and retrieving specific client details.

```APIDOC
## GET /api/whmcs/clients

### Description
Retrieves client information from WHMCS. This endpoint can fetch all clients, search for specific clients by email, paginate results, or retrieve detailed information for a specific client ID.

### Method
GET

### Endpoint
`/api/whmcs/clients` (This is a conceptual endpoint for the provided examples, the actual interaction is through the Whmcs facade)

### Parameters
#### Query Parameters
- **search** (string) - Optional - The email address or name to search for clients.
- **limitstart** (integer) - Optional - The starting limit for pagination.
- **limitnum** (integer) - Optional - The number of results to return per page.
- **clientid** (integer) - Optional - The ID of the specific client to retrieve details for.
- **stats** (boolean) - Optional - Whether to include statistics for the client.

### Request Example
```php
// Get all clients
$allClients = Whmcs::client()->getClients();

// Search for specific client by email
$clientByEmail = Whmcs::client()->getClients([
    'search' => 'john@example.com'
]);

// Get clients with pagination
$clients = Whmcs::client()->getClients([
    'limitstart' => 0,
    'limitnum' => 25
]);

// Get specific client details by ID
$clientDetails = Whmcs::client()->getClientsDetails([
    'clientid' => 123,
    'stats' => true
]);
```

### Response
#### Success Response (200)
- **result** (string) - Indicates the success status of the request.
- **clients** (array) - An array of client objects (if applicable).
- **client** (object) - A single client object with details (if applicable).
- **totalresults** (integer) - The total number of clients found.

#### Response Example
```json
{
    "result": "success",
    "client": {
        "id": 123,
        "firstname": "John",
        "lastname": "Doe",
        "email": "john.doe@example.com",
        "stats": {
            "numActiveOrders": 5,
            "numProducts": 10
        }
    },
    "totalresults": 1
}
```
```

--------------------------------

### Configure WHMCS Retry Logic and Backoff in PHP

Source: https://context7.com/darthsoup/laravel-whmcs/llms.txt

This configuration file example shows how to set up automatic retry logic and backoff strategies for WHMCS API requests. It allows defining the number of retries for a specific connection, improving resilience against transient network issues. Includes settings for connection timeouts.

```php
<?php

// config/whmcs.php
return [
    'connections' => [
        'primary' => [
            'method' => 'token',
            'url' => env('WHMCS_API_URL'),
            'identifier' => env('WHMCS_API_IDENTIFIER'),
            'secret' => env('WHMCS_API_SECRET'),
            'access_key' => env('WHMCS_API_ACCESSKEY'),

            // Enable retry with 2 retries (default when set to true)
            'backoff' => true,

            // Or specify custom number of retries
            // 'backoff' => 5,
        ],
    ],

    // HTTP timeouts in seconds
    'connect_timeout' => 10,
    'timeout' => 30,
];

```

--------------------------------

### Retrieve Client Information using WHMCS API

Source: https://context7.com/darthsoup/laravel-whmcs/llms.txt

Demonstrates how to fetch client data from WHMCS using the Laravel-WHMCS package. Supports retrieving all clients, searching by email, paginating results, and getting specific client details.

```php
<?php

namespace App\Http\Controllers;

use DarthSoup\Whmcs\Facades\Whmcs;
use Illuminate\Http\JsonResponse;

class ClientController extends Controller
{
    public function listClients(): JsonResponse
    {
        // Get all clients
        $allClients = Whmcs::client()->getClients();

        // Search for specific client by email
        $clientByEmail = Whmcs::client()->getClients([
            'search' => 'john@example.com'
        ]);

        // Get clients with pagination
        $clients = Whmcs::client()->getClients([
            'limitstart' => 0,
            'limitnum' => 25
        ]);

        // Get specific client details by ID
        $clientDetails = Whmcs::client()->getClientsDetails([
            'clientid' => 123,
            'stats' => true
        ]);

        return response()->json([
            'success' => true,
            'data' => $clientDetails
        ]);
    }
}
```

--------------------------------

### Usage via Dependency Injection in Laravel Controller

Source: https://github.com/darthsoup/laravel-whmcs/blob/main/README.md

This PHP example shows how to inject the WhmcsManager into a Laravel controller to interact with the WHMCS API. It demonstrates fetching a list of clients using dependency injection.

```php
use DarthSoup\Whmcs\WhmcsManager;

class WhmcsController extends Controller
{
    private WhmcsManager $whmcsManager;

    public function __construct(WhmcsManager $whmcsManager)
    {
        $this->whmcsManager = $whmcsManager;
    }

    public function index()
    {
        $result = $this->whmcsManager->client()->getClients();
        dd($result);
    }
}
```

--------------------------------

### Call Custom WHMCS API Endpoints in PHP

Source: https://context7.com/darthsoup/laravel-whmcs/llms.txt

This controller demonstrates how to call custom WHMCS API endpoints that have been added to a WHMCS installation. It uses the Whmcs facade to interact with custom modules, passing parameters and handling potential exceptions. Requires custom API functions to be present in WHMCS.

```php
<?php

use DarthSoup\Whmcs\Facades\Whmcs;

class CustomApiController extends Controller
{
    public function callCustomEndpoint(): JsonResponse
    {
        try {
            // Call a custom API endpoint
            // Assumes you have added custom API functions to WHMCS
            $result = Whmcs::custom()->myCustomFunction([
                'param1' => 'value1',
                'param2' => 'value2',
                'clientid' => 123
            ]);

            return response()->json([
                'success' => true,
                'data' => $result
            ]);

        } catch (\Exception $e) {
            return response()->json([
                'success' => false,
                'error' => 'Custom endpoint failed: ' . $e->getMessage()
            ], 500);
        }
    }
}

```

--------------------------------

### Configure WHMCS API via .env Variables

Source: https://context7.com/darthsoup/laravel-whmcs/llms.txt

Sets up WHMCS API connection parameters using environment variables for flexibility. Supports both password and token-based authentication methods.

```dotenv
WHMCS_AUTH_TYPE=password
WHMCS_API_URL=https://your-whmcs.com
WHMCS_USERNAME=admin_user
WHMCS_PASSWORD=secure_password
WHMCS_ACCESSKEY=your_access_key

# For token-based authentication
WHMCS_AUTH_TYPE=token
WHMCS_API_IDENTIFIER=your_api_identifier
WHMCS_API_SECRET=your_api_secret
WHMCS_API_ACCESSKEY=your_access_key
```

--------------------------------

### Manage WHMCS Domains and Products in PHP

Source: https://context7.com/darthsoup/laravel-whmcs/llms.txt

Retrieves domain information, WHOIS data, and domain availability for clients using the WhmcsManager. It also demonstrates fetching client hosting products. This snippet handles potential API errors by returning a JSON response with an error message.

```php
<?php

use DarthSoup\Whmcs\Facades\Whmcs;

class DomainController extends Controller
{
    public function getClientDomains(int $clientId): JsonResponse
    {
        try {
            // Get all domains for a client
            $domains = Whmcs::client()->getClientsDomains([
                'clientid' => $clientId,
                'limitstart' => 0,
                'limitnum' => 50
            ]);

            // Get specific domain details
            $domainInfo = Whmcs::domains()->getDomainWhois([
                'domain' => 'example.com'
            ]);

            // Check domain availability
            $availability = Whmcs::domains()->domainWhois([
                'domain' => 'newdomain.com'
            ]);

            return response()->json([
                'success' => true,
                'domains' => $domains,
                'total_domains' => count($domains['domains'] ?? [])
            ]);

        } catch (\Exception $e) {
            return response()->json([
                'success' => false,
                'error' => $e->getMessage()
            ], 500);
        }
    }

    public function getClientProducts(int $clientId): JsonResponse
    {
        // Get hosting products/services for a client
        $products = Whmcs::client()->getClientsProducts([
            'clientid' => $clientId,
            'serviceid' => null, // Optional: specific service ID
            'pid' => null, // Optional: specific product ID
            'domain' => null // Optional: filter by domain
        ]);

        return response()->json($products);
    }
}

```

--------------------------------

### Manage Multiple WHMCS Connections in PHP

Source: https://context7.com/darthsoup/laravel-whmcs/llms.txt

This service demonstrates how to manage and interact with multiple WHMCS instances using named connections. It fetches client data from different instances and retrieves system information, utilizing the WhmcsManager to switch between configured connections. Dependencies include the WhmcsManager class.

```php
<?php

namespace App\Services;

use DarthSoup\Whmcs\WhmcsManager;

class MultiWhmcsService
{
    private WhmcsManager $whmcs;

    public function __construct(WhmcsManager $whmcs)
    {
        $this->whmcs = $whmcs;
    }

    public function syncClientsAcrossInstances(): array
    {
        $results = [];

        try {
            // Use primary connection (default)
            $primaryClients = $this->whmcs
                ->connection('primary')
                ->client()
                ->getClients(['limitnum' => 100]);

            // Switch to secondary connection
            $secondaryClients = $this->whmcs
                ->connection('secondary')
                ->client()
                ->getClients(['limitnum' => 100]);

            $results['primary'] = count($primaryClients['clients'] ?? []);
            $results['secondary'] = count($secondaryClients['clients'] ?? []);

            // Get list of active connections
            $connections = $this->whmcs->getConnections();
            $results['total_connections'] = count($connections);

            return [
                'success' => true,
                'statistics' => $results
            ];

        } catch (\Exception $e) {
            return [
                'success' => false,
                'error' => $e->getMessage()
            ];
        }
    }

    public function getSystemInfo(string $connection = 'primary'): array
    {
        // Get WHMCS system information
        $systemInfo = $this->whmcs
            ->connection($connection)
            ->system()
            ->getStats();

        return $systemInfo;
    }
}

```

--------------------------------

### Register Service Provider and Facade (Optional)

Source: https://github.com/darthsoup/laravel-whmcs/blob/main/README.md

This PHP code demonstrates how to manually register the service provider and optionally set up a facade alias in your Laravel application's config/app.php file if auto-discovery does not work.

```php
'DarthSoup\Whmcs\WhmcsServiceProvider::class',
```

```php
'Whmcs' => DarthSoup\Whmcs\Facades\Whmcs::class
```

--------------------------------

### Fetch WHMCS Data with Automatic Retries in PHP

Source: https://context7.com/darthsoup/laravel-whmcs/llms.txt

This service demonstrates fetching WHMCS client data with automatic retry logic enabled. If the initial API request fails, the package will automatically retry the request based on the backoff configuration. Errors are logged if all retries fail, and the exception is re-thrown.

```php
<?php

use DarthSoup\Whmcs\Facades\Whmcs;

class ResilientApiService
{
    public function fetchWithRetry(): array
    {
        try {
            // This will automatically retry up to 2 times if configured
            $clients = Whmcs::client()->getClients([
                'limitnum' => 100
            ]);

            return [
                'success' => true,
                'data' => $clients,
                'fetched_at' => now()
            ];

        } catch (\Exception $e) {
            \Log::error('WHMCS API failed after retries', [
                'error' => $e->getMessage(),
                'trace' => $e->getTraceAsString()
            ]);

            throw $e;
        }
    }
}

```

--------------------------------

### Create WHMCS Client in PHP

Source: https://context7.com/darthsoup/laravel-whmcs/llms.txt

Adds a new client to WHMCS with comprehensive validation for required fields. It utilizes the WhmcsManager to interact with the WHMCS API, handling potential exceptions during the process. Input includes validated request data and optional fields like notes and email preferences.

```php
<?php

namespace App\Http\Controllers;

use DarthSoup\Whmcs\WhmcsManager;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;

class ClientController extends Controller
{
    private WhmcsManager $whmcs;

    public function __construct(WhmcsManager $whmcs)
    {
        $this->whmcs = $whmcs;
    }

    public function createClient(Request $request): JsonResponse
    {
        $validated = $request->validate([
            'firstname' => 'required|string',
            'lastname' => 'required|string',
            'email' => 'required|email',
            'address1' => 'required|string',
            'city' => 'required|string',
            'postcode' => 'required|string',
            'country' => 'required|string|size:2',
            'phonenumber' => 'required|string',
        ]);

        try {
            $result = $this->whmcs->client()->addClient([
                'firstname' => $validated['firstname'],
                'lastname' => $validated['lastname'],
                'email' => $validated['email'],
                'address1' => $validated['address1'],
                'city' => $validated['city'],
                'state' => $request->input('state', ''),
                'postcode' => $validated['postcode'],
                'country' => $validated['country'],
                'phonenumber' => $validated['phonenumber'],
                'password2' => $request->input('password', bin2hex(random_bytes(8))),
                'clientip' => $request->ip(),
                'notes' => $request->input('notes', ''),
                'noemail' => $request->boolean('no_email', false),
            ]);

            return response()->json([
                'success' => true,
                'client_id' => $result['clientid'],
                'message' => 'Client created successfully'
            ], 201);

        } catch (\Exception $e) {
            return response()->json([
                'success' => false,
                'error' => $e->getMessage()
            ], 400);
        }
    }
}

```

--------------------------------

### Configure WHMCS API Connections

Source: https://context7.com/darthsoup/laravel-whmcs/llms.txt

Defines WHMCS API connection details in the configuration file. Supports multiple connections with different authentication methods (password or token) and custom timeouts.

```php
<?php

return [
    'default' => 'primary',

    'connections' => [
        'primary' => [
            'method' => 'password',
            'url' => 'https://your-whmcs.com',
            'username' => 'admin',
            'password' => 'your-secure-password',
            'access_key' => 'optional-access-key'
        ],

        'secondary' => [
            'method' => 'token',
            'url' => 'https://another-whmcs.com',
            'identifier' => 'api-identifier',
            'secret' => 'api-secret',
            'access_key' => 'optional-access-key'
        ],
    ],

    'connect_timeout' => 10,
    'timeout' => 30,
];
```

--------------------------------

### Manage WHMCS Billing and Invoices in Laravel

Source: https://context7.com/darthsoup/laravel-whmcs/llms.txt

Handles invoice creation, retrieval, and payment recording using the DarthSoup WHMCS package. It allows fetching specific invoices, all invoices for a client with filtering, adding payments, and creating new draft invoices. Requires the DarthSoup WHMCS package and a configured WHMCS connection.

```php
<?php

use DarthSoup\Whmcs\Facades\Whmcs;

class BillingController extends Controller
{
    public function getInvoiceDetails(int $invoiceId): JsonResponse
    {
        try {
            // Get specific invoice
            $invoice = Whmcs::billing()->getInvoice([
                'invoiceid' => $invoiceId
            ]);

            // Get all invoices for a client
            $clientInvoices = Whmcs::billing()->getInvoices([
                'userid' => 123,
                'status' => 'Unpaid', // Paid, Unpaid, Cancelled, etc.
                'limitstart' => 0,
                'limitnum' => 25
            ]);

            // Add invoice payment
            $payment = Whmcs::billing()->addInvoicePayment([
                'invoiceid' => $invoiceId,
                'transid' => 'TXN_' . time(),
                'gateway' => 'stripe',
                'amount' => 99.99,
                'date' => date('Y-m-d H:i:s')
            ]);

            // Create a new invoice
            $newInvoice = Whmcs::billing()->createInvoice([
                'userid' => 123,
                'status' => 'Draft',
                'sendinvoice' => false,
                'paymentmethod' => 'banktransfer',
                'itemdescription1' => 'Custom Service',
                'itemamount1' => 49.99,
                'itemtaxed1' => true
            ]);

            return response()->json([
                'success' => true,
                'invoice' => $invoice,
                'payment_recorded' => isset($payment['result']) && $payment['result'] === 'success'
            ]);

        } catch (Exception $e) {
            return response()->json([
                'success' => false,
                'error' => $e->getMessage()
            ], 500);
        }
    }
}

```

--------------------------------

### Manage WHMCS Orders in Laravel

Source: https://context7.com/darthsoup/laravel-whmcs/llms.txt

Facilitates order retrieval and placement through the DarthSoup WHMCS package. It allows fetching all orders with optional filters (e.g., by user ID, status) and adding new orders with product details, domain information, and payment method. Requires the DarthSoup WHMCS package and a configured WHMCS connection.

```php
<?php

use DarthSoup\Whmcs\Facades\Whmcs;

class OrderController extends Controller
{
    public function getAllOrders(): JsonResponse
    {
        // Retrieve all orders with optional filtering
        $orders = Whmcs::orders()->getOrders([
            'limitstart' => 0,
            'limitnum' => 100,
            'userid' => null, // Optional: filter by client ID
            'status' => 'Active' // Pending, Active, Completed, Cancelled, Fraud
        ]);

        return response()->json($orders);
    }

    public function placeOrder(Request $request): JsonResponse
    {
        try {
            // Add a new order
            $order = Whmcs::orders()->addOrder([
                'clientid' => $request->input('client_id'),
                'pid' => [101], // Product IDs array
                'domain' => ['example.com'],
                'billingcycle' => ['annually'],
                'domaintype' => ['register'],
                'regperiod' => [1],
                'paymentmethod' => 'stripe',
                'promocode' => $request->input('promo_code', ''),
                'affid' => $request->input('affiliate_id', 0),
                'noinvoice' => false,
                'noemail' => false
            ]);

            return response()->json([
                'success' => true,
                'order_id' => $order['orderid'],
                'invoice_id' => $order['invoiceid'] ?? null
            ], 201);

        } catch (Exception $e) {
            return response()->json([
                'success' => false,
                'error' => $e->getMessage()
            ], 400);
        }
    }
}

```

--------------------------------

### Publish Vendor Assets and Configure WHMCS

Source: https://github.com/darthsoup/laravel-whmcs/blob/main/README.md

This command publishes the configuration file for the laravel-whmcs package. After running this, you should modify the generated config/whmcs.php file with your WHMCS API credentials and connection details.

```bash
php artisan vendor:publish --provider="DarthSoup\Whmcs\WhmcsServiceProvider"
```

--------------------------------

### Manage WHMCS Users in Laravel

Source: https://context7.com/darthsoup/laravel-whmcs/llms.txt

Provides functionality to search for admin users and retrieve their permissions using the DarthSoup WHMCS package. It allows searching users by a query string and fetching specific user permissions by user ID. Requires the DarthSoup WHMCS package and a configured WHMCS connection.

```php
<?php

use DarthSoup\Whmcs\Facades\Whmcs;

class UserManagementController extends Controller
{
    public function searchUsers(Request $request): JsonResponse
    {
        try {
            // Search for admin users
            $users = Whmcs::users()->getUsers([
                'search' => $request->input('query', ''),
                'limitstart' => 0,
                'limitnum' => 25
            ]);

            // Get specific user permissions
            $permissions = Whmcs::users()->getUserPermissions([
                'userid' => 5
            ]);

            return response()->json([
                'success' => true,
                'users' => $users,
                'total' => count($users['users'] ?? [])
            ]);

        } catch (Exception $e) {
            return response()->json([
                'success' => false,
                'error' => $e->getMessage()
            ], 500);
        }
    }
}

```

--------------------------------

### Register WHMCS Service Provider in PHP

Source: https://context7.com/darthsoup/laravel-whmcs/llms.txt

This snippet shows how to manually register the WHMCS service provider and its alias in the `config/app.php` file. This is necessary if Laravel's auto-discovery feature is disabled. It ensures that the WHMCS facade and related services are available throughout the application.

```php
<?php

// config/app.php
return [
    'providers' => [
        // Other service providers...
        DarthSoup\Whmcs\WhmcsServiceProvider::class,
    ],

    'aliases' => [
        // Other aliases...
        'Whmcs' => DarthSoup\Whmcs\Facades\Whmcs::class,
    ],
];

```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.