Getting Started

Minimal Setup

Installation

composer require luezoid/laravel-core

Publish the config:

php artisan vendor:publish --provider="Luezoid\LaravelCore\LaravelCoreServiceProvider" --tag="config"

Basic API Resource Define a resource class (e.g., UserResource):

namespace App\Http\Resources;

use Luezoid\LaravelCore\Resources\Resource;
use App\Models\User;

class UserResource extends Resource
{
    public function toArray($request, User $user)
    {
        return [
            'id' => $user->id,
            'name' => $user->name,
            'email' => $user->email,
        ];
    }
}

First API Endpoint Register a route in routes/api.php:

use App\Http\Resources\UserResource;
use App\Models\User;

Route::get('/users', function () {
    return UserResource::collection(User::all());
});

Query & Filtering Enable filtering in config/laravel-core.php:

'filters' => [
    'enabled' => true,
],

Use built-in filters (e.g., ?search=john):

Route::get('/users', function () {
    return UserResource::collection(User::filter()->get());
});

Implementation Patterns

1. RESTful API Structure

Resource Classes: Extend Luezoid\LaravelCore\Resources\Resource for consistent API responses.

class PostResource extends Resource
{
    public function toArray($request, $post)
    {
        return [
            'title' => $post->title,
            'content' => $post->content,
            'author' => new UserResource($post->user),
        ];
    }
}

Nested Relationships: Use with() and load() for eager loading:

Route::get('/posts/{post}', function (Post $post) {
    return new PostResource($post->load('comments.user'));
});

2. Query & Filtering

Built-in Filters: Enable global filtering in config/laravel-core.php:

'filters' => [
    'enabled' => true,
    'default' => ['search', 'sort'],
],

Use query parameters:

/users?search=john&sort=-created_at

Custom Filters: Create a filter class:

namespace App\Filters;

use Luezoid\LaravelCore\Filters\Filter;

class ActiveFilter extends Filter
{
    public function apply($query)
    {
        return $query->where('is_active', true);
    }
}

LaravelCore::addFilter('active', \App\Filters\ActiveFilter::class);

Use in routes:

/users?active=true

3. Pagination & Meta Data

Custom Pagination: Override meta() in your resource:

public function meta()
{
    return [
        'custom_field' => 'value',
    ];
}

API Responses: Use Resource::collection() or Resource::make():
```
return UserResource::collection(User::paginate(10));
```

4. Validation & Request Handling

API Requests: Extend Luezoid\LaravelCore\Http\Requests\ApiRequest:

namespace App\Http\Requests;

use Luezoid\LaravelCore\Http\Requests\ApiRequest;

class StoreUserRequest extends ApiRequest
{
    public function rules()
    {
        return [
            'name' => 'required|string|max:255',
            'email' => 'required|email|unique:users',
        ];
    }
}

Form Requests: Use in controllers:

public function store(StoreUserRequest $request)
{
    $user = User::create($request->validated());
    return new UserResource($user);
}

5. Middleware & Authentication

API Guard: Configure in config/laravel-core.php:

'auth' => [
    'guard' => 'api',
],

Protect routes:

Route::middleware('auth:api')->group(function () {
    Route::get('/profile', function () {
        return new UserResource(auth()->user());
    });
});

Gotchas and Tips

1. Common Pitfalls

Filter Conflicts: Ensure filter names (e.g., search, sort) don’t clash with Laravel’s built-in query parameters. Use unique prefixes if needed:
```
LaravelCore::addFilter('custom_search', \App\Filters\CustomSearchFilter::class);
```
Then use:
```
/users?custom_search=john
```
Eager Loading Issues: Always use load() with with() to avoid N+1 queries:
```
$post = Post::with('comments.user')->find($id);
```
Resource Caching: Clear cached views if modifying resources:
```
php artisan view:clear
```

2. Debugging

Query Logs: Enable Laravel’s query logging in .env:
```
DB_ENABLE_QUERY_LOG=true
```
Check logs in storage/logs/laravel.log.

Filter Debugging: Dump filter queries:

\Log::info(User::filter()->toSql(), User::filter()->getBindings());

3. Performance Tips

Selective Field Loading: Use select() in queries to reduce payload:
```
User::select('id', 'name', 'email')->filter()->get();
```

Caching Responses: Cache API responses with response()->cache():

return response()->cache(now()->addMinutes(10))->json(UserResource::collection(User::all()));

4. Extending Functionality

Custom Responses: Override Resource::respond() for global response formatting:

namespace App\Http\Resources;

use Luezoid\LaravelCore\Resources\Resource;

class AppResource extends Resource
{
    public function respond($request, $resource)
    {
        return response()->json([
            'data' => $this->toArray($request, $resource),
            'meta' => $this->meta(),
            'status' => 'success',
        ]);
    }
}

Dynamic Relationships: Use append() in models for dynamic attributes:

class Post extends Model
{
    public function getAuthorAttribute()
    {
        return $this->user->name;
    }
}

Access in resource:

return ['author' => $post->author];

5. Configuration Quirks

Filter Order: Filters are applied in registration order. Reorder in AppServiceProvider:

LaravelCore::addFilter('sort', \App\Filters\SortFilter::class);
LaravelCore::addFilter('search', \App\Filters\SearchFilter::class);

Pagination Defaults: Override defaults in config/laravel-core.php:
```
'pagination' => [
    'default' => 15,
    'max' => 100,
],
```

6. Testing

Mocking Filters: Use partial mocks in tests:

$filter = \Mockery::mock(\App\Filters\SearchFilter::class);
$filter->shouldReceive('apply')->andReturn($query);
LaravelCore::setFilter('search', $filter);

API Testing: Use Http::fake() for testing API responses:

use Illuminate\Http\Testing\MixedHttpAuthentication;

$response = $this->actingAs($user)
    ->withHeaders(['Accept' => 'application/json'])
    ->get('/users');

Laravel Core Laravel Package