Releases: laravel-json-api/laravel
Releases · laravel-json-api/laravel
Initial stable release
Finally, our initial stable release. Yes there's more features to work on, but this package is definitely production ready - so here at last is a stable release!
Upgrade Instructions
composer require laravel-json-api/laravel --no-update
composer require laravel-json-api/testing --dev --no-update
composer up laravel-json-api/* cloudcreativity/json-api-testing
Added
- New relationship filter classes:
Has
,WhereHas
,WhereDoesntHave
. Refer to the filter documentation for details.
Changed
- BREAKING: Countable Relationships. This feature is now turned off by default. Although included in the 1.0 release, this feature is not considered production-ready. This is because we plan to make breaking changes to it, which will change how the client requests countable relationships. As such, this feature is considered highly-experimental and developers must opt-in to it by calling the
canCount()
method on a relationship. Refer to the Countable relationships chapter in the documentation for more details. - BREAKING: Cursor Pagination. Laravel now has its own cursor pagination feature. We have therefore moved our implementation into its own package: laravel-json-api/cursor-pagination This change has been made because it makes sense for the in-built cursor pagination implementation to use Laravel's cursor pagination implementation rather than our own custom one. Support for Laravel's cursor pagination will be added during the
1.x
release cycle. If you are already using our cursor implementation, you can migrate in two easy steps:- Install the new package:
composer require laravel-json-api/cursor-pagination
- In any schemas using the cursor pagination, change the import statement
fromLaravelJsonApi\Eloquent\Pagination\CursorPagination
toLaravelJsonApi\CursorPagination\CursorPagination
.
- Install the new package:
Authorizer updates, debug exceptions and more improvements
Added
- The authorizer now has separate
showRelated()
andshowRelationship()
methods. Previously both these controller actions were authorized via the singleshowRelationship()
method. Adding the newshowRelated
method means developers can now implement separate authorization logic for these two actions if desired. Our default implementation remains unchanged - both are authorized using theview<RelationshipName>
method on the relevant policy. - The request class now has a
isCreatingOrUpdating()
helper method to determine whether the request is to create or updated a resource. - Add stop on first failure to all validators in the resource request class.
- #85 When running an application with debug mode turned on, the default JSON:API error object for an exception will now contain detailed exception information, including the stack trace, in the object's
meta
member. - #103 Can now fully customise attribute serialization to JSON using the
extractUsing()
callback. This receives the model, column name and value. This is useful if the developer needs to control the serialization of a few fields on their schema. However, the recommendation is to use a resource class for complete control over the serialization of a model to a JSON:API resource.
Changed
- Minimum Laravel version is now
8.30
. This change was required to use the$stopOnFirstFailure
property on Laravel'sFormRequest
class. - Schema classes no longer automatically sort their fields by name when iterating over them. This change was made to give the developer full control over the order of fields (particularly as this order affects the order in which fields are listed when serialized to a JSON:API resource). Developers can list fields in name order if that is the preferred order.
- Removed the
LaravelJsonApi\Spec\UnexpectedDocumentException
which was thrown if there was a failure when decoding request JSON content before parsing it for compliance with the JSON:API specification. AJsonApiException
will now be thrown instead.
Fixed
- #101 Ensure controller create action always returns a response that will result in a
201 Created
response. - #102 The attach and detach to-many relationship controller actions now correctly resolve the collection query class using the relation's inverse resource type. Previously they were incorrectly using the primary resource type to resolve the query class.
Pagination links fix
Fixed
- #76 Pagination links will now be correctly added to related resources and relationship identifiers responses.
Sort fields and default include paths
Added
- #14 Additional sort parameters can now be added to Eloquent schemas. Previously only sortable attributes were supported. These new classes are added to schemas in the
sortables()
method. Refer to the new Sorting chapter in the documentation. - Eloquent schemas now support a default sort order via the
$defaultSort
property. - New generator command
jsonapi:sort-field
to create a custom sort field class. - #74 Developers can now add default include paths to the query request classes (e.g.
PostQuery
andPostCollectionQuery
) via the$defaultIncludePaths
property. These include paths are used if the client does not provide any include paths.
Attributes from related models and various improvements
Added
- #65 BREAKING The
fill()
method on Eloquent fields has been updated to receive all the validated data as its third argument. This change was made to allow fields to work out the value to fill into the model based on other JSON:API field values. If you have written any custom fields, you will need to update thefill()
method on your field class. - BREAKING Eloquent attributes now support serializing and filling column values on related objects. This is primarily intended for use with the Eloquent
belongsTo
,hasOne
,hasOneThrough
andmorphOne
relationships that have awithDefault()
method. As part of this change, themustExist()
method was added to theFillable
interface. If you have written any custom fields, you will need to add this method to your field class - it should returntrue
if the attribute needs to be filled after the primary model has been persisted. - #58 Schema model classes can now be a parent class or an interface.
Fixed
- #69 Fixed the parsing of empty
include
,sort
andwithCount
query parameters.
Countable relations, id encoding and non-Eloquent resources
Added
- #18 Added a
withCount
query parameter. For Eloquent resources, this allows a client to request the relationship count for the primary data's relationships. Refer to documentation for implementation details. - #55 Encoding and decoding of resource IDs is now supported. The
ID
field needs to implement theLaravelJsonApi\Contracts\Schema\IdEncoder
interface for this to work. - #41 Hash IDs are now supported by installing the
laravel-json-api/hashids
package and using theHashId
field instead of the standard EloquentID
field. Refer to documentation for details. - #30 Non-Eloquent resources are now supported via the
laravel-json-api/non-eloquent
package. Refer to documentation for implementation details. - There is now a
Core\Reponses\RelatedResponse
class for returning the result for a related resources endpoint. For example, the/api/v1/posts/1/comments
endpoint. Previously theDataResponse
class was used. While this class can still be used, the newRelatedResponse
class merges relationship meta into the top-levelmeta
member of the response document. For to-many relationships that are countable, this will mean the top-levelmeta
member will contain the count of the relationship. - The schema generator Artisan command now has a
--non-eloquent
option to generate a schema for a non-Eloquent resource.
Changed
- The
LaravelJsonApi::registerQuery()
,LaravelJsonApi::registerCollectionQuery()
andLaravelJsonApi::registerRequest()
methods must now be used to register custom HTTP request classes for specified resource types. Previously methods could be called on theRequestResolver
classes, but these have now been removed.
Fixed
- Relationship endpoints that return resource identifiers now correctly include page meta in the top-level meta member of the document, if the results are paginated. Previously the page meta was incorrectly omitted.
Soft deletes, polymorphic to-many and multi-resource models
Added
- #43 The package now supports soft-deleting resources. For full details on how to apply this to resource schemas, refer to the new Soft Deleting chapter in the documentation.
- Multi-resource models are now supported. This allows developers to represent a single model class as multiple different JSON:API resource types within an API. Refer to documentation for details of how to implement.
- #8 The new
MorphToMany
relation field can now be used to add polymorphic to-many relations to a schema. Refer to documentation for details. - Developers can now type-hint dependencies in their server's
serving()
method. - Can now manually register request, query and collection query classes using the
RequestResolver::registerRequest()
,RequestResolver::registerQuery()
andRequestResolver::registerCollectionQuery()
static methods.
Extensive additions and fixes
Added
- Added missing
jsonapi:authorizer
generator command. - The Eloquent schema now has
indexQuery
andrelatableQuery
methods. These allow filtering for authorization purposes when a list of resources is being retrieved. For instance, it could filter those queries so that only models belonging to the authenticated user are returned. - #23 The resource request class now does not need to exist for the destroy controller action. Previously the implementation was expecting the resource request class to exist, even though delete validation was optional.
- #24 Controller actions will now stop executing and return a response if one is returned by the before action hooks: i.e.
searching
,reading
,saving
,creating
,updating
,deleting
,readingRelated<Name>
,reading<Name>
,updating<Name>
,attaching<Name>
anddetaching<Name>
. - #37 Can now use constructor dependency injection in
Server
classes. - #40 There is now a new
MetaResponse
class that can be used when returning meta-only responses. In addition, response classes have been updated to add awithServer
method. This can be used to specify the named server the response should use to encode the JSON:API document. This has to be used when returning responses from routes that have not run the JSON:API middleware (i.e. there is no default server available via the service container). - #9 The Laravel route registrar is now passed through to the
resources
,relationships
andactions
callbacks as the second function argument. - #36 Eloquent schemas now support complex singular filter logic, via the
Schema::isSingular()
method. - #33 Specification compliance will now reject an incorrect resource type in a relationship. For example, if a relationship expects
tags
but the client sendsposts
, the request will be rejected with an error message thatposts
are not supported.
Changed
- #22 BREAKING The
index
andstore
methods on the authorizer contract now receive the model class as their second argument. This is useful for authorizers that are used for multiple resource types. - BREAKING When querying or modifying models via the schema repository or store, calls to
using()
must be replaced withwithRequest()
. This change was made to make it clearer that the request class can be passed into query builders. - #28 The sparse field sets validation rule will now reject with a specific message identifying any resource types in the parameter that do not exist.
- #35 The
Relation::type()
method must now be used when setting the inverse resource type for the relation.
Fixed
- Optional parameters to generator commands that require values now work correctly. Previously these were incorrectly set up as optional parameters that expected no values.
- #25 The encoder now correctly handles conditional fields when iterating over a resource's relationships.
- #26 Fix parsing the
fields
query parameter to field set value objects. - #34 Do not require server option when generating a generic authorizer with multiple servers present.
- #29 Do not reject delete requests without a
Content-Type
header. - #11 Fixed iterating over an empty to-many generator twice in the underlying compound document encoder.
Deprecated
- The
Relation::inverseType()
method is deprecated and will be removed in1.0-stable
. UseRelation::type()
instead.
Custom resource controller actions and more
Added
- #12 Can now register routes for custom actions on a resource, using the
actions()
helper method when registering resources. See the PR for examples. - The
JsonApiController
now has the LaravelAuthorizesRequests
,DispatchesJobs
andValidatesRequests
traits applied. - #6 Resource class can now use conditional fields in their relationships. This works in the same way as conditional attributes: the resource's
when()
andmergeWhen()
method should be used to add conditional relationships. - #13 Added French translations for JSON:API errors generated by specification parsing and resource/query parameter validation.
- #7 Eloquent schemas now support default eager loading via their
$with
property. - #15 When parsing a JSON:API document for compliance with the specification, the client will now receive a clearer error message if they submit a to-one relationship object for a to-many relationship (and vice-versa).
Changed
- #2 BREAKING Improved the extraction of existing resource field values when constructing validation data for update requests:
- The
existingAttributes()
andexistingRelationships()
methods on the resource request class has been removed. If you need to modify the existing values before the client values are merged, implement thewithExisting()
method instead. This receives the model and its JSON representation (as an array). - The
mustValidate()
method must now be called on a schema relationship field. (Previously this was on the resource relation.) By default, belongs-to and morph-to relations will be included when extracting existing values; all other relations will not. Use themustValidate()
ornotValidated()
method on the schema relation to alter whether a relation is included in the extracted values.
- The
Optional Resources
Added
- #1 Resource classes are now optional. If one is not defined, the implementation falls-back to using the Eloquent schema to serialize a model. Eloquent schema fields now have new
hidden
andserializeUsing
methods to customise the serialization of models by the schema. - Resource classes now support using conditional attributes in their
meta()
method. - New field classes
ArrayList
andArrayHash
have been added, to distinguish between PHP zero-indexed arrays that serialize to JSON arrays (ArrayList
) and PHP associative arrays that serialize to JSON objects (ArrayHash
). The distinction is required because an empty array list can be serialized to[]
in JSON whereas an empty associative array must be serialized tonull
in JSON.
Changed
- BREAKING The JsonApiResource method signatures for the
attributes()
,relationships()
,meta()
, andlinks()
methods have been changed so that they receive the HTTP request as the first (and only) parameter. This brings the implementation in line with Laravel's Eloquent resources, which receive the request to theirtoArray()
method. The slight difference is our implementation allows the request to benull
- this is to cover encoding resources outside of HTTP requests, e.g. queued broadcasting. When upgrading, you will need to either delete resource classes (as they are now optional), or update the method signatures on any classes you are retaining.
Fixed
- #3 Example server registration in the published configuration file prevented developer from creating a
v1
server after adding this package to their Laravel application. - Package discovery for sub-packages that have service providers now works correctly.
Removed
- BREAKING The
Arr
schema field has been removed - use the newArrayList
orArrayHash
fields instead. - BREAKING The
uri
method on resource and relationship routes has been removed:- The resource type URI can now be set on the resource's schema (using the
$uriType
property). - Relationship URIs are now set on the schema field for the relationship (via the
withUriFieldName
method).
- The resource type URI can now be set on the resource's schema (using the