Laravel Laravel Package

Getting Started

Install via Composer:

composer require laravel-json-api/laravel

Publish the package config (if needed):

php artisan vendor:publish --provider="LaravelJsonApi\LaravelJsonApiServiceProvider"

Register the service provider in config/app.php (if not auto-discovered). First use case: Fetch a JSON:API-compliant response for a model:

use LaravelJsonApi\Laravel\JsonApiResource;
use App\Models\User;

class UserResource extends JsonApiResource
{
    public static $resourceKey = 'users';
    public static $primaryKey = 'id';
}

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

Implementation Patterns

Core Workflow

1. Define Resources: Extend JsonApiResource for each model.
2. Configure Relationships: Use $relationships property or hasMany, belongsTo methods.
3. Customize Fields: Override fields() or resolveField() for dynamic attributes.
4. Pagination: Use built-in pagination (e.g., Resource::paginate()).

Common Patterns

• Filtering: Use JsonApiQueryBuilder for query filtering:

  UserResource::collection(User::query()->filter());
  

• Sorting: Leverage JsonApiQueryBuilder for sorting:

  UserResource::collection(User::query()->sort());
  

• Includes: Fetch nested relationships via ?include=posts,comments:

  UserResource::collection(User::all())->withIncludes();
  

Integration Tips

• API Versioning: Use Laravel’s route model binding with JsonApiResource.
• Testing: Mock JsonApiResource responses in PHPUnit:

  $this->getJson('/users')->assertJsonStructure([
      'data' => [
          ['type' => 'users', 'id' => '1']
      ]
  ]);
  

Gotchas and Tips

Breaking Changes (v5.3.0)

• Laravel 11 Dropped: This package now requires Laravel 10+. Update your laravel/framework constraint in composer.json:

  "laravel/framework": "^10.0"
  

• Undefined Variable Fix: If you were manually using getWheres() in custom queries, ensure you’re using the updated method signature (now type-hinted).

Debugging

• Undefined Fields/Relationships: Verify $resourceKey and $primaryKey are set in your JsonApiResource.
• Query Builder Issues: Use JsonApiQueryBuilder::debug() to inspect parsed query parameters:

  User::query()->filter()->debug();
  

Extension Points

• Custom Query Logic: Override resolveQuery() in your resource:

  public static function resolveQuery($query)
  {
      return $query->where('active', true);
  }
  

• Meta Data: Add custom meta fields:

  return UserResource::collection(User::all())->withMeta(['custom' => 'value']);
  

• Error Handling: Catch JsonApiException for malformed requests.

Performance

• Eager Loading: Always use with() for relationships to avoid N+1 queries:

  UserResource::collection(User::with('posts')->get());
  

• Caching: Cache frequent queries with JsonApiResource::cache() (requires laravel-json-api/cache package).