README

A flexible and extensible Laravel repository pattern implementation for Eloquent models, providing a clean interface for data access with built-in caching and query-building utilities.

Features

Repository Pattern: Abstracts Eloquent model interactions for cleaner, testable code.
Model Resolution: Automatically or explicitly resolves Eloquent models based on repository class names or configurations.
Fluent Query Building: Chainable methods for where, with, search, and more.
Caching Support: Optional caching of query results with configurable TTL, using Laravel's cache drivers.
CRUD Operations: Simplified methods for creating, updating, deleting, and restoring models.
Soft Deletes: Handles soft-deleted models with restore and forceDelete methods.
Modular Design: Organized into traits for maintainability and reusability.
Comprehensive Tests: Unit tests covering model resolution, caching, queries, and mutations.

Requirements

PHP >= 8.1
Laravel >= 9.x
Composer
PHPUnit and Mockery for running tests

Installation

Install the package via Composer:
```
composer require awtechs/datasource
```
(Optional) Publish the configuration file:
```
php artisan vendor:publish --provider="Awtechs\DataSource\DataSourceServiceProvider"
```
This creates a config/datasource.php file for customizing settings.

Configuration

The configuration file (config/datasource.php) allows you to customize the package behavior:

return [
    // Enable/disable automatic model resolution based on repository naming conventions
    'auto_resolve_models' => env('DATASOURCE_AUTO_RESOLVE_MODELS', true),

    // Enable/disable caching of query results
    'cache_results' => env('DATASOURCE_CACHE_RESULTS', false),

    // Default cache duration in seconds
    'cache_duration' => env('DATASOURCE_CACHE_DURATION', 3600),

    // Default items per page for pagination
    'default_per_page' => env('DATASOURCE_DEFAULT_PER_PAGE', 15),
];

You can override these settings in your .env file, e.g.:

DATASOURCE_AUTO_RESOLVE_MODELS=true
DATASOURCE_CACHE_RESULTS=true
DATASOURCE_CACHE_DURATION=7200
DATASOURCE_DEFAULT_PER_PAGE=20

Usage

Creating a Repository

Create a repository class extending Awtechs\DataSource\Eloquent\BaseRepository:

namespace App\Repositories;

use Awtechs\DataSource\Eloquent\BaseRepository;
use App\Models\User;

class UserRepository extends BaseRepository
{
    public static function model(): ?string
    {
        return User::class;
    }
}

Alternatively, set the $modelClass property directly:

namespace App\Repositories;

use Awtechs\DataSource\Eloquent\BaseRepository;
use App\Models\User;

class UserRepository extends BaseRepository
{
    protected ?string $modelClass = User::class;
}

If auto_resolve_models is enabled, the repository can infer the model (e.g., UserRepository maps to App\Models\User).

Dependency Injection

Inject the repository into your controllers or services using Laravel's IoC container:

namespace App\Http\Controllers;

use App\Repositories\UserRepository;

class UserController extends Controller
{
    protected $users;

    public function __construct(UserRepository $users)
    {
        $this->users = $users;
    }

    public function index()
    {
        $users = $this->users->all();
        return view('users.index', compact('users'));
    }
}

Example Operations

Retrieve All Records

$users = $this->users->all(['id', 'name']);

Paginate Results

$users = $this->users->paginate(10, ['id', 'name']);

Query with Conditions

$users = $this->users
    ->with(['posts'])
    ->where(['role' => 'admin'])
    ->orderBy('created_at', 'desc')
    ->all();

Search Across Columns

$users = $this->users->search(['name', 'email'], 'john')->all();

Cache Results

$users = $this->users->cacheFor(3600)->all(); // Cache for 1 hour

Create a Record

$user = $this->users->create([
    'name' => 'John Doe',
    'email' => 'john@example.com',
    'password' => bcrypt('password'),
]);

Update a Record

$this->users->update(1, ['name' => 'Jane Doe']);

Delete a Record

$this->users->delete(1); // Soft delete if model uses SoftDeletes
$this->users->forceDelete(1); // Permanent delete

Restore a Soft-Deleted Record

$this->users->restore(1);

Transaction

$this->users->transaction(function ($repo) {
    $repo->create(['name' => 'Test User', 'email' => 'test@example.com']);
    $repo->update(1, ['name' => 'Updated User']);
});

Testing

The package includes comprehensive unit tests for all functionality. To run the tests:

Ensure PHPUnit and Mockery are installed:

composer require --dev phpunit/phpunit mockery/mockery

Copy the test files from the package's tests/Unit directory to your project's tests/Unit directory.
Run the tests:
```
vendor/bin/phpunit
```

The tests cover:

Model resolution (explicit and auto-resolution)
Caching behavior (key generation, cache enable/disable, flushing)
Query building (with, where, search, dynamic methods)
Retrieval operations (all, paginate, find, findOrFail, firstWhere)
Mutation operations (create, update, delete, restore)

Contributing

Contributions are welcome! Please follow these steps:

Fork the repository.
Create a feature branch (git checkout -b feature/my-feature).
Commit your changes (git commit -am 'Add my feature').
Push to the branch (git push origin feature/my-feature).
Create a Pull Request.

Please ensure your code follows PSR-12 standards and includes tests for new functionality.

License

This package is open-sourced under the MIT License.

Support

For issues, questions, or suggestions, please open an issue on the GitHub repository.

awtechs / datasource

Maintainers

Package info

Fund package maintenance!

Statistics

Security