Download the PHP package odysee/iliad without Composer

Iliad Documentation

Overview

Iliad is a PHP package built on top of Laravel's Eloquent ORM that provides a structured approach to developing REST APIs. It implements the repository pattern to create an abstraction layer between controllers and models, making your codebase more maintainable and testable.

Core Components

Repositories

Repositories are the heart of Iliad, providing a clean interface for data access and manipulation. They encapsulate the logic required to interact with data sources.

BaseRepository (Deprecated)

DEPRECATED: This class is deprecated and should not be used in new code. Use _BaseRepository instead.

The original base repository implementation that provides common methods for interacting with Eloquent models.

_BaseRepository

The current implementation of the repository pattern that leverages PHP 8 features and provides a more robust implementation.

Key features:

• Strong typing with PHP 8 features
• Better integration with Laravel's ecosystem
• Enhanced transaction handling via TransactionManager
• Integration with Spatie's Laravel Data package

Implementing a Repository

When implementing a repository, you should extend _BaseRepository and implement the necessary methods:

Transaction Management

Iliad provides robust transaction handling to ensure database integrity.

Transaction Trait

The Transaction trait provides methods for managing database transactions:

Key features:

• Automatic transaction start for non-GET requests
• Integration with the TransactionManager class
• Automatic rollback on exceptions

TransactionManager

The transaction management system that provides control and error handling:

Key features:

• Tracks active transactions
• Provides a clean API for transaction management
• Supports nested transactions
• Includes a transaction() method for executing code within a transaction

Query Builder Concern

The QueryBuilder trait provides methods for building and executing queries:

Key features:

• Transform queries into data collections
• Parse query string parameters
• Apply sorting, filtering, and other operations

Data Transfer Objects

Iliad uses Data Transfer Objects (DTOs) to encapsulate data and provide a consistent interface.

Dto

The base DTO class that provides common functionality:

Key features:

• Convert to and from arrays
• Create collections of DTOs
• Static factory methods

Controllers

Iliad provides base controllers that integrate with repositories to handle HTTP requests.

BaseController (Deprecated)

DEPRECATED: This class is deprecated and should not be used in new code.

The base controller that provides RESTful endpoints:

_BaseController

The recommended controller base class to extend for new controllers:

Controller

The base controller that provides the foundation for all controllers:

Implementing a Controller

Here's an example of implementing a controller that uses route attributes and integrates with a repository:

Key features:

• Route attributes for defining API routes (#[Prefix], #[Resource])
• Type-hinted repository injection
• Strong typing with return types and parameter types
• Integration with Data objects for request and response handling

Query String Parameters

Iliad supports various query string parameters to customize API responses:

with

Load relationships with the with parameter:

This will return a user with their posts and comments:

You can also load nested relationships:

scopes

Apply model scopes with the scopes parameter:

This will apply the active and premium scopes to the query.

paginate

Enable pagination with the paginate parameter:

This will return paginated results with 10 items per page.

sort

Sort results with the sort parameter:

This will sort users by name in ascending order, then by creation date in descending order.

groupBy

Group results with the groupBy parameter:

This will group users by their role:

exclude

Exclude specific relationships or fields:

This will load user posts but exclude the post body content.

Exception Handling

Iliad includes a custom exception handler that integrates with the transaction system.

HandlerDecorator

Decorates Laravel's exception handler to provide additional functionality:

Key features:

• Custom exception reporting
• Custom exception rendering
• Integration with the transaction system for automatic rollback

Validation

Iliad provides validation support through the Validator trait.

Validator Trait

Key features:

• Apply validation rules to requests
• Custom error handling
• Support for Laravel's validation system

Utility Traits

Iliad includes several utility traits that provide additional functionality.

ResolveId

Resolves the currently authenticated user's ID:

WithData

Provides a method to get a data object from a model:

Editable

Provides methods for formatting messages with variable replacement:

Helper Functions

Iliad includes several helper functions in helpers.php:

• decimalTime($value) - Converts decimal time to hours:minutes format
• timeToDecimal($value) - Converts hours:minutes format to decimal
• carbon($value) - Parses a value to a Carbon instance
• format($value, $format) - Formats a date using Carbon
• generatePassword() - Generates a secure random password

Best Practices

Using Repositories

1. Always extend _BaseRepository for new repositories
2. Implement specific interfaces for each repository
3. Define the required $model and $dataClass properties
4. Inject TransactionManager in the constructor
5. Call $this->transactionManager->commit() at the end of methods that modify data

Using Controllers

1. Always extend _BaseController for new controllers
2. Use route attributes (#[Prefix], #[Resource], etc.) to define routes
3. Type-hint repository dependencies in the constructor
4. Use strong typing for parameters and return values
5. Use data objects (UserData, etc.) for request and response handling

Transaction Management

1. Let Iliad handle transactions automatically for non-GET requests
2. Use $this->transactionManager->commit() to commit transactions
3. Don't worry about rollbacks - they happen automatically on exceptions
4. For complex operations, use the transaction() method of the TransactionManager

Data Transfer Objects

1. Create a specific DTO for each model
2. Use YourData::from($model) to create DTOs from models
3. Define the allowedRequestExcept() method to control what can be excluded

Query Parameters

1. Use with to load relationships efficiently
2. Use scopes to apply model scopes
3. Use sort to control sorting order
4. Use paginate for large result sets

Conclusion

Iliad provides a structured approach to developing REST APIs with Laravel. By following the repository pattern and using the provided base classes, you can create maintainable and testable APIs with minimal boilerplate code.

Remember to always use the most recent implementations (_BaseRepository) and avoid deprecated classes (BaseRepository and BaseController).