README

A comprehensive Laravel package for integrating with the Daftra API. This package provides a clean, fluent interface for all Daftra API endpoints including products, customers, invoices, purchases, payments, and more.

Features

• Complete API Coverage: All Daftra API endpoints are supported
• Laravel Integration: Native Laravel service provider and facade
• Error Handling: Comprehensive exception handling with specific error types
• Caching: Built-in caching support for GET requests
• Retry Logic: Automatic retry mechanism for failed requests
• Logging: Configurable request/response logging
• Testing: Full test coverage with PHPUnit
• Type Safety: Well-structured services with consistent interfaces

Installation

Install the package via Composer:

composer require usamamuneerchaudhary/daftravel

Publish the configuration file:

php artisan vendor:publish --provider="UsamamuneerChaudhary\Daftravel\DaftravelServiceProvider" --tag="daftravel-config"

Configuration

Add your Daftra API credentials to your .env file:

DAFTRA_API_KEY=your-api-key-here
DAFTRA_API_URL=https://api.daftra.com/v2
DAFTRA_TIMEOUT=30

Usage

Using the Facade

use Daftravel;

// Get all products
$products = Daftravel::products()->all();

// Find a specific product
$product = Daftravel::products()->find(1);

// Create a new product
$product = Daftravel::products()->create([
    'name' => 'New Product',
    'price' => 99.99,
    'stock' => 10,
]);

// Update a product
$product = Daftravel::products()->update(1, [
    'name' => 'Updated Product',
    'price' => 149.99,
]);

// Delete a product
Daftravel::products()->delete(1);

// Paginate results
$products = Daftravel::products()->paginate(1, 20);

Using Dependency Injection

use UsamamuneerChaudhary\Daftravel\Daftravel;

class ProductController extends Controller
{
    protected $daftravel;

    public function __construct(Daftravel $daftravel)
    {
        $this->daftravel = $daftravel;
    }

    public function index()
    {
        $products = $this->daftravel->products()->all();
        return response()->json($products);
    }
}

Available Services

All services support the following basic CRUD operations:

• all() - Get all records
• find($id) - Find a specific record by ID
• create($data) - Create a new record
• update($id, $data) - Update an existing record
• delete($id) - Delete a record
• paginate($page, $limit) - Paginate results

Note: Search functionality varies by endpoint. Some endpoints may support search via query parameters, while others may not. Check the official Daftra API documentation for endpoint-specific search capabilities.

Query Parameters

Common Parameters (Most Endpoints)

• limit - Number of records per page (integer [1..1000], default: 20)
• page - Page number (integer >= 1, default: 1)

Path Parameters

• format - Format of the output (string, default: ".json") - Only for GET operations

Endpoint-Specific Parameters

Each endpoint may support additional parameters. Check the official Daftra API documentation for complete parameter lists.

Examples:

// Get all products (defaults to JSON format)
$products = Daftravel::products()->all();

// Get products with pagination
$products = Daftravel::products()->paginate(1, 20);

// Get products with custom parameters
$products = Daftravel::products()->all([
    'limit' => 10,
    'page' => 2
]);

// Additional parameters (check API docs for specific endpoints)
$products = Daftravel::products()->all([
    'category_id' => 1,
    'status' => 'active'
]);

Note: The format parameter is automatically handled by the client for GET operations. All GET endpoints default to JSON format (.json). POST, PUT, and DELETE operations do not use the format parameter.

Supported Endpoints

The following endpoints are supported by this package. Each endpoint supports basic CRUD operations (all, find, create, update, delete):

Important: Each endpoint may support additional parameters beyond the common ones listed above. Always check the official Daftra API documentation for the complete list of parameters supported by each endpoint.

Products

// Basic CRUD operations
$products = Daftravel::products()->all();
$product = Daftravel::products()->find(1);
$product = Daftravel::products()->create($data);
$product = Daftravel::products()->update(1, $data);
Daftravel::products()->delete(1);

// Pagination and filtering
$products = Daftravel::products()->paginate(1, 20);

Customers

