docs: improve 2.x upgrade documentation (#484)

* docs: improve 2.x upgrade documentation * docs: multi cli versions * chore: improve * chore: improve
flarum · Nov 28, 2024 · decd07b · decd07b
1 parent 36166df
commit decd07b
Show file tree

Hide file tree

Showing 17 changed files with 2,124 additions and 1,650 deletions.
diff --git a/docs/extend/api.md b/docs/extend/api.md
@@ -415,12 +415,12 @@ public function endpoints(): array
     return [
         Endpoint\Show::make()
             ->authenticated()
-            ->can('view'), // equivalent to $actor->can('view', $label)
+            ->can('view'), // equivalent to $actor->assertCan('view', $label)
         Endpoint\Create::make()
             ->authenticated()
-            ->can('createLabel'), // equivalent to $actor->can('createLabel'),
+            ->can('createLabel'), // equivalent to $actor->assertCan('createLabel'),
         Endpoint\Update::make()
-            ->admin(), // equivalent to $actor->isAdmin()
+            ->admin(), // equivalent to $actor->assertAdmin()
     ];
 }
 ```
@@ -874,6 +874,12 @@ return [
             Schema\Str::make('customField'),
             Schema\Relationship\ToOne::make('customRelation')
                 ->type('customRelationType'),
+        ])
+        ->fieldsBefore('email', fn () => [
+            Schema\Str::make('customFieldBeforeEmail'),
+        ])
+        ->fieldsAfter('email', fn () => [
+            Schema\Str::make('customFieldAfterEmail'),
         ]),
 ]
 ```
@@ -914,18 +920,43 @@ return [
 You can add endpoints to an existing resource through the `endpoints` method.
 
 ```php
+use Flarum\Api\Context;
 use Flarum\Api\Resource;
 use Flarum\Api\Endpoint;
 use Flarum\Extend;
 
 return [
     (new Extend\ApiResource(Resource\UserResource::class))
         ->endpoints(fn () => [
-            Endpoint\Show::make(),
             Endpoint\Endpoint::make('custom')
-                ->route('GET', '/custom')
-                ->action(fn (Context $context) => 'custom'),
-        ]),
+                ->route('GET', '/{id}/custom')
+                ->action(function (Context $context) {
+                    $user = $context->model;
+
+                    // logic...
+                }),
+        ])
+        ->endpointsBefore('show', fn () => [
+            Endpoint\Endpoint::make('customBeforeShow')
+                ->route('GET', '/customBeforeShow')
+                ->action(function (Context $context) {
+                    // logic ...
+                }),
+        ])
+        ->endpointsAfter('show', fn () => [
+            Endpoint\Endpoint::make('customAfterShow')
+                ->route('GET', '/customAfterShow')
+                ->action(function (Context $context) {
+                    // logic ...
+                }),
+        ])
+        ->endpointsBeforeAll(fn () => [
+            Endpoint\Endpoint::make('customBeforeAll')
+                ->route('GET', '/customBeforeAll')
+                ->action(function (Context $context) {
+                    // logic ...
+                }),
+        ])
 ];
 ```
 
@@ -1031,3 +1062,62 @@ return [
 
 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.
 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`.
+
+## Programmatically calling an API endpoint
+
+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:
+
+```php
+/** @var JsonApi $api */
+$api = $context->api;
+
+/** @var Post $post */
+$post = $api->forResource(PostResource::class)
+    ->forEndpoint('create')
+    ->withRequest($context->request)
+    ->process([
+        'data' => [
+            'attributes' => [
+                'content' => Arr::get($context->body(), 'data.attributes.content'),
+            ],
+            'relationships' => [
+                'discussion' => [
+                    'data' => [
+                        'type' => 'discussions',
+                        'id' => (string) $model->id,
+                    ],
+                ],
+            ],
+        ],
+    ], ['isFirstPost' => true]);
+```
+
+If you do not have access to the `Flarum\Api\Context $context` object, then you can directly inject the api object:
+
+```php
+use Flarum\Api\JsonApi;
+
+public function __construct(
+    protected JsonApi $api 
+) {
+}
+
+public function handle(): void
+{
+    $group = $api->forResource(GroupResource::class)
+        ->forEndpoint('create')
+        ->process(
+            body: [
+                'data' => [
+                    'attributes' => [
+                        'nameSingular' => 'test group',
+                        'namePlural' => 'test groups',
+                        'color' => '#000000',
+                        'icon' => 'fas fa-crown',
+                    ]
+                ],
+            ],
+            options: ['actor' => User::find(1)]
+        )
+}
+```
diff --git a/docs/extend/cli.md b/docs/extend/cli.md
@@ -14,3 +14,60 @@ See the [package's readme](https://github.com/flarum/cli#readme) for information
 - Upgrading
 - Available commands
 - Some implementation details, if you're interested
+
+## Installing Multiple CLI versions
+
+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.
+
+#### Installing Specific Versions
+
+To install CLI versions 2 and 3 globally, you can alias them for easy access:
+
+```bash
+npm install -g fl1@npm:@flarum/cli@2 --force
+npm install -g fl2@npm:@flarum/cli@3 --force
+```
+
+This will allow you to use the CLI with the following commands:
+* `fl1` for the v2 CLI (compatible with project v1)
+* `fl2` for the v3 CLI (compatible with project v2)
+
+To confirm the installation and version of each CLI, run:
+
+```bash
+fl1 flarum info
+fl2 flarum info
+```
+
+##### Switching Between Versions
+
+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:
+
+```bash
+fl flarum change
+```
+
+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.
+
+```shell
+$ fl flarum info
+Flarum version: 2.x
+CLI version: 3.0.1
+$ fl flarum change
+Currently using CLI 3.x compatible with Flarum 2.x
+
+✔ Switch to CLI 2.x compatible with Flarum 1.x? … yes
+$ fl flarum info
+Flarum version: 1.x
+CLI version: 2.0.2
+```
+
+You will still be able to use the individual version specific bins:
+```bash
+$ fl1 flarum info
+Flarum version: 1.x
+CLI version: 2.0.2
+$ fl2 flarum info
+Flarum version: 2.x
+CLI version: 3.0.1
+```