Merge branch 'develop' of github.com:cloudcreativity/laravel-json-api into develop

Author: lindyhopchris

.gitattributes

@@ -0,0 +1,8 @@
+/docs export-ignore
+/tests export-ignore
+.editorconfig export-ignore
+.gitattributes export-ignore
+.gitignore export-ignore
+.travis.yml export-ignore
+mkdocs.yml export-ignore
+phpunit.xml export-ignore

CHANGELOG.md

@@ -1,7 +1,26 @@
-[![Build Status](https://travis-ci.org/cloudcreativity/laravel-json-api.svg?branch=master)](https://travis-ci.org/cloudcreativity/laravel-json-api)
+![Tests](https://github.com/cloudcreativity/laravel-json-api/workflows/Tests/badge.svg)
 
 # cloudcreativity/laravel-json-api
 
+## Status
+
+**DO NOT USE THIS PACKAGE FOR NEW PROJECTS - USE [laravel-json-api/laravel](https://github.com/laravel-json-api/laravel)
+INSTEAD.**
+
+This package has now been rewritten, substantially improved and released as the `laravel-json-api/laravel` package.
+Documentation for the new version is available on our new website [laraveljsonapi.io](https://laraveljsonapi.io) and the
+code is now developed under the
+[Laravel JSON:API Github organisation.](https://github.com/laravel-json-api)
+
+The `cloudcreativity/laravel-json-api` package is now considered to be the *legacy* package. As we know it is in use in
+a lot of production applications, it will continue to receive bug fixes and updates for new Laravel versions. However,
+it is no longer supported for new features.
+
+If you are starting a new project, you MUST use the
+[new package `laravel-json-api/laravel`.](https://github.com/laravel-json-api/laravel)
+
+## Introduction
+
 Build feature-rich and standards-compliant APIs in Laravel.
 
 This package provides all the capabilities you need to add [JSON API](http://jsonapi.org)
@@ -38,25 +57,23 @@ The following additional features are also supported:
 From [jsonapi.org](http://jsonapi.org)
 
 > If you've ever argued with your team about the way your JSON responses should be formatted, JSON API is your
-anti-bikeshedding weapon.
+> anti-bikeshedding weapon.
 >
-> By following shared conventions, you can increase productivity, take advantage of generalized tooling, and focus
-on what matters: your application. Clients built around JSON API are able to take advantage of its features around
-efficiently caching responses, sometimes eliminating network requests entirely.
+> By following shared conventions, you can increase productivity, take advantage of generalized tooling, and focus on
+> what matters: your application. Clients built around JSON API are able to take advantage of its features around
+> efficiently caching responses, sometimes eliminating network requests entirely.
 
 For full information on the spec, plus examples, see [http://jsonapi.org](http://jsonapi.org).
 
-## Tutorial and Documentation
-
-Want a tutorial to get started? Read the
-[*How to JSON:API* Laravel tutorial.](https://howtojsonapi.com/laravel.html)
+## Documentation
 
 Full package documentation is available on
 [Read the Docs](http://laravel-json-api.readthedocs.io/en/latest/).
 
-## Demo
+## Slack
 
-A demo application is available at [here](https://github.com/cloudcreativity/demo-laravel-json-api).
+Join the Laravel JSON:API community on
+[Slack.](https://join.slack.com/t/laraveljsonapi/shared_invite/zt-e3oi2r4y-8nkmhzpKnPQViaXrkPJHtQ)
 
 ## Laravel Versions
 
@@ -73,12 +90,6 @@ A demo application is available at [here](https://github.com/cloudcreativity/dem
 Make sure you consult the [Upgrade Guide](http://laravel-json-api.readthedocs.io/en/latest/upgrade/)
 when upgrading between major or pre-release versions.
 
-## Lumen
-
-Currently we have not integrated the package with Lumen. We do not have any active projects that use Lumen,
-so if you do and can help, please let us know on
-[this issue](https://github.com/cloudcreativity/laravel-json-api/issues/61).
-
 ## License
 
 Apache License (Version 2.0). Please see [License File](LICENSE) for more information.
@@ -89,8 +100,8 @@ Installation is via `composer`. See the documentation for complete instructions.
 
 ## Contributing
 
-Contributions are absolutely welcome. Ideally submit a pull request, even more ideally with unit tests.
-Please note the following:
+Contributions are absolutely welcome. Ideally submit a pull request, even more ideally with unit tests. Please note the
+following:
 
 - **Bug Fixes** - submit a pull request against the `master` branch.
 - **Enhancements / New Features** - submit a pull request against the `develop` branch.

README.md

@@ -1,6 +1,6 @@
 <?php
-/**
- * Copyright 2020 Cloud Creativity Limited
+/*
+ * Copyright 2021 Cloud Creativity Limited
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

database/migrations/2018_10_23_000001_create_client_jobs_table.php

@@ -233,7 +233,8 @@ for Eloquent models. The relationship types available are `belongsTo`, `hasOne`,
 | `morphOne` | `hasOne` |
 | `morphMany` | `hasMany` |
 | `morphToMany` | `hasMany` |
-| `morphedByMany` | `morphMany` |
+| `morphedByMany` | `hasMany` |
+| n/a | `morphMany` |
 | n/a | `queriesOne` |
 | n/a | `queriesMany` |
 
@@ -380,8 +381,8 @@ class Adapter extends AbstractAdapter
 
 #### Morph-Many
 
-Use the JSON API `morphMany` relation for an Eloquent `morphedByMany` relation. The `morphMany` relation in effect
-*mixes* multiple different JSON API resource relationships in a single relationship.
+Use the JSON API `morphMany` relation to *mix* multiple different JSON API resource relationships in a single
+relationship.
 
 This is best demonstrated with an example. If our application has a `tags` resource that can be linked to either
 `videos` or `posts`, our `tags` adapter would define a `taggables` relation as follows:

docs/basics/adapters.md

@@ -22,8 +22,8 @@ to it.
 
 ### API Route Prefix
 
-When registering a JSON API, we automatically read the URL prefix and route name prefix from your 
-[API's URL configuration](./api#url) and apply this to the route group for your API. The URL prefix in your JSON API 
+When registering a JSON API, we automatically read the URL prefix and route name prefix from your
+[API's URL configuration](./api#url) and apply this to the route group for your API. The URL prefix in your JSON API
 config is **always** relative to the root URL on a host, i.e. from `/`.
 **This means when registering your routes, you need to ensure that no prefix has already been applied.**
 
@@ -42,7 +42,7 @@ JsonApi::register('default')->withNamespace('Api')->routes(function ($api) {
 ```
 
 > We use `withNamespace()` instead of Laravel's usual `namespace()` method because `namespace` is a
-[Reserved Keyword](http://php.net/manual/en/reserved.keywords.php). 
+[Reserved Keyword](http://php.net/manual/en/reserved.keywords.php).
 
 ## Resource Routes
 
@@ -67,6 +67,16 @@ JsonApi::register('default')->routes(function ($api) {
 });
 ```
 
+By default the resource type is used as the URI fragment: i.e. the `posts` resource will have a URI of
+`/posts`. If you want to use a different URI fragment, use the `uri()` method. In the following example,
+the resource type is `posts` but the URI will be `/blog_posts`:
+
+```php
+JsonApi::register('default')->routes(function ($api) {
+    $api->resource('posts')->uri('blog_posts');
+});
+```
+
 ## Relationship Routes
 
 The JSON API spec also defines routes for relationships on a resource type. There are two types of relationships:
@@ -87,6 +97,19 @@ JsonApi::register('default')->routes(function ($api) {
 });
 ```
 
+By default the relationship name is used as the URI fragment: i.e. for the `comments` relationship on the
+`posts` resource, the related resource URI is `/posts/{record}/comments`. To customise the URI framgent,
+use the `uri()` method. In the following example, the relationship name is `comments` but the URI
+will be `/posts/{record}/blog_comments`:
+
+```php
+JsonApi::register('default')->routes(function ($api) {
+    $api->resource('posts')->relationships(function ($relations) {
+        $relations->hasMany('comments')->uri('blog_comments');
+    });
+});
+```
+
 ### Related Resource Type
 
 When registering relationship routes, it is assumed that the resource type returned in the response is the
@@ -252,7 +275,7 @@ JsonApi::register('default')->withNamespace('Api')->routes(function ($api, $rout
 
 ### Controller Names
 
-If you call `controller()` without any arguments, we assume your controller is the camel case name version of 
+If you call `controller()` without any arguments, we assume your controller is the camel case name version of
 the resource type with `Controller` on the end. I.e. `posts` would expect `PostsController` and
 `blog-posts` would expect `BlogPostsController`. Or if your resource type was `post`,
 we would guess `PostController`.
@@ -332,7 +355,7 @@ If you are using these, you will also need to refer to the *Custom Actions* sect
 
 Also note that custom routes are registered *before* the routes defined by the JSON API specification,
 i.e. those that are added when you call `$api->resource('posts')`. You will need to ensure that your
-custom route definitions do not collide with these defined routes. 
+custom route definitions do not collide with these defined routes.
 
 > Generally we advise against registering custom routes. This is because the JSON API specification may
 have additional routes added to it in the future, which might collide with your custom routes.
@@ -396,7 +419,7 @@ does not contain an `@` symbol we add the controller name to it.
 
 Secondly, if you are defining a custom relationship route, you must use the `field` method. This takes
 the relationship name as its first argument. The inverse resource type can be specified as the second argument,
-for example: 
+for example:
 
 ```php
 JsonApi::register('default')->withNamespace('Api')->routes(function ($api) {

docs/basics/routing.md

@@ -1,6 +1,6 @@
 <?php
-/**
- * Copyright 2020 Cloud Creativity Limited
+/*
+ * Copyright 2021 Cloud Creativity Limited
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

helpers.php

@@ -1,6 +1,6 @@
 <?php
-/**
- * Copyright 2020 Cloud Creativity Limited
+/*
+ * Copyright 2021 Cloud Creativity Limited
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

resources/lang/en/errors.php

@@ -1,6 +1,6 @@
 <?php
-/**
- * Copyright 2020 Cloud Creativity Limited
+/*
+ * Copyright 2021 Cloud Creativity Limited
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

resources/lang/en/validation.php

@@ -0,0 +1,156 @@
+<?php
+/*
+ * Copyright 2021 Cloud Creativity Limited
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+return [
+
+    /*
+    |--------------------------------------------------------------------------
+    | Error Object Language Lines
+    |--------------------------------------------------------------------------
+    |
+    | The following language lines contain the default translatable members
+    | of JSON API error objects. According to the JSON API spec, the
+    | `title` and `detail` members can be localized. In addition the `code`
+    | member is also read from this package if you want to give the error
+    | a specific code.
+    |
+    | Set any value to an empty string if you do not want the member to be
+    | included in the error object.
+    |
+    | @see http://jsonapi.org/format/#errors
+    */
+
+    'unauthorized' => [
+        'title' => 'Non authentifié',
+        'detail' => '',
+        'code' => '',
+    ],
+
+    'forbidden' => [
+        'title' => 'Non autorisé',
+        'detail' => '',
+        'code' => '',
+    ],
+
+    'token_mismatch' => [
+        'title' => 'Jeton invalide',
+        'detail' => "Le jeton n'est pas valide.",
+        'code' => '',
+    ],
+
+    'member_required' => [
+        'title' => 'Document JSON API invalide',
+        'detail' => 'Le membre :member est obligatoire.',
+        'code' => '',
+    ],
+
+    'member_object_expected' => [
+        'title' => 'Document JSON API invalide',
+        'detail' => 'Le membre :member doit être un objet.',
+        'code' => '',
+    ],
+
+    'member_identifier_expected' => [
+        'title' => 'Document JSON API invalide',
+        'detail' => 'Le membre :member doit être un identifiant de ressource.',
+        'code' => '',
+    ],
+
+    'member_string_expected' => [
+        'title' => 'Document JSON API invalide',
+        'detail' => 'Le membre :member doit être une chaîne de caractères.',
+        'code' => '',
+    ],
+
+    'member_empty' => [
+        'title' => 'Document JSON API invalide',
+        'detail' => 'Le membre :member ne peut être vide.',
+        'code' => '',
+    ],
+
+    'member_field_not_allowed' => [
+        'title' => 'Document JSON API invalide',
+        'detail' => 'Le membre :member ne peut avoir de champ :field.',
+        'code' => '',
+    ],
+
+    'resource_type_not_supported' => [
+        'title' => 'Non supporté',
+        'detail' => "Le type de ressource :type n'est pas supporté par ce endpoint.",
+        'code' => '',
+    ],
+
+    'resource_type_not_recognised' => [
+        'title' => 'Non supporté',
+        'detail' => "Le type de ressource :type n'est pas reconnu.",
+        'code' => '',
+    ],
+
+    'resource_id_not_supported' => [
+        'title' => 'Non supporté',
+        'detail' => "L'identifiant de ressource :id n'est pas supporté par ce endpoint.",
+        'code' => '',
+    ],
+
+    'resource_client_ids_not_supported' => [
+        'title' => 'Non supporté',
+        'detail' => "Le type de ressource :type n'accepte pas les identifiants générés par le client.",
+        'code' => '',
+    ],
+
+    'resource_exists' => [
+        'title' => 'Conflit',
+        'detail' => 'La ressource :id existe déjà.',
+        'code' => '',
+    ],
+
+    'resource_not_found' => [
+        'title' => 'Introuvable',
+        'detail' => "La ressource spécifiée n'existe pas.",
+        'code' => '',
+    ],
+
+    'resource_field_exists_in_attributes_and_relationships' => [
+        'title' => "Document JSON API invalide",
+        'detail' => 'Le champ :field ne peut être à la fois un attribut et une relation.',
+        'code' => '',
+    ],
+
+    'resource_invalid' => [
+        'title' => 'Entité non traitable',
+        'detail' => 'Le document est correctement structuré mais contient des erreurs sémantiques.',
+        'code' => '',
+    ],
+
+    'resource_cannot_be_deleted' => [
+        'title' => 'Non supprimable',
+        'detail' => 'La ressource ne peut être supprimée.',
+        'code' => '',
+    ],
+
+    'query_invalid' => [
+        'title' => 'Paramètre de requête invalide',
+        'detail' => 'Les paramètres de la requête ne sont pas valides.',
+        'code' => '',
+    ],
+
+    'failed_validator' => [
+        'title' => 'Entité non traitable',
+        'detail' => 'Le document est correctement structuré mais contient des erreurs sémantiques.',
+        'code' => '',
+    ],
+];