// Basic CRUD operations
$customers = Daftravel::customers()->all();
$customer = Daftravel::customers()->find(1);
$customer = Daftravel::customers()->create($data);
$customer = Daftravel::customers()->update(1, $data);
Daftravel::customers()->delete(1);

// Pagination and filtering
$customers = Daftravel::customers()->paginate(1, 20);

Invoices

// Basic CRUD operations
$invoices = Daftravel::invoices()->all();
$invoice = Daftravel::invoices()->find(1);
$invoice = Daftravel::invoices()->create($data);
$invoice = Daftravel::invoices()->update(1, $data);
Daftravel::invoices()->delete(1);

// Pagination and filtering
$invoices = Daftravel::invoices()->paginate(1, 20);

Categories

// Basic CRUD operations
$categories = Daftravel::categories()->all();
$category = Daftravel::categories()->find(1);
$category = Daftravel::categories()->create($data);
$category = Daftravel::categories()->update(1, $data);
Daftravel::categories()->delete(1);

Suppliers

// Basic CRUD operations
$suppliers = Daftravel::suppliers()->all();
$supplier = Daftravel::suppliers()->find(1);
$supplier = Daftravel::suppliers()->create($data);
$supplier = Daftravel::suppliers()->update(1, $data);
Daftravel::suppliers()->delete(1);

Stores

// Basic CRUD operations
$stores = Daftravel::stores()->all();
$store = Daftravel::stores()->find(1);
$store = Daftravel::stores()->create($data);
$store = Daftravel::stores()->update(1, $data);
Daftravel::stores()->delete(1);

Purchases

// Basic CRUD operations
$purchases = Daftravel::purchases()->all();
$purchase = Daftravel::purchases()->find(1);
$purchase = Daftravel::purchases()->create($data);
$purchase = Daftravel::purchases()->update(1, $data);
Daftravel::purchases()->delete(1);

Payments

// Basic CRUD operations
$payments = Daftravel::payments()->all();
$payment = Daftravel::payments()->find(1);
$payment = Daftravel::payments()->create($data);
$payment = Daftravel::payments()->update(1, $data);
Daftravel::payments()->delete(1);

Expenses

// Basic CRUD operations
$expenses = Daftravel::expenses()->all();
$expense = Daftravel::expenses()->find(1);
$expense = Daftravel::expenses()->create($data);
$expense = Daftravel::expenses()->update(1, $data);
Daftravel::expenses()->delete(1);

Reports

// Basic CRUD operations
$reports = Daftravel::reports()->all();
$report = Daftravel::reports()->find(1);
$report = Daftravel::reports()->create($data);
$report = Daftravel::reports()->update(1, $data);
Daftravel::reports()->delete(1);

Users

// Basic CRUD operations
$users = Daftravel::users()->all();
$user = Daftravel::users()->find(1);
$user = Daftravel::users()->create($data);
$user = Daftravel::users()->update(1, $data);
Daftravel::users()->delete(1);

Taxes

// Basic CRUD operations
$taxes = Daftravel::taxes()->all();
$tax = Daftravel::taxes()->find(1);
$tax = Daftravel::taxes()->create($data);
$tax = Daftravel::taxes()->update(1, $data);
Daftravel::taxes()->delete(1);

Currencies

// Basic CRUD operations
$currencies = Daftravel::currencies()->all();
$currency = Daftravel::currencies()->find(1);
$currency = Daftravel::currencies()->create($data);
$currency = Daftravel::currencies()->update(1, $data);
Daftravel::currencies()->delete(1);

Price Lists

// Basic CRUD operations
$priceLists = Daftravel::priceLists()->all();
$priceList = Daftravel::priceLists()->find(1);
$priceList = Daftravel::priceLists()->create($data);
$priceList = Daftravel::priceLists()->update(1, $data);
Daftravel::priceLists()->delete(1);

Inventory

// Basic CRUD operations
$inventory = Daftravel::inventory()->all();
$item = Daftravel::inventory()->find(1);
$item = Daftravel::inventory()->create($data);
$item = Daftravel::inventory()->update(1, $data);
Daftravel::inventory()->delete(1);

