feat: extension upgrade tool for 2.0 (#42)

* chore: first iteration (frontend changes)

* fix: improvements

* fix: improvements

* fix: improvements

* fix: improvements

* feat: backend changes

* feat: JSON:API migration help

* feat: search api migration

* chore: visual improvements

* feat: continue

* chore: improvements

* fix: allow proprietary license (#44)

* chore: improvements

* chore: improvements

* chore: improvements

* chore: improvements

* chore: improvements

* chore: improvements

* chore: improvements

* chore: improvements

* chore: improvements

* chore: improvements

* chore: improvements

* chore: improvements

* chore: improvements

* chore: improvements

* chore: improvements

* feat: intervention/image

* chore: improvements

README.md

@@ -51,7 +51,7 @@ $ npm install -g @flarum/cli
 $ flarum-cli COMMAND
 running command...
 $ flarum-cli (-v|--version|version)
-@flarum/cli/3.0.0 linux-x64 node-v16.20.2
+@flarum/cli/3.0.0 linux-x64 node-v18.19.1
 $ flarum-cli --help [COMMAND]
 USAGE
   $ flarum-cli COMMAND

boilerplate/skeleton/extension/gitignore

@@ -4,6 +4,7 @@ composer.phar
 
 .DS_Store
 Thumbs.db
+tests/.phpunit.cache
 tests/.phpunit.result.cache
 /tests/integration/tmp
 .vagrant

boilerplate/skeleton/extension/js/package.json

@@ -7,9 +7,9 @@
   "dependencies": {
   },
   "devDependencies": {
-    "@flarum/jest-config": "^2.0.0",
+    "@flarum/jest-config": "^1.0.1",
     "@flarum/prettier-config": "^1.0.0",
-    "flarum-tsconfig": "^1.0.2",
+    "flarum-tsconfig": "^2.0.0",
     "flarum-webpack-config": "^3.0.0",
     "prettier": "^2.5.1",
     "typescript": "^4.5.4",

boilerplate/skeleton/extension/js/src/admin/index.ts

@@ -2,6 +2,6 @@ import app from 'flarum/admin/app';
 
 export { default as extend } from './extend';
 
-app.initializers.add('<%= params.packageName %>', () => {
+app.initializers.add('<%= params.extensionId %>', () => {
   console.log('[<%= params.packageName %>] Hello, admin!');
 });

boilerplate/skeleton/extension/js/src/common/index.ts

@@ -1,5 +1,5 @@
 import app from 'flarum/common/app';
 
-app.initializers.add('<%= params.packageName %>-common', () => {
+app.initializers.add('<%= params.extensionId %>-common', () => {
   console.log('[<%= params.packageName %>] Hello, forum and admin!');
 });

boilerplate/skeleton/extension/js/src/forum/index.ts

@@ -2,6 +2,6 @@ import app from 'flarum/forum/app';
 
 export { default as extend } from './extend';
 
-app.initializers.add('<%= params.packageName %>', () => {
+app.initializers.add('<%= params.extensionId %>', () => {
   console.log('[<%= params.packageName %>] Hello, forum!');
 });

boilerplate/skeleton/extension/locale/en.yml

@@ -1,6 +1,6 @@
 <%= params.extensionId %>:
   # For more details on the format
-  # Checkout https://docs.flarum.org/extend/i18n/#appendix-a-standard-key-format
+  # Checkout https://docs.flarum.org/2.x/extend/i18n/#appendix-a-standard-key-format
   admin:
     my_cool_key: My Cool Key
 

boilerplate/skeleton/extension/tests/phpunit.integration.xml

@@ -1,21 +1,19 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <phpunit
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-    xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.3/phpunit.xsd"
+    xsi:noNamespaceSchemaLocation="../vendor/phpunit/phpunit/phpunit.xsd"
     backupGlobals="false"
-    backupStaticAttributes="false"
+    cacheDirectory=".phpunit.cache"
+    backupStaticProperties="false"
     colors="true"
-    convertErrorsToExceptions="true"
-    convertNoticesToExceptions="true"
-    convertWarningsToExceptions="true"
     processIsolation="true"
     stopOnFailure="false"
 >
-    <coverage processUncoveredFiles="true">
+    <source>
         <include>
             <directory suffix=".php">../src/</directory>
         </include>
-    </coverage>
+    </source>
     <testsuites>
         <testsuite name="Flarum Integration Tests">
             <directory suffix="Test.php">./integration</directory>

boilerplate/skeleton/extension/tests/phpunit.unit.xml

@@ -1,27 +1,22 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <phpunit
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-    xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.3/phpunit.xsd"
+    xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/10.5/phpunit.xsd"
     backupGlobals="false"
-    backupStaticAttributes="false"
+    cacheDirectory=".phpunit.cache"
+    backupStaticProperties="false"
     colors="true"
-    convertErrorsToExceptions="true"
-    convertNoticesToExceptions="true"
-    convertWarningsToExceptions="true"
     processIsolation="false"
     stopOnFailure="false"
 >
-    <coverage processUncoveredFiles="true">
+    <source>
         <include>
             <directory suffix=".php">../src/</directory>
         </include>
-    </coverage>
+    </source>
     <testsuites>
         <testsuite name="Flarum Unit Tests">
             <directory suffix="Test.php">./unit</directory>
         </testsuite>
     </testsuites>
-    <listeners>
-        <listener class="\Mockery\Adapter\Phpunit\TestListener" />
-    </listeners>
 </phpunit>

boilerplate/stubs/backend/advanced-api-resource.php

@@ -0,0 +1,85 @@
+<?php
+
+namespace <%= classNamespace %>;
+
+use Flarum\Api\Context;
+use Flarum\Api\Endpoint;
+use Flarum\Api\Resource;
+use Flarum\Api\Schema;<% if (modelClassName) { %>
+use Flarum\Api\Sort\SortColumn;
+use <%= modelClass %>;
+use Illuminate\Database\Eloquent\Builder;<% } %>
+use Tobyz\JsonApiServer\Context as OriginalContext;
+
+/**
+ * @extends <% if (modelClassName) { %>Resource\AbstractDatabaseResource<<%= modelClassName %>><% } else { %>Resource\AbstractResource<object><% } %>
+ */
+class <%= className %> extends <% if (modelClassName) { %>Resource\AbstractDatabaseResource<% } else { %>Resource\AbstractResource<% if (interfaces.length > 0) %> implements <%= interfaces.join(', ') %><% } %>
+{
+    public function type(): string
+    {
+        return '<%= modelType %>';
+    }<% if (modelClassName) { %>
+
+    public function model(): string
+    {
+        return <%= modelClassName %>::class;
+    }
+
+    public function scope(Builder $query, OriginalContext $context): void
+    {
+        $query->whereVisibleTo($context->getActor());
+    }<% } %>
+
+    public function endpoints(): array
+    {
+        return [<% if (endpoints.includes('create')) { %>
+            Endpoint\Create::make()<% if (modelClassName) { %>
+                ->can('create<%= modelClassName %>'),<% } %><% } %><% if (endpoints.includes('update')) { %>
+            Endpoint\Update::make()
+                ->can('update'),<% } %><% if (endpoints.includes('delete')) { %>
+            Endpoint\Delete::make()
+                ->can('delete'),<% } %><% if (endpoints.includes('show')) { %>
+            Endpoint\Show::make()
+                ->authenticated(),<% } %><% if (endpoints.includes('list')) { %>
+            Endpoint\Index::make()
+                ->paginate(),<% } %>
+        ];
+    }
+
+    public function fields(): array
+    {
+        return [
+
+            /**
+             * @todo migrate logic from old serializer and controllers to this API Resource.
+             * @see https://docs.flarum.org/2.x/extend/api#api-resources
+             */
+
+            // Example:
+            Schema\Str::make('name')
+                ->requiredOnCreate()
+                ->minLength(3)
+                ->maxLength(255)
+                ->writable(),
+
+<% (relations || []).forEach(([name,type]) => { %>
+            Schema\Relationship\<% if (type === 'hasOne') { %>ToOne<% } else { %>ToMany<% } %>::make('<%= name %>')
+                ->includable()
+                // ->inverse('?') // the inverse relationship name if any.
+                ->type('<%= name %>s'), // the serialized type of this relation (type of the relation model's API resource).<% }) %>
+        ];
+    }<% if (modelClassName) { %>
+
+    public function sorts(): array
+    {
+        return [
+            // SortColumn::make('createdAt'),
+        ];
+    }<% } else { %>
+
+    public function getId(object $model, OriginalContext $context): string
+    {
+        return $model->id;
+    }<% } %>
+}

boilerplate/stubs/backend/api-resource.php

@@ -52,9 +52,10 @@ public function fields(): array
         return [
 
             /**
-             * @see https://docs.flarum.org/extend/api
+             * @see https://docs.flarum.org/2.x/extend/api#api-resources
              */
 
+            // Example:
             Schema\Str::make('name')
                 ->requiredOnCreate()
                 ->minLength(3)

boilerplate/stubs/backend/command.php

@@ -15,7 +15,7 @@ protected function configure()
 
     protected function fire(): int
     {
-        // See https://docs.flarum.org/extend/console.html#console and
+        // See https://docs.flarum.org/2.x/extend/console.html#console and
         // https://symfony.com/doc/current/console.html#configuring-the-command for more information.
     }
 }

boilerplate/stubs/backend/event-listener.php

@@ -9,6 +9,6 @@ class <%= className %>
     public function handle(<%= eventClassName %> $event)
     {
         // Add logic to handle the event here.
-        // See https://docs.flarum.org/extend/backend-events.html for more information.
+        // See https://docs.flarum.org/2.x/extend/backend-events.html for more information.
     }
 }

boilerplate/stubs/backend/filter.php

@@ -19,11 +19,6 @@ public function getFilterKey(): string
     }
 
     public function filter(SearchState $state, string|array $value, bool $negate): void
-    {
-        $this->constrain($state->getQuery(), $state->getActor(), $negate);
-    }
-
-    protected function constrain(Builder $query, User $actor, bool $negate): void
     {
         // @TODO: implement filter logic
     }

boilerplate/stubs/backend/integration-test.php

@@ -3,8 +3,11 @@
 namespace <%= classNamespace %>;
 
 use Carbon\Carbon;
+use Flarum\Discussion\Discussion;
 use Flarum\Testing\integration\RetrievesAuthorizedUsers;
 use Flarum\Testing\integration\TestCase;
+use Flarum\User\User;
+use PHPUnit\Framework\Attributes\Test;
 
 class <%= className %> extends TestCase
 {
@@ -17,18 +20,18 @@ protected function setUp(): void
         $this->extension('<%= extensionId %>');
 
         $this->prepareDatabase([
-            'users' => [
-                ['id' => 1, 'username' => 'Muralf', 'email' => 'muralf@machine.local', 'is_email_confirmed' => 1],
+            User::class => [
+                ['id' => 3, 'username' => 'Muralf', 'email' => 'muralf@machine.local', 'is_email_confirmed' => 1],
             ],
-            'discussions' => [
-                ['id' => 1, 'title' => __CLASS__, 'created_at' => Carbon::now(), 'last_posted_at' => Carbon::now(), 'user_id' => 1, 'first_post_id' => 1, 'comment_count' => 1],
+            Discussion::class => [
+                ['id' => 1, 'title' => __CLASS__, 'created_at' => Carbon::now(), 'last_posted_at' => Carbon::now(), 'user_id' => 3, 'first_post_id' => 1, 'comment_count' => 1],
             ],
         ]);
     }
 
-    /** @test */
-    public function test_works()
+    #[Test]
+    public function works_as_expected()
     {
-        // See https://docs.flarum.org/extend/testing.html#backend-tests for more information.
+        // See https://docs.flarum.org/2.x/extend/testing.html#backend-tests for more information.
     }
 }

boilerplate/stubs/backend/job.php

@@ -2,22 +2,17 @@
 
 namespace <%= classNamespace %>;
 
-use Illuminate\Bus\Queueable;
-use Illuminate\Contracts\Queue\ShouldQueue;
-use Illuminate\Queue\SerializesModels;
+use Flarum\Queue\AbstractJob;
 
-class <%= className %> implements ShouldQueue
+class <%= className %>
 {
-    use Queueable;
-    use SerializesModels;
-
     public function __construct(
-
+        //
     ) {
     }
 
     public function handle()
     {
-        // See https://laravel.com/docs/10.x/queues for more information.
+        // See https://laravel.com/docs/11.x/queues for more information.
     }
 }

boilerplate/stubs/backend/model.php

@@ -8,7 +8,7 @@
 
 class <%= className %> extends AbstractModel
 {
-    // See https://docs.flarum.org/extend/models.html#backend-models for more information.
+    // See https://docs.flarum.org/2.x/extend/models.html#backend-models for more information.
     <% if (tableName) { %>
     protected $table = '<%= tableName %>';<% } %>
 }

boilerplate/stubs/backend/notification-blueprint.php

@@ -4,9 +4,11 @@
 
 use Flarum\Database\AbstractModel;
 use Flarum\Notification\Blueprint\BlueprintInterface;
+use Flarum\Notification\AlertableInterface;
+// use Flarum\Notification\MailableInterface;
 use Flarum\User\User;
 
-class <%= className %> implements BlueprintInterface
+class <%= className %> implements BlueprintInterface, AlertableInterface/*, MailableInterface*/
 {
     public function __construct(
 

boilerplate/stubs/backend/policy.php

@@ -10,6 +10,6 @@ class <%= className %> extends AbstractPolicy
 {
     public function can(User $actor, string $ability, <%= modelClassName %> $model)
     {
-        // See https://docs.flarum.org/extend/authorization.html#custom-policies for more information.
+        // See https://docs.flarum.org/2.x/extend/authorization.html#custom-policies for more information.
     }
 }

boilerplate/stubs/backend/service-provider.php

@@ -9,7 +9,7 @@ class <%= className %> extends AbstractServiceProvider
 {
     public function register()
     {
-        // See https://docs.flarum.org/extend/service-provider.html#service-provider for more information.
+        // See https://docs.flarum.org/2.x/extend/service-provider.html#service-provider for more information.
     }
 
     public function boot(Container $container)

boilerplate/stubs/backend/validator.php

@@ -10,6 +10,6 @@ class <%= className %> extends AbstractValidator
      * {@inheritdoc}
      */
     protected $rules = [
-        // See https://laravel.com/docs/10.x/validation#available-validation-rules for more information.
+        // See https://laravel.com/docs/11.x/validation#available-validation-rules for more information.
     ];
 }

boilerplate/stubs/frontend/component.js

@@ -16,7 +16,7 @@ export default class <%= className %> extends Component {
   view() {
     return (
       <div className="<%= className %>">
-        // See https://docs.flarum.org/extend/frontend.html#components for more information.
+        {/* See https://docs.flarum.org/2.x/extend/frontend.html#components for more information. */}
       </div>
     );
   }