Tutorial: Customizing Endpoints in DataForge

This tutorial walks through customizing DataForge API endpoints to address unique business needs. By tweaking Task, SQL, and Entity classes, you can create endpoints that are tailored to specific workflows or data requirements.

---

Prerequisites

Before proceeding, ensure that:

• DataForge is installed and configured in your Laravel project. Refer to the installation guide.
• You are familiar with the basics of DataForge, including SQL, Task, and Entity classes.
• The standard endpoints (e.g., api/list, api/item, api/Task) are already operational.

---

Step 1: Modify SQL Class

SQL classes define the data source and query logic for your endpoint. Here’s how you can customize them.

Example: Adding Date Range Filters

File Location:

app/DataForge/Sql/Invoice.php

Code:

namespace App\DataForge\Sql;

use DataForge\Sql;

class Invoice extends Sql
{
    public function list(array &$data)
    {
        $query = Query('InvoiceList');

        $query->select('list', 'i.id AS invoiceId, i.customer_id AS customerId, i.total AS totalAmount, i.status AS status, i.created_at AS createdAt');
        $query->from('invoices AS i');
        $query->filter('i.status = {request.status}');
        $query->filterOptional('i.customer_id = {request.customerId}');
        $query->filterOptional('i.created_at >= {request.startDate}');
        $query->filterOptional('i.created_at <= {request.endDate}');
        $query->order('{request.sort}', '{request.order}');

        return $query;
    }
}

Use Case:

• Add support for filtering invoices by a date range (startDate and endDate).

---

Step 2: Extend Entity Class

Entity classes encapsulate the business logic and relationships. You can extend them to include additional attributes or methods.

Example: Adding a Computed Attribute

File Location:

app/DataForge/Entity/Invoice.php

Code:

namespace App\DataForge\Entity;

use DataForge\Entity;

class Invoice extends Entity
{
    public function init($id)
    {
        return \Sql('Invoice:list', ['id' => $id, 'select' => 'entity'])->fetchRow();
    }

    public function getFormattedDate()
    {
        return date('F j, Y', strtotime($this->createdAt));
    }
}

Use Case:

• Add a FormattedDate attribute to the Invoice entity, providing a human-readable version of the createdAt field.

---

Step 3: Create Custom Task Methods

Task classes enable you to define workflows that involve SQL queries, Entities, or both. Here’s how to customize a Task method.

Example: Fetch Invoices by Customer

File Location:

app/DataForge/Task/InvoiceTask.php

Code:

namespace App\DataForge\Task;

use DataForge\Task;

use DataForge\Task;

class InvoiceTask extends Task
{
    public function fetchByCustomer($request)
    {
        $customerId = $request->get('customerId');
        if (!$customerId) {
            $this->setError('Customer ID is missing!');
            return false;
        }

        $invoices = \Sql('Invoice:list', [
            'customerId' => $customerId,
            'select' => 'list',
        ])->fetchRowList();

        return $invoices;
    }
}

Use Case:

• Define a custom endpoint to fetch all invoices for a specific customer.

---

Step 4: Expose the Custom Endpoint

DataForge automatically maps Task methods to the api/Task endpoint. To expose the custom fetchByCustomer method:

Example Request:

/api/Task/InvoiceTask/fetchByCustomer?customerId=67890

Sample Response:

[
    {
        "invoiceId": 12345,
        "customerId": 67890,
        "totalAmount": 500.00,
        "status": "paid",
        "createdAt": "2025-01-01 12:00:00"
    },
    ...
]

---

Step 5: Test and Refine

1. Use tools like Postman or cURL to test your custom endpoint.
2. Validate input parameters and ensure error messages are user-friendly.
3. Optimize queries and ensure they adhere to performance best practices.

---

Advanced Customization

Combine Multiple Queries

Task methods can combine multiple SQL queries to create a composite response:

public function summary($request)
{
    $totalInvoices = \Sql('Invoice:list', ['select' => 'total'])->fetchColumn();
    $paidInvoices = \Sql('Invoice:list', ['status' => 'paid', 'select' => 'total'])->fetchColumn();

    return [
        'totalInvoices' => $totalInvoices,
        'paidInvoices' => $paidInvoices,
    ];
}

Use GuestTask for Public Access

Define GuestTask methods for unauthenticated access:

public function guestSummary($request)
{
    return \Sql('Invoice:publicSummary', [])->fetchRow();
}

---

Conclusion

Customizing endpoints in DataForge allows you to tailor API behavior to your project’s specific needs. By leveraging SQL, Entity, and Task classes, you can create powerful, reusable, and secure endpoints for any application.