Best Practices

Best Practices for Using DataForge

Adhering to best practices ensures that your application remains scalable, maintainable, and efficient while leveraging the full power of DataForge. Below are the recommended guidelines for optimal usage.

1. Modular and Organized Directory Structure

Recommendation:

Maintain a clear and consistent directory structure for SQL, Entity, and Task classes:
```
app/DataForge/
    Sql/
    Entity/
    Task/
```
Name files and classes logically (e.g., Invoice, User, Customer).

Why?

Improves readability and simplifies collaboration.
Promotes maintainability for large codebases.

2. Use Named Queries

Recommendation:

Always assign a meaningful name to your queries when instantiating a Query object:

$query = Query('InvoiceSummary');

Why?

Helps in identifying query-related errors.
Simplifies debugging with descriptive logs.

3. Leverage `select` Types in SQL Classes

Recommendation:

Define multiple select types for versatile query reuse:

$query->select('list', 'id, customer_id, total');
$query->select('item', 'id, customer_id, total, status');
$query->select('summary', 'SUM(total) AS totalSales');

Why?

Enhances query reusability across different endpoints.
Reduces redundancy in query definitions.

4. Enforce Strong Typing in Entity Methods

Recommendation:

Define attribute methods in Entity classes with strict type declarations:

function getTotalAmount(): float
{
    return Sql('Invoice:total', ['id' => $this->id])->fetchColumn();
}

Why?

Ensures data consistency and reduces runtime errors.
Improves code readability and developer confidence.

5. Lazy Loading for Optimized Performance

Recommendation:

Define attributes in Entity classes that load only when accessed:

function getCustomer(): Customer
{
    return DataForge::getCustomer($this->customer_id);
}

Why?

Minimizes unnecessary data retrieval.
Enhances application performance, especially for large datasets.

6. Use Attribute Groups for Bulk Operations

Recommendation:

Organize related attributes into groups using attribGroups in Entity classes:

function attribGroups(): array
{
    return [
        'Financials' => 'TotalAmount, TaxAmount, DiscountAmount',
        'Details' => 'InvoiceDate, DueDate, Status'
    ];
}

Why?

Simplifies batch retrieval of related attributes.
Improves efficiency in data-heavy operations.

7. Centralize Access Control Logic

Recommendation:

Implement access validation within the access method of Entity classes:

function access(): bool
{
    return Auth::user()->can('view', $this);
}

Why?

Ensures consistent and secure access control.
Avoids duplication of access logic across your application.

8. Combine SQL and Entity Methods in Task Classes

Recommendation:

Utilize Task classes to orchestrate complex workflows:

function generateInvoiceReport($request)
{
    $invoices = Sql('Invoice:list', ['status' => 'unpaid'])->fetchRowList();
    $total = array_sum(array_column($invoices, 'total'));

    return [
        'Invoices' => $invoices,
        'TotalUnpaid' => $total
    ];
}

Why?

Centralizes complex logic for easy maintenance.
Enhances reusability and modularity.

9. Secure Guest Access

Recommendation:

Limit public access by using GuestTask methods for non-sensitive data:

function guestInvoiceSummary(): array
{
    return Sql('Invoice:summary')->fetchRow();
}

Why?

Protects sensitive data from unauthorized access.
Allows controlled public exposure for specific use cases.

10. Test and Debug Extensively

Recommendation:

Use descriptive query names for easy debugging.
Validate all dynamic parameters to prevent SQL injection.
Test each Task and Entity method individually.

Why?

Ensures robust and secure implementation.
Simplifies troubleshooting during development and maintenance.

Conclusion

By following these best practices, developers can maximize the efficiency, maintainability, and security of applications built with DataForge. These guidelines not only streamline development but also ensure that the system remains robust and scalable for future growth.