Transactions

// Basic CRUD operations
$transactions = Daftravel::transactions()->all();
$transaction = Daftravel::transactions()->find(1);
$transaction = Daftravel::transactions()->create($data);
$transaction = Daftravel::transactions()->update(1, $data);
Daftravel::transactions()->delete(1);

Appointments

// Basic CRUD operations
$appointments = Daftravel::appointments()->all();
$appointment = Daftravel::appointments()->find(1);
$appointment = Daftravel::appointments()->create($data);
$appointment = Daftravel::appointments()->update(1, $data);
Daftravel::appointments()->delete(1);

Follow-ups

// Basic CRUD operations
$followUps = Daftravel::followUps()->all();
$followUp = Daftravel::followUps()->find(1);
$followUp = Daftravel::followUps()->create($data);
$followUp = Daftravel::followUps()->update(1, $data);
Daftravel::followUps()->delete(1);

Notes

// Basic CRUD operations
$notes = Daftravel::notes()->all();
$note = Daftravel::notes()->find(1);
$note = Daftravel::notes()->create($data);
$note = Daftravel::notes()->update(1, $data);
Daftravel::notes()->delete(1);

Time Tracking

// Basic CRUD operations
$timeEntries = Daftravel::timeTracking()->all();
$timeEntry = Daftravel::timeTracking()->find(1);
$timeEntry = Daftravel::timeTracking()->create($data);
$timeEntry = Daftravel::timeTracking()->update(1, $data);
Daftravel::timeTracking()->delete(1);

Work Orders

// Basic CRUD operations
$workOrders = Daftravel::workOrders()->all();
$workOrder = Daftravel::workOrders()->find(1);
$workOrder = Daftravel::workOrders()->create($data);
$workOrder = Daftravel::workOrders()->update(1, $data);
Daftravel::workOrders()->delete(1);

Credit Notes

// Basic CRUD operations
$creditNotes = Daftravel::creditNotes()->all();
$creditNote = Daftravel::creditNotes()->find(1);
$creditNote = Daftravel::creditNotes()->create($data);
$creditNote = Daftravel::creditNotes()->update(1, $data);
Daftravel::creditNotes()->delete(1);

Refund Receipts

// Basic CRUD operations
$refundReceipts = Daftravel::refundReceipts()->all();
$refundReceipt = Daftravel::refundReceipts()->find(1);
$refundReceipt = Daftravel::refundReceipts()->create($data);
$refundReceipt = Daftravel::refundReceipts()->update(1, $data);
Daftravel::refundReceipts()->delete(1);

Client Payments

// Basic CRUD operations
$clientPayments = Daftravel::clientPayments()->all();
$clientPayment = Daftravel::clientPayments()->find(1);
$clientPayment = Daftravel::clientPayments()->create($data);
$clientPayment = Daftravel::clientPayments()->update(1, $data);
Daftravel::clientPayments()->delete(1);

Journals

// Basic CRUD operations
$journals = Daftravel::journals()->all();
$journal = Daftravel::journals()->find(1);
$journal = Daftravel::journals()->create($data);
$journal = Daftravel::journals()->update(1, $data);
Daftravel::journals()->delete(1);

Incomes

// Basic CRUD operations
$incomes = Daftravel::incomes()->all();
$income = Daftravel::incomes()->find(1);
$income = Daftravel::incomes()->create($data);
$income = Daftravel::incomes()->update(1, $data);
Daftravel::incomes()->delete(1);

Purchase Refunds

// Basic CRUD operations
$purchaseRefunds = Daftravel::purchaseRefunds()->all();
$purchaseRefund = Daftravel::purchaseRefunds()->find(1);
$purchaseRefund = Daftravel::purchaseRefunds()->create($data);
$purchaseRefund = Daftravel::purchaseRefunds()->update(1, $data);
Daftravel::purchaseRefunds()->delete(1);

Stock Transactions

