Skip to content

Commit ba5add1

Browse files
lindyhopchrislindyhopchris
committed
Merge branch 'release/5.0.0'
2 parents ceff1ee + 1e28051 commit ba5add1

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

57 files changed

+23672
-690
lines changed

‎CHANGELOG.md

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Change Log
2+
3+
All notable changes to this project will be documented in this file. This project adheres to
4+
[Semantic Versioning](http://semver.org/) and [this changelog format](http://keepachangelog.com/).
5+
6+
## Unreleased
7+
8+
## [5.0.0] - 2025-02-24
9+
10+
### Added
11+
12+
- New 5.x chapters replicated from 4.x.
13+
- Reference Laravel 11 and 12 support in 5.x docs.
14+
- Added details on _Gate Responses_ to the authorization chapter.
15+
16+
## [4.1.1] - 2024-10-26
17+
18+
### Fixed
19+
20+
- Add missing `favicon.ico` and `robots.txt` to the public folder.

‎docs/.vitepress/5.x.js

+114
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
import prefix from './prefix';
2+
3+
export default (base) => [
4+
{
5+
text: 'Getting Started',
6+
collapsed: false,
7+
items: prefix(base, 'getting-started', [
8+
{text: 'Installation', link: ''},
9+
{text: 'Upgrade Guide', link: 'upgrade'},
10+
{text: 'Core Concepts', link: 'core-concepts'},
11+
{text: 'Directory Structure', link: 'directory-structure'},
12+
]),
13+
},
14+
{
15+
text: 'Tutorial',
16+
collapsed: true,
17+
items: prefix(base, 'tutorial', [
18+
{text: '1. Getting Started', link: ''},
19+
{text: '2. Models', link: '02-models'},
20+
{text: '3. Server and Schemas', link: '03-server-and-schemas'},
21+
{text: '4. Relationships', link: '04-relationships'},
22+
{text: '5. Creating Resources', link: '05-creating-resources'},
23+
{text: '6. Modifying Resources', link: '06-modifying-resources'},
24+
{text: '7. Deleting Resources', link: '07-deleting-resources'},
25+
{text: '8. Fetching Resources', link: '08-fetching-resources'},
26+
]),
27+
},
28+
{
29+
text: 'Servers',
30+
collapsed: false,
31+
items: prefix(base, 'servers', [
32+
{text: 'The Basics', link: ''},
33+
{text: 'Events', link: 'events'},
34+
]),
35+
},
36+
{
37+
text: 'Schemas',
38+
collapsed: false,
39+
items: prefix(base, 'schemas', [
40+
{text: 'The Basics', link: ''},
41+
{text: 'Identifier', link: 'identifier'},
42+
{text: 'Attributes', link: 'attributes'},
43+
{text: 'Relationships', link: 'relationships'},
44+
{text: 'Eager Loading', link: 'eager-loading'},
45+
{text: 'Sorting', link: 'sorting'},
46+
{text: 'Pagination', link: 'pagination'},
47+
{text: 'Filters', link: 'filters'},
48+
{text: 'Soft Deleting', link: 'soft-deleting'},
49+
]),
50+
},
51+
{
52+
text: 'Routing',
53+
collapsed: false,
54+
items: prefix(base, 'routing', [
55+
{text: 'Routing', link: ''},
56+
{text: 'Controllers', link: 'controllers'},
57+
{text: 'Writing Actions', link: 'writing-actions'},
58+
{text: 'Custom Actions', link: 'custom-actions'},
59+
]),
60+
},
61+
{
62+
text: 'Requests',
63+
collapsed: false,
64+
items: prefix(base, 'requests', [
65+
{text: 'The Basics', link: ''},
66+
{text: 'Authorization', link: 'authorization'},
67+
{text: 'JSON:API Compliance', link: 'compliance'},
68+
{text: 'Resources', link: 'resources'},
69+
{text: 'Query Parameters', link: 'query-parameters'},
70+
]),
71+
},
72+
{
73+
text: 'Responses',
74+
collapsed: false,
75+
items: prefix(base, 'responses', [
76+
{text: 'JSON:API Documents', link: ''},
77+
{text: 'Errors', link: 'errors'},
78+
]),
79+
},
80+
{
81+
text: 'API Resources',
82+
collapsed: true,
83+
items: prefix(base, 'resources', [
84+
{text: 'The Basics', link: ''},
85+
{text: 'Attributes', link: 'attributes'},
86+
{text: 'Relationships', link: 'relationships'},
87+
{text: 'Meta', link: 'meta'},
88+
{text: 'Links', link: 'links'},
89+
]),
90+
},
91+
{
92+
text: 'Digging Deeper',
93+
collapsed: false,
94+
items: prefix(base, 'digging-deeper', [
95+
{text: 'Artisan Console', link: 'artisan'},
96+
{text: 'Countable', link: 'countable'},
97+
{text: 'Localisation', link: 'localisation'},
98+
{text: 'Proxies', link: 'proxies'},
99+
{text: 'Non-Eloquent Models', link: 'non-eloquent'},
100+
{text: 'Polymorphic to Many', link: 'polymorphic-to-many'},
101+
]),
102+
},
103+
{
104+
text: 'Testing',
105+
collapsed: false,
106+
items: prefix(base, 'testing', [
107+
{text: 'Getting Started', link: ''},
108+
{text: 'Resources', link: 'resources'},
109+
{text: 'Relationships', link: 'relationships'},
110+
{text: 'Requests', link: 'requests'},
111+
{text: 'Assertions', link: 'assertions'},
112+
]),
113+
},
114+
];

‎docs/.vitepress/config.mts

+4-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
import {defineConfig} from 'vitepress';
2+
import v5 from './5.x';
23
import v4 from './4.x';
34
import v3 from './3.x';
45
import v2 from './2.x';
@@ -14,6 +15,7 @@ export default defineConfig({
1415
{
1516
text: 'Version',
1617
items: [
18+
{text: '5.x', link: '/5.x/'},
1719
{text: '4.x', link: '/4.x/'},
1820
{text: '3.x', link: '/3.x/'},
1921
{text: '2.x', link: '/2.x/'},
@@ -23,6 +25,7 @@ export default defineConfig({
2325
],
2426

2527
sidebar: {
28+
'/5.x/': v5('/5.x'),
2629
'/4.x/': v4('/4.x'),
2730
'/3.x/': v3('/3.x'),
2831
'/2.x/': v2('/2.x'),
@@ -42,7 +45,7 @@ export default defineConfig({
4245

4346
footer: {
4447
message: 'Released under the MIT License.',
45-
copyright: 'Copyright © 2024 Cloud Creativity Ltd',
48+
copyright: 'Copyright © 2025 Cloud Creativity Ltd',
4649
},
4750

4851
outline: 'deep',

‎docs/5.x/digging-deeper/artisan.md

+216
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,216 @@
1+
# Artisan Console
2+
3+
## Generators
4+
5+
Laravel JSON:API ships with a comprehensive set of generators, so that
6+
you can easily create the classes required by the implementation.
7+
These are referred to in the relevant chapters, but a comprehensive
8+
list is provided here for reference.
9+
10+
:::tip
11+
Many generators are shown with the `--server` option. You can omit this
12+
option if you only have one server registered in your `jsonapi.servers`
13+
configuration array.
14+
15+
If you have more than one server, you **MUST** provide the `--server`
16+
option to specify which server the class is being generated for.
17+
:::
18+
19+
### Controller
20+
21+
To generate a JSON:API controller, use the `jsonapi:controller` command:
22+
23+
```bash
24+
php artisan jsonapi:controller Api/V1/PostController
25+
```
26+
27+
This will generate the following controller:
28+
`App\Http\Controllers\Api\V1\PostController`.
29+
30+
Use the `--force` option if you want to overwrite an existing controller.
31+
32+
### Filter
33+
34+
To generate a JSON:API filter, use the `jsonapi:filter` command:
35+
36+
```bash
37+
php artisan jsonapi:filter MyCustomFilter
38+
```
39+
40+
This will generate the following filter:
41+
`App\JsonApi\Filters\MyCustomFilter`.
42+
43+
Use the `--force` option if you want to overwrite an existing filter.
44+
45+
### Query and Collection Query
46+
47+
To generate a JSON:API query parameter request, use the `jsonapi:query` command:
48+
49+
```bash
50+
php artisan jsonapi:query posts --server=v1
51+
```
52+
53+
This will generate the following query request class:
54+
`App\JsonApi\V1\Posts\PostQuery`.
55+
56+
To generate a collection query, use the `--collection` option:
57+
58+
```bash
59+
php artisan jsonapi:query posts --collection --server=v1
60+
```
61+
62+
This will generate the following query request class:
63+
`App\JsonApi\V1\Posts\PostCollectionQuery`.
64+
65+
To generate both the `PostQuery` *and* the `PostCollectionQuery`, use the
66+
`--both` option:
67+
68+
```bash
69+
php artisan jsonapi:query posts --both --server=v1
70+
```
71+
72+
And finally, use the `--force` option if you want to overwrite existing
73+
files.
74+
75+
### Resource Request
76+
77+
To generate a JSON:API resource request, use the `jsonapi:request` command:
78+
79+
```bash
80+
php artisan jsonapi:request posts --server=v1
81+
```
82+
83+
This will generate the following resource request class:
84+
`App\JsonApi\V1\Posts\PostRequest`.
85+
86+
Use the `--force` option if you want to overwrite an existing request class.
87+
88+
### Resource Requests
89+
90+
To generate a JSON:API resource request, query request and query collection
91+
request, use the `jsonapi:requests` command:
92+
93+
```bash
94+
php artisan jsonapi:requests posts --server=v1
95+
```
96+
97+
This will generate all of these classes:
98+
99+
- `App\JsonApi\V1\Posts\PostRequest`
100+
- `App\JsonApi\V1\Posts\PostQuery`
101+
- `App\JsonApi\V1\Posts\PostCollectionQuery`
102+
103+
Use the `--force` option if you need to overwrite existing files.
104+
105+
### Resource
106+
107+
To generate a JSON:API resource class, use the `jsonapi:resource` command:
108+
109+
```bash
110+
php artisan jsonapi:resource posts --server=v1
111+
```
112+
113+
This will generate the following resource class:
114+
`App\JsonApi\V1\Posts\PostResource`.
115+
116+
Use the `--force` option if you need to overwrite existing files.
117+
118+
### Schema
119+
120+
To generate a JSON:API schema class, use the `jsonapi:schema` command:
121+
122+
```bash
123+
php artisan jsonapi:schema posts --server=v1
124+
```
125+
126+
This will generate the following schema class:
127+
`App\JsonApi\V1\Posts\PostSchema`
128+
129+
By default, this generator will assume the model class that the schema
130+
refers to is the singular of the resource type. I.e. in this example,
131+
the `PostSchema` will have its `$model` property set to the `Post` model.
132+
133+
Use the `--model` option to provide a different model class, for example:
134+
135+
```bash
136+
php artisan jsonapi:schema posts --model=BlogPost --server=v1
137+
```
138+
139+
:::tip
140+
Laravel automatically detects the model namespace in your application:
141+
either the `Models` namespace or the root application namespace.
142+
143+
If you use a different convention, provide the fully-qualified model
144+
class name, starting with a `\`, for example:
145+
146+
```bash
147+
php artisan jsonapi:schema posts --model="\App\Foo\Bar\BlogPost" --server=v1
148+
```
149+
:::
150+
151+
If you are generating a schema for a [multi-resource model](proxies.md),
152+
you should use the `--proxy` option when creating a schema for a proxy class.
153+
154+
As with other commands, use the `--force` option if you need to overwrite
155+
an existing file.
156+
157+
### Server
158+
159+
To generate a JSON:API server class, use the `jsonapi:server` command:
160+
161+
```bash
162+
php artisan jsonapi:server v1
163+
```
164+
165+
This will create the following server class:
166+
`App\JsonApi\V1\Server`
167+
168+
The generator will assume that the `$baseUri` property of the server is
169+
`/api/{server_name}` - which would be `/api/v1` in the above example.
170+
To use a different base URI, use the `--uri` flag:
171+
172+
```bash
173+
php artisan jsonapi:server v1 --uri=http://api.example.com/v1
174+
```
175+
176+
Use the `--force` option to overwrite an existing server file.
177+
178+
:::tip
179+
After generating your server class, don't forget to register the class
180+
in your `jsonapi.servers` configuration array.
181+
:::
182+
183+
### Sort Field
184+
185+
To generate a JSON:API sort field class, use the `jsonapi:sort-field` command:
186+
187+
```bash
188+
php artisan jsonapi:sort-field MyCustomSort
189+
```
190+
191+
This will generate the following sort field class:
192+
`App\JsonApi\Sorting\MyCustomSort`.
193+
194+
Use the `--force` option if you want to overwrite an existing sort field.
195+
196+
## Stub Customisation
197+
198+
The console commands described in this chapter that generate classes all
199+
use *"stub"* files that are populated with values based on your input.
200+
However, you may sometimes wish to make small changes to files generated
201+
by Artisan. To accomplish this, you may use the `jsonapi:stubs` command to
202+
publish the stubs for customization:
203+
204+
```bash
205+
php artisan jsonapi:stubs
206+
```
207+
208+
The published stubs will be located within the `/stubs/jsonapi` directory in
209+
the root of your application. Any changes you make to these stubs will be
210+
reflected when you generate their corresponding classes using the
211+
commands described in this chapter.
212+
213+
:::tip
214+
Use the `--force` command option to overwrite any existing JSON:API stub
215+
files.
216+
:::

0 commit comments

Comments
 (0)