Laravel Apiable Laravel Package

Added

• AssertableJsonApi::data(Closure) — scope into the data member using the full AssertableJson fluent API (where, has, missing, count, etc, dd, dump, when, tap, …)
• AssertableJsonApi::meta(Closure) — scope into meta
• AssertableJsonApi::links(Closure) — scope into links
• AssertableJsonApi::errors(Closure) — scope into errors
• AssertableJsonApi::included(Closure) — scope into included
• AssertableJsonApi::relationship(string $name, Closure) — scope into relationships.{name}.data of the current resource
• AssertableJsonApi::at(int $position, Closure $callback) — optional closure variant; when a callback is supplied the method runs assertions inside that scope and returns $this (the collection) for further chaining
• AssertableJsonApi::atRelation(Model $model, Closure $callback) — optional closure variant on atRelation
• AssertableJsonApi::assertIsJsonApiDocument() — validates the top-level JSON:API document structure (requires at least one of data/errors/meta; data and errors must not coexist; included requires data)
• Error documents (errors, no data) are now accepted by fromTestResponse and can be asserted via errors()

Changed

• AssertableJsonApi constructor is now aligned with the parent AssertableJson(array $props, ?string $path = null). All JSON:API state (id, type, attributes, relationships, included) is now derived from props via accessors instead of stored as separate fields. As a result, parent methods scope(), first(), each(), where(), has(), missing(), count(), etc(), dd(), dump(), when(), tap() are now fully functional on AssertableJsonApi instances.
• fromTestResponse no longer silently collapses a collection response to the first item. Calling hasAttribute(), hasId(), hasType(), or relationship methods directly on a collection root now operates on the root document, not the first item. Use ->at(0) to scope into a specific collection item before running those assertions.
• hasAttribute($name, $value) value comparison tightened. The old implementation used assertContains($value, $attributes) which matched the value against any attribute — regardless of key. The new implementation uses assertSame($value, $attributes[$name]) which correctly checks the exact key/value pair. Action required: any test that relied on the old loose matching (e.g. hasAttribute('subtitle', 'Hello') passing because a different key happened to hold 'Hello') needs to be corrected.
• hasAttribute($name, $value) skipping falsy values fixed. The old guard was if ($value), which skipped the value check when $value was 0, false, or ''. The guard is now if ($value !== null), so values of 0 and false are correctly asserted.
• toArray() now returns the full document props (delegating to AssertableJson::toArray()) instead of only the attributes of the current resource. Code that called ->toArray() to obtain attributes should use ->toArray()['data']['attributes'] or ->prop('data.attributes').
• hasNotAttribute($name, $value) semantics clarified. Without $value, asserts the attribute key is absent. With $value, asserts that either the key is absent or the key's value differs from $value. Previously the method always failed if the key existed, even when only checking that a specific value was not present.
• hasAttributes() now accepts both list form (['title', 'abstract'] — key existence only) and map form (['title' => 'Hello'] — key + exact value).

Fixed

• scope(), first(), each() from the parent now work correctly because the constructor matches the parent signature
• AssertableJsonApi::rootProps is threaded into child scopes so included, meta, and links are reachable from any scope depth

Added

• Apiable::modelResourceMap() to register custom JsonApiResource classes per model globally
• Apiable::jsonApiResourceFor() to resolve the registered resource class for a given model instance
• JsonApiResponse::usingResource() to override the resource class used for serialization per-response
• JsonApiResource::toApplicationJsonArray() for plain JSON serialization merging model attributes with computed ones

Fixed

• Related models in included relationships now resolve through the resource registry instead of always using the base JsonApiResource class
• Pivot relationship meta keys were not being prefixed correctly (array_walk callback was not returning the modified array); replaced with an explicit loop

Added

