Weave Code
JSON:API for Laravel applications.
Frequently asked questions about Laravel
- What Laravel versions does laravel-json-api support, and how do I upgrade from Laravel 11?
- The package dropped Laravel 11 support in v5.3.0. Upgrade to Laravel 10 or 12 by following Laravel’s official upgrade guide, then run `composer require laravel-json-api/laravel:^5.3` and test critical endpoints. The upgrade is straightforward but requires thorough validation of queries, auth, and middleware.
- Can I use this package with non-Eloquent models or raw SQL queries?
- The package primarily relies on Eloquent, so non-Eloquent models may require custom serialization logic or abstraction layers. For raw SQL, consider extending the package’s `JsonApiResource` or using a wrapper to map results to Eloquent-like structures. Document these workarounds for maintainability.
- How do I configure pagination, sorting, and filtering in laravel-json-api?
- Pagination, sorting, and filtering are defined in your `Schema` class. Use methods like `pagination()` to set defaults (e.g., `Paginator::make(15)`), `sortable()` on fields for sorting, and `filters()` to add conditions like `WhereIdIn::make()` or `WhereIn::make()`. The package integrates seamlessly with Laravel’s query builder.
- Does laravel-json-api support sparse fieldsets (fetching only requested fields)?
- Yes, the package supports sparse fieldsets natively. Clients can request specific fields via the `fields` query parameter (e.g., `?fields[posts]=title,body`), and the package will only include those fields in the response. This reduces payload size and improves performance.
- How do I test my JSON:API endpoints with this package?
- Use the built-in `php artisan json:api:test` command to validate compliance, and leverage Laravel’s testing tools for custom logic. Test sparse fieldsets, relationships, and pagination by sending requests with query parameters like `?include=author` or `?page[number]=2`. Mock schemas and resources in your tests for isolated validation.
- Will this package impact my API’s performance? How can I benchmark it?
- The package adds minimal overhead for basic serialization, but complex queries or deep relationships may impact performance. Benchmark endpoints with and without the package using tools like Laravel Debugbar or Blackfire. Optimize by caching responses (`Cache::remember`) or limiting eager-loaded relationships.
- Can I use laravel-json-api with Laravel Nova or other admin panels?
- Yes, the package works alongside Nova. Use the `Schema` class to define resources with Nova-style conventions, and leverage Nova’s built-in API features for admin interfaces. Ensure your schemas align with Nova’s field types (e.g., `Str::make()` for text fields) for consistency.
- How do I handle relationships like `belongsTo`, `hasMany`, or `belongsToMany`?
- Define relationships in your `Schema` using methods like `BelongsTo::make()`, `HasMany::make()`, or `BelongsToMany::make()`. Specify the related model’s type and set `readOnly()` if the relationship shouldn’t be writable. Eager loading is automatic when clients request `?include=relationships`.
- Are there alternatives to laravel-json-api for JSON:API in Laravel?
- Alternatives include `spatie/laravel-fractal` (for custom serialization) or `beberlei/doctrine-extra-bundle` (if using Doctrine). However, laravel-json-api is the most Laravel-native solution, offering built-in JSON:API compliance, testing tools, and tight integration with Eloquent, policies, and form requests.
- How do I customize error responses or add validation rules specific to JSON:API?
- Extend the package’s error handling by overriding the `JsonApiException` class or using Laravel’s `FormRequest` validation. For JSON:API-specific errors, return structured responses with `JsonApiException::make()` and include `errors` in the payload. Combine with Laravel’s validation rules (e.g., `ValidatesWhenActive`) for business logic.
Weaver
How can I help you explore Laravel packages today?