Skip to content

Commit decd07b

Browse files
SychO9SychO9
authored
docs: improve 2.x upgrade documentation (#484)
* docs: improve 2.x upgrade documentation * docs: multi cli versions * chore: improve * chore: improve
1 parent 36166df commit decd07b

17 files changed

+2124
-1650
lines changed

‎docs/extend/api.md‎

Lines changed: 97 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -415,12 +415,12 @@ public function endpoints(): array
415415
return [
416416
Endpoint\Show::make()
417417
->authenticated()
418-
->can('view'), // equivalent to $actor->can('view', $label)
418+
->can('view'), // equivalent to $actor->assertCan('view', $label)
419419
Endpoint\Create::make()
420420
->authenticated()
421-
->can('createLabel'), // equivalent to $actor->can('createLabel'),
421+
->can('createLabel'), // equivalent to $actor->assertCan('createLabel'),
422422
Endpoint\Update::make()
423-
->admin(), // equivalent to $actor->isAdmin()
423+
->admin(), // equivalent to $actor->assertAdmin()
424424
];
425425
}
426426
```
@@ -874,6 +874,12 @@ return [
874874
Schema\Str::make('customField'),
875875
Schema\Relationship\ToOne::make('customRelation')
876876
->type('customRelationType'),
877+
])
878+
->fieldsBefore('email', fn () => [
879+
Schema\Str::make('customFieldBeforeEmail'),
880+
])
881+
->fieldsAfter('email', fn () => [
882+
Schema\Str::make('customFieldAfterEmail'),
877883
]),
878884
]
879885
```
@@ -914,18 +920,43 @@ return [
914920
You can add endpoints to an existing resource through the `endpoints` method.
915921

916922
```php
923+
use Flarum\Api\Context;
917924
use Flarum\Api\Resource;
918925
use Flarum\Api\Endpoint;
919926
use Flarum\Extend;
920927

921928
return [
922929
(new Extend\ApiResource(Resource\UserResource::class))
923930
->endpoints(fn () => [
924-
Endpoint\Show::make(),
925931
Endpoint\Endpoint::make('custom')
926-
->route('GET', '/custom')
927-
->action(fn (Context $context) => 'custom'),
928-
]),
932+
->route('GET', '/{id}/custom')
933+
->action(function (Context $context) {
934+
$user = $context->model;
935+
936+
// logic...
937+
}),
938+
])
939+
->endpointsBefore('show', fn () => [
940+
Endpoint\Endpoint::make('customBeforeShow')
941+
->route('GET', '/customBeforeShow')
942+
->action(function (Context $context) {
943+
// logic ...
944+
}),
945+
])
946+
->endpointsAfter('show', fn () => [
947+
Endpoint\Endpoint::make('customAfterShow')
948+
->route('GET', '/customAfterShow')
949+
->action(function (Context $context) {
950+
// logic ...
951+
}),
952+
])
953+
->endpointsBeforeAll(fn () => [
954+
Endpoint\Endpoint::make('customBeforeAll')
955+
->route('GET', '/customBeforeAll')
956+
->action(function (Context $context) {
957+
// logic ...
958+
}),
959+
])
929960
];
930961
```
931962

@@ -1031,3 +1062,62 @@ return [
10311062

10321063
API Resources don't have to correspond to Eloquent models: you can define JSON:API resources for anything. You need to extend the [`Flarum\Api\Rsource\AbstractResource`](https://github.com/flarum/framework/blob/2.x/framework/core/src/Api/Resource/AbstractResource.php) class instead.
10331064
For instance, Flarum core uses the [`Flarum\Api\Resource\ForumResource`](hhttps://github.com/flarum/framework/blob/2.x/framework/core/src/Api/Resource/ForumResource.php) to send an initial payload to the frontend. This can include settings, whether the current user can perform certain actions, and other data. Many extensions add data to the payload by extending the fields of `ForumResource`.
1065+
1066+
## Programmatically calling an API endpoint
1067+
1068+
You can internally execute an endpoint's logic through the `Flarum\Api\JsonApi` object. For example, this is what Flarum does to immediately create the first post of a discussion:
1069+
1070+
```php
1071+
/** @var JsonApi $api */
1072+
$api = $context->api;
1073+
1074+
/** @var Post $post */
1075+
$post = $api->forResource(PostResource::class)
1076+
->forEndpoint('create')
1077+
->withRequest($context->request)
1078+
->process([
1079+
'data' => [
1080+
'attributes' => [
1081+
'content' => Arr::get($context->body(), 'data.attributes.content'),
1082+
],
1083+
'relationships' => [
1084+
'discussion' => [
1085+
'data' => [
1086+
'type' => 'discussions',
1087+
'id' => (string) $model->id,
1088+
],
1089+
],
1090+
],
1091+
],
1092+
], ['isFirstPost' => true]);
1093+
```
1094+
1095+
If you do not have access to the `Flarum\Api\Context $context` object, then you can directly inject the api object:
1096+
1097+
```php
1098+
use Flarum\Api\JsonApi;
1099+
1100+
public function __construct(
1101+
protected JsonApi $api
1102+
) {
1103+
}
1104+
1105+
public function handle(): void
1106+
{
1107+
$group = $api->forResource(GroupResource::class)
1108+
->forEndpoint('create')
1109+
->process(
1110+
body: [
1111+
'data' => [
1112+
'attributes' => [
1113+
'nameSingular' => 'test group',
1114+
'namePlural' => 'test groups',
1115+
'color' => '#000000',
1116+
'icon' => 'fas fa-crown',
1117+
]
1118+
],
1119+
],
1120+
options: ['actor' => User::find(1)]
1121+
)
1122+
}
1123+
```

‎docs/extend/cli.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,3 +14,60 @@ See the [package's readme](https://github.com/flarum/cli#readme) for information
1414
- Upgrading
1515
- Available commands
1616
- Some implementation details, if you're interested
17+
18+
## Installing Multiple CLI versions
19+
20+
To assist in upgrading extensions and maintaining compatibility with both v1 and v2 of the project, developers may need to use both versions of the CLI tool simultaneously. This guide explains how to install and manage multiple CLI versions side-by-side.
21+
22+
#### Installing Specific Versions
23+
24+
To install CLI versions 2 and 3 globally, you can alias them for easy access:
25+
26+
```bash
27+
npm install -g fl1@npm:@flarum/cli@2 --force
28+
npm install -g fl2@npm:@flarum/cli@3 --force
29+
```
30+
31+
This will allow you to use the CLI with the following commands:
32+
* `fl1` for the v2 CLI (compatible with project v1)
33+
* `fl2` for the v3 CLI (compatible with project v2)
34+
35+
To confirm the installation and version of each CLI, run:
36+
37+
```bash
38+
fl1 flarum info
39+
fl2 flarum info
40+
```
41+
42+
##### Switching Between Versions
43+
44+
If you have any of the latest v2 or v3 versions of the CLI, you can also use the following command to install the counterpart version:
45+
46+
```bash
47+
fl flarum change
48+
```
49+
50+
This will install the latest counterpart version of the CLI, allowing you to switch between them as needed. It will also set the default `fl` bin to the version you have just changed to.
51+
52+
```shell
53+
$ fl flarum info
54+
Flarum version: 2.x
55+
CLI version: 3.0.1
56+
$ fl flarum change
57+
Currently using CLI 3.x compatible with Flarum 2.x
58+
59+
✔ Switch to CLI 2.x compatible with Flarum 1.x? … yes
60+
$ fl flarum info
61+
Flarum version: 1.x
62+
CLI version: 2.0.2
63+
```
64+
65+
You will still be able to use the individual version specific bins:
66+
```bash
67+
$ fl1 flarum info
68+
Flarum version: 1.x
69+
CLI version: 2.0.2
70+
$ fl2 flarum info
71+
Flarum version: 2.x
72+
CLI version: 3.0.1
73+
```

0 commit comments

Comments
 (0)