• Multiple scoped filters parameters values (e.g. /?filter[withStatuses]=Active&filter[withStatuses]=Archived) (#15)

Fixed

• Issue when included repeated relationships replaced others (#11)

Added

• apiable:docs command to generate API documentation from PHP attributes in Postman v2.1, Markdown/MDX, and OpenAPI 3.1 formats
• $description property to all *QueryParam attributes for documentation generation
• #[DocumentedResource], #[DocumentedEndpointSection], and #[EndpointResource] PHP attributes for annotating controllers
• OpenSoutheners\LaravelApiable\Documentation\Generator class for building resource documentation trees from registered routes
• OpenSoutheners\LaravelApiable\Http\JsonApiPaginator class exposing pagination logic as a typed static method
• Laravel 13 support

Fixed

• Handler::includesTrace() was calling env('APP_DEBUG') outside of the config directory, which returns null in production; now uses config('app.debug')
• IteratesResultsAfterQuery had leaked application-specific imports (App\Domain\Process\Models\Box\Box, App\Models\ModelForm) left over from a real project
• addAppendsToResult() instanceof JsonApiCollection check was unreachable because it was nested inside an instanceof JsonApiResource branch (since JsonApiCollection extends JsonApiResource); logic restructured to check the most-specific subtype first
• addAppendsToResult() instanceof Paginator branch was using the Paginator contract which does not declare through(); changed to AbstractPaginator
• CollectsResources::collects() was missing a return null fallback, causing PHPStan to report a missing return statement
• isScope() in ApplyFiltersToQuery was using get_parent_class() to exclude base builder methods, which could return false for unknown types; now diffs against Illuminate\Database\Eloquent\Builder::class directly, which is also more accurate
• Various PHPDoc type corrections in documentation exporters and Generator (malformed class name OpenSouthenersLaravelApiableDocumentationResource → \OpenSoutheners\LaravelApiable\Documentation\Resource)

Removed

• Laravel 11 support

Fixed

• Exceptions handler at issue #20

Added

• Appends to raw JSON responses

Fixed

• URL params getting double encoded

Fixed

• Laravel param inconsistency with paginator page number also applies to FastPaginate

Fixed

• Pagination returns wrong page name query parameter (Laravel framework is inconsistent around this)

Fixed

• Apiable::toJsonApi() given collection as input returns empty response

Fixed

• jsonApiPaginate() method typos

Fixed

• Page number resolver not properly retrieved for jsonApiPaginate() method
• Fast paginate package with new name and namespace check

Added

• Laravel 12 support

Removed

• Laravel 9 and 10 support
• PHP 8.0 and 8.1 support

Changed

• Replaced package open-southeners/laravel-helpers with open-southeners/extended-php

Fixed

• Performance degradation issue on serialisation (infinite loop on nested includeds)

Added

• Laravel 11 support

Fixed

• Raw response without pagination returning query builder

Added

• Raw response formatting to JsonApiResponse

Added

• Type generics into:
  • OpenSoutheners\LaravelApiable\Http\JsonApiResponse
  • OpenSoutheners\LaravelApiable\Http\RequestQueryObject
  • OpenSoutheners\LaravelApiable\Http\Resources\JsonApiResource
  • OpenSoutheners\LaravelApiable\Http\Resources\JsonApiCollection
  • OpenSoutheners\LaravelApiable\Contracts\ViewQueryable
  • OpenSoutheners\LaravelApiable\Contracts\ViewableBuilder

Added

• Handler::withHeader (used as apiable()->jsonApiRenderable()->withHeader) to add headers to JSON errors

Added

• Includes relationships counts with tags_count (needs to end with _count). E.g:

JsonApiResponse::using(Post::class)->allowInclude(['tags_count']);

// Then request this with ?include=tags_count

Fixed

• Some IDEs getting confused with returning self types in traits (replaced to static)

Changed

• Fix open-southeners/laravel-helpers utilities package version constrain so other packages can use similar versions under the same major release

Fixed

• Query withCount method usage with apiable is replacing the underlying added selects for these counts

Fixed

• Force formatting always coming through even thought is not forced by config

Changed

• Config file now with response.formatting with type and force sub-items as options

Fixed

• Force formatting for Inertia based apps (now can use Apiable::forceResponseFormatting())

Fixed

• Non existing class ForceAppendAttribute when reading controller attributes

Added

• Default sorts using JsonApiResponse::applyDefaultSort method or OpenSoutheners\LaravelApiable\Attributes\ApplyDefaultSort attribute
• Default filters using JsonApiResponse::applyDefaultFilter method or OpenSoutheners\LaravelApiable\Attributes\ApplyDefaultFilter attribute
• Default formatting bypass using JsonApiResponse::forceFormatting method

Changed

• Request::wantsJsonApi() only looks at Accept header, not looking for Content-Type one anymore
• Now all requests can send a different Accept header if they want a diffent response formatting. For e.g. sending Accept: application/json will get raw JSON response. Default being configured in the config/apiable.php make sure to publish or update it

Added

• Sorts now accepts relationships (for e.g. /posts?sort=tags.created_at)

Fixed

• PHP deprecation warning on string vars interpolation

Fixed

• JsonApiResponse using viewable builder (query scopes to filter by view permission) didn't send any user as first parameter

Added

• JsonApiResponse::paginateUsing(fn ($query) => $query->simplePaginate()) method to customise pagination used in JSON API responses.

Changed

• Pivot attributes now aren't configurable through config/apiable.php, they will always be applied as long as there are any under the relationship. They can be found under relationships.data.*.meta and keyed following the same as before: pivot_name_pivot_attribute (pivot_name being customisable through: https://laravel.com/docs/10.x/eloquent-relationships#customizing-the-pivot-attribute-name)

Fixed

• Missing import to make work pivot attributes functionality

Added

• include_pivot_attributes config option to optionally add pivot attributes to the relationships data (default to false to match previous functionality). Pivot data will be added as pivot_name_pivot_attribute (remember if you're using as it will use this one: https://laravel.com/docs/10.x/eloquent-relationships#customizing-the-pivot-attribute-name).

Fixed

• Added status code (401) to unauthorised responses

Fixed

• Inconsistent behaviour with Apiable::toJsonApi() returning false sometimes, now returns an API resource/collection all the time (might be a breakchange therefore this was minor release)

Fixed

• JsonApiResponse::conditionallyLoadResults() method doesn't work as expected

Fixed

• Exceptions handler using apiable()->jsonApiRenderable() now returns thrown exception headers

Added

• Backend now returns properly the Content-Type=application/vnd.api+json response header

Fixed

• Filters with negative values like filter[attr]=0 won't be filtered out

Fixed

• Apiable::jsonApiRenderable method, Handler missing import of Symfony's HttpException

Changed

• Apiable::jsonApiRenderable now accepts 2 arguments: Throwable exception & second a bool nullable withTrace, error handling redesign to properly match JSON:API & Laravel.

Added

• JsonApiResponse::conditionallyLoadResults to manage adding viewable query or not to the response

Added

• Laravel 10 support
• PHP native types

Removed

• QueryParametersValidator constants ENFORCE_VALIDATION_STRATEGY & FILTER_VALIDS_ONLY_STRATEGY, now strategy parameter is changed to a boolean instead

Fixed

• Types with static analysis

Fixed

• Error when wrong typed parameter sent to IteratesResultsAfterQuery::appendToApiResource

Fixed

• Filtering when wrong operator is present was returning exception, now ignores the operator (e.g. filter[attribute][0]=1&filter[attribute][1]=2)

Fixed

• Deprecation notice on explode second argument

Added

• forceAppendWhen method to JsonApiResponse

Fixed

• Fix PHP 8 deprecation with string variable interpolation

Fixed

• Fix issue reporting wrong status code when setup handler renderable receives a query exception: apiable()->jsonApiRenderable()

Fixed

• Fix issue reporting wrong status code when setup handler renderable receives a query exception: apiable()->jsonApiRenderable()

Fixed

• Filters values like: filter[attribute]=0 now doesn't get removed

Fixed

• PHP 8.2 deprecation warnings

Added

• PHP 8.2 support

Fixed

• Fixed OR filters with rest of filtering or SQL query affecting negatively the results

Fixed

• Fixed page[size] in request doesn't get the number of results when lower than model's $perPage (only on higher)

Fixed

• Filtering scopes were not being applied

Added

• Search (Laravel Scout) filters with allowed attributes and/or value(s): ?q=hello&q[filter][attribute]=foo or ?search=hello&search[filter][attribute]=foo

Fixed

• Empty filter without attribute: ?filter=test was throwing an error

Fixed

• Remove page parameter from pagination links when using withQuery

Changed

• Filter relationship without any value applies relationship existence filtering, now doesn't
• Filtering now handles AND/OR conditions properly
• Filtering using OR condition (filter[status]=Active,Inactive) will be fully invalidated if one member doesn't pass the validation
• RequestQueryObject::filters method now implements own logic instead of reusing Symfony's request one to be able to get AND filters with same keys (attributes) on a different array item

Removed

• withWhereHas under filtering, now all related data is loaded (until reimplemented with AND/OR conditionals...)

Fixed

• Add request query parameters to pagination links on JsonApiResponse resource collections

Fixed

• Ambiguous columns when filtering on relationships attributes (redoing it right without any regression)

Fixed

• Ambiguous columns when filtering on relationships attributes

Added

• Conditionally filter out attributes that ends with "_id" (adding config option responses.include_ids_on_attributes)
• JsonApiResponse::includingIdAttributes() method for setting responses.include_ids_on_attributes option value within an individual response

Fixed

• Fix resolveFromRoute when using invokable controller JsonApiResponse

Fixed

• JsonApiResponse::toArray returning wrong formatted JSON:API array

Fixed

• JsonApiResponse::forceAppend method fails getting model class when from query builder

Added

• requests.validate_params config option to apiable.php for enforcing validation. Requires to publish or manually copy [#7]
• Additional filter operators like gte (greater or equal than), gt (greater than), lte (lower or equal than), lt (lower than) [#5]

Changed

• Get allowed fields methods from apply query params pipeline classes moved to OpenSoutheners\LaravelApiable\Http\QueryParamsValidator
• Operators from allowed_filters included to meta data are now URL-safe
• allowed_sorts structure is now based on ['attribute' => 'allowed_direction']
• Allow filters methods/attribute now accepts array with multiple operators

Added

• Illuminate\Contracts\Support\Arrayable interface to JsonApiResponse so it can be used in Inertia responses (as an example)

Added

• OpenSoutheners\LaravelApiable\Contracts\ViewQueryable and OpenSoutheners\LaravelApiable\Contracts\ViewableBuilder classes for models & custom query builders now functional with JsonApiResponse (can be disabled by config see config/apiable.php)

⚠️ Please make sure to run php artisan vendor:publish --force --provider="OpenSoutheners\LaravelApiable\ServiceProvider" ⚠️

Fixed

• Getting wrong config keys

⚠️ Please make sure to run php artisan vendor:publish --force --provider="OpenSoutheners\LaravelApiable\ServiceProvider" ⚠️

Removed

• JsonApiResponse::list and JsonApiResponse::getOne methods as isn't the responsibility of this package to act as query repository so it makes easier to encapsulate it into repository or whatever design pattern you're using. Use JsonApiResponse::using instead sending the query as its parameter.

Added

• PHP 8 attributes for QueryParams:
  • OpenSoutheners\LaravelApiable\Attributes\FilterQueryParam
  • OpenSoutheners\LaravelApiable\Attributes\IncludeQueryParam
  • OpenSoutheners\LaravelApiable\Attributes\AppendsQueryParam
  • OpenSoutheners\LaravelApiable\Attributes\FieldsQueryParam
  • OpenSoutheners\LaravelApiable\Attributes\SortQueryParam
  • OpenSoutheners\LaravelApiable\Attributes\SearchQueryParam
• Method JsonApiResponse::from can now be non-statically called as JsonApiResponse::using (for dependency injection usage in controllers, etc)

Changed

• Config file changes. Please make sure to run php artisan vendor:publish --force --provider="OpenSoutheners\LaravelApiable\ServiceProvider"
• Constructor from JsonApiResponse now only accepts 1 optional parameter (being the query parameter removed in favor of manually setting this by calling JsonApiResponse::using method)
• Constructor from RequestQueryObject now only accepts 1 optional parameter (being the query parameter removed in favor of manually setting this by calling RequestQueryObject::setQuery method)

Added

• JsonApiResponse:forceAppend method to force appends to the final response

Changed

• JsonApiResponse::getPipelineQuery now accepts an optional callback closure & is exposed as public for repositories usage

Changed

• RequestQueryObject::allowFilter method now accepts 3 arguments (attribute, operator/values, values)

Fixed

• AllowedFilter::scopedValue method was removed and accidentally pushed onto RequestQueryObject::allowScopedFilter

Added

• Method RequestQueryObject::allows to be able to group everything in the same method call without needing to use class methods (AllowedFilters, AllowedFields, etc...)

Added

• AllowedFilter::scoped method for Laravel query scopes filters to specify the filter is not an actual attribute but a query builder scope
• enforce_scoped_names to config/apiable.php to be used so they rename scoped filters in case there are attributes with the same name on the model (remember to use vendor:publish artisan command to update the config file)
• include_allowed to config/apiable.php to be used so any JsonApiResponse will include allowed filters and sorts (like using JsonApiResponse::includeAllowedToResponse but on all requests)
• AssertableJsonApi::hasNotAttribute and AssertableJsonApi::hasNotAttributes methods for negative test assertions (counter part of AssertableJsonApi::hasAttribute and AssertableJsonApi::hasAttributes)

Fixed

• Scoped filters now can be allowed & applied to requested response
• Issue with allowAppends & allowFields sending array of attributes will wrongly parse them

Added

• Allowing fields and appends now accepts model class as for type parameter

Fixed

• Missing publishable config

Removed

• Custom transformers (out of package scope / purpose)

Fixed

• Method allowIncludes adds nested array which leads into issues

Changed

• Model setup not needed (OpenSoutheners\LaravelApiable\JsonApiOptions replaced by OpenSoutheners\LaravelApiable\Facades\Apiable::modelResourceTypeMap facade method)

Added

• Support for laravel/scout
• Support for hammerstone/fast-paginate

Fixed

• Missing autoload-dev, tests were autoloaded with the released version
• Multiple minor fixes around forwarding calls (methods)
• Apiable facade toJsonApi

Added

• Way to add multiple sorts and includes with allowSort & allowInclude methods

Added

• JsonApiResponse getOne method for parse current model instance or model key passed
• isCollection and isResource testing methods to AssertableJsonApi

Fixed

• Multiple fixes to tests & package

Changed

• Appends now needs to be sent as ?appends[type]=my_attribute,another_attribute as they're completely different from fields

Removed

• JsonApiResource::withRelations() method (bad idea, lots of possible N+1 problems to the dev-user)

Added

• Initial pre-release!