// Basic CRUD operations
$stockTransactions = Daftravel::stockTransactions()->all();
$stockTransaction = Daftravel::stockTransactions()->find(1);
$stockTransaction = Daftravel::stockTransactions()->create($data);
$stockTransaction = Daftravel::stockTransactions()->update(1, $data);
Daftravel::stockTransactions()->delete(1);

Treasuries

// Basic CRUD operations
$treasuries = Daftravel::treasuries()->all();
$treasury = Daftravel::treasuries()->find(1);
$treasury = Daftravel::treasuries()->create($data);
$treasury = Daftravel::treasuries()->update(1, $data);
Daftravel::treasuries()->delete(1);

Client Attendance

// Basic CRUD operations
$attendanceLogs = Daftravel::clientAttendance()->all();
$attendanceLog = Daftravel::clientAttendance()->find(1);
$attendanceLog = Daftravel::clientAttendance()->create($data);
$attendanceLog = Daftravel::clientAttendance()->update(1, $data);
Daftravel::clientAttendance()->delete(1);

Site Info

// Basic CRUD operations
$siteInfo = Daftravel::siteInfo()->all();
$info = Daftravel::siteInfo()->find(1);
$info = Daftravel::siteInfo()->create($data);
$info = Daftravel::siteInfo()->update(1, $data);
Daftravel::siteInfo()->delete(1);

Listings

// Basic CRUD operations
$listings = Daftravel::listings()->all();
$listing = Daftravel::listings()->find(1);
$listing = Daftravel::listings()->create($data);
$listing = Daftravel::listings()->update(1, $data);
Daftravel::listings()->delete(1);

Error Handling

The package provides specific exception classes for different error scenarios:

use UsamamuneerChaudhary\Daftravel\Exceptions\AuthenticationException;
use UsamamuneerChaudhary\Daftravel\Exceptions\ValidationException;
use UsamamuneerChaudhary\Daftravel\Exceptions\RateLimitException;
use UsamamuneerChaudhary\Daftravel\Exceptions\ApiException;

try {
    $products = Daftravel::products()->all();
} catch (AuthenticationException $e) {
    // Handle authentication error
    echo "Authentication failed: " . $e->getMessage();
} catch (ValidationException $e) {
    // Handle validation errors
    $errors = $e->getErrors();
    foreach ($errors as $field => $messages) {
        echo "Field {$field}: " . implode(', ', $messages);
    }
} catch (RateLimitException $e) {
    // Handle rate limit
    $retryAfter = $e->getRetryAfter();
    echo "Rate limit exceeded. Retry after: " . $retryAfter . " seconds";
} catch (ApiException $e) {
    // Handle general API errors
    echo "API error: " . $e->getMessage();
}

Configuration Options

The package provides extensive configuration options:

return [
    'api_url' => env('DAFTRA_API_URL', 'https://api.daftra.com/v2'),
    'api_key' => env('DAFTRA_API_KEY'),
    'timeout' => env('DAFTRA_TIMEOUT', 30),
    
    'retry' => [
        'times' => env('DAFTRA_RETRY_TIMES', 3),
        'delay' => env('DAFTRA_RETRY_DELAY', 1000),
    ],
    
    'cache' => [
        'enabled' => env('DAFTRA_CACHE_ENABLED', true),
        'ttl' => env('DAFTRA_CACHE_TTL', 3600),
        'prefix' => env('DAFTRA_CACHE_PREFIX', 'daftra_'),
    ],
    
    'logging' => [
        'enabled' => env('DAFTRA_LOGGING_ENABLED', true),
        'level' => env('DAFTRA_LOGGING_LEVEL', 'info'),
    ],
];

Testing

Run the tests with:

composer test

Or run PHPUnit directly:

vendor/bin/phpunit

Requirements

• PHP 8.2+
• Laravel 11.0+ or 12.0+
• Guzzle HTTP 7.0+

License

The MIT License (MIT). Please see License File for more information.

Contributing

Please see CONTRIBUTING.md for details.

Security

If you discover any security related issues, please email the author instead of using the issue tracker.

Credits

• Usama Muneer Chaudhary
• All Contributors

Changelog

Please see CHANGELOG.md for more information on what has changed recently.