Upgrade tool

README.md

@@ -26,8 +26,6 @@ Scribe helps you generate API documentation for humans from your Laravel/Lumen/[
 ## Documentation
 Check out the documentation at [scribe.knuckles.wtf/laravel](http://scribe.knuckles.wtf/laravel).
 
-v2 docs (PHP 7.2+, not actively maintained) are at [scribe.rtfd.io](http://scribe.rtfd.io).
-
 If you're coming from `mpociot/laravel-apidoc-generator`, there's a [migration guide](https://scribe.knuckles.wtf/laravel/migrating-apidoc).
 
 ## Contributing

config/scribe.php

@@ -314,22 +314,22 @@ INTRO
 
         /*
          * By default, Scribe will sort groups alphabetically, and endpoints in the order their routes are defined.
-         * You can customise that by listing the groups, subgroups and endpoints here in the order you want them.
+         * You can override this by listing the groups, subgroups and endpoints here in the order you want them.
          *
          * Any groups, subgroups or endpoints you don't list here will be added as usual after the ones here.
-         * If an endpoint/subgroups is listed under a group it doesn't belong in, it will be ignored.
+         * If an endpoint/subgroup is listed under a group it doesn't belong in, it will be ignored.
          * Note: you must include the initial '/' when writing an endpoint.
          */
         'order' => [
-            // 'This group comes first',
-            // 'This group comes next' => [
-            //     'POST /this-endpoint-comes-first',
-            //     'GET /this-endpoint-comes-next',
+            // 'This group will come first',
+            // 'This group will come next' => [
+            //     'POST /this-endpoint-will-comes-first',
+            //     'GET /this-endpoint-will-comes-next',
             // ],
-            // 'This group comes third' => [
-            //     'This subgroup comes first' => [
-            //         'GET /this-other-endpoint-comes-first',
-            //         'GET /this-other-endpoint-comes-next',
+            // 'This group will come third' => [
+            //     'This subgroup will come first' => [
+            //         'GET /this-other-endpoint-will-comes-first',
+            //         'GET /this-other-endpoint-will-comes-next',
             //     ]
             // ]
         ],

src/Commands/GenerateDocumentation.php

@@ -41,6 +41,12 @@ class GenerateDocumentation extends Command
     {
         $this->bootstrap();
 
+        if (!empty($this->docConfig->get("default_group"))) {
+            $this->warn("It looks like you just upgraded to Scribe v4.");
+            $this->warn("Please run the upgrade command first: `php artisan scribe:upgrade`.");
+            exit(1);
+        }
+
         $groupedEndpointsInstance = $groupedEndpointsFactory->make($this, $routeMatcher, $this->configName);
 
         $userDefinedEndpoints = Camel::loadUserDefinedEndpoints(Camel::camelDir($this->configName));
@@ -187,7 +193,7 @@ class GenerateDocumentation extends Command
             $upgrader = Upgrader::ofConfigFile("config/{$this->configName}.php", __DIR__ . '/../../config/scribe.php')
                 ->dontTouch(
                     'routes', 'example_languages', 'database_connections_to_transact', 'strategies', 'laravel.middleware',
-                    'postman.overrides', 'openapi.overrides'
+                    'postman.overrides', 'openapi.overrides', 'groups'
                 );
             $changes = $upgrader->dryRun();
             if (!empty($changes)) {

src/Commands/Upgrade.php

@@ -7,47 +7,73 @@ use Shalvah\Upgrader\Upgrader;
 
 class Upgrade extends Command
 {
-    protected $signature = "scribe:upgrade {--dry-run}";
+    protected $signature = "scribe:upgrade {--dry-run : Print the changes that will be made, without actually making them}
+                            {--config=scribe : choose which config file to use}
+                            ";
 
     protected $description = '';
 
     public function handle(): void
     {
-        $oldConfig = config('scribe');
-        $upgrader = Upgrader::ofConfigFile('config/scribe.php', __DIR__ . '/../../config/scribe.php')
+        $configName = $this->option('config');
+        if (!($oldConfig = config($configName))) {
+            $this->error("The specified config (config/{$configName}.php) doesn't exist.");
+            return;
+        }
+
+        if (array_key_exists("interactive", $oldConfig)) {
+            $this->error("This upgrade tool is for upgrading from Scribe v3 to v4, but it looks like you're coming from v2.");
+            $this->error("Please install v3 and follow its upgrade guide first.");
+            return;
+        }
+
+        $this->info("Welcome to the Scribe v3 to v4 upgrader.");
+        $this->line("Checking for config file changes...");
+
+        $upgrader = Upgrader::ofConfigFile("config/$configName.php", __DIR__ . '/../../config/scribe.php')
             ->dontTouch('routes', 'laravel.middleware', 'postman.overrides', 'openapi.overrides',
                 'example_languages', 'database_connections_to_transact', 'strategies')
-            ->move('interactive', 'try_it_out.enabled')
             ->move('default_group', 'groups.default')
             ->move('faker_seed', 'examples.faker_seed');
 
         $changes = $upgrader->dryRun();
         if (empty($changes)) {
-            $this->info("No changes needed! Looks like you're all set.");
-            return;
-        }
+            $this->info("✔ No config file changes needed.");
+        } else {
+            $this->info('The following changes will be made to your config file:');
+            $this->newLine();
+            foreach ($changes as $change) {
+                $this->line($change["description"]);
+            }
 
-        $this->info('The following changes will be made to your config file:');
+            if (!($this->option('dry-run'))) {
+                $upgrader->upgrade();
+                $this->info("✔ Upgraded your config file. Your old config is backed up at config/$configName.php.bak.");
+            }
+        }
         $this->newLine();
-        foreach ($changes as $change) {
-            $this->info($change["description"]);
-        }
 
-        if ($this->option('dry-run')) {
-            return;
+        if ($this->confirm("Do you have any custom strategies?")) {
+            $this->line('1. Add a new property <info>public ?ExtractedEndpointData $endpointData;</info>.');
+            $this->line('2. Replace the <info>array $routeRules</info> parameter in __invoke() with <info>array $routeRules = []</info> .');
         }
+        $this->newLine();
 
-        $upgrader->upgrade();
-
-        if (!empty($oldConfig["continue_without_database_transactions"])) {
-            $this->warn(
-                '`continue_without_database_transactions` was deprecated in 2.4.0. Your new config file now uses `database_connections_to_transact`.'
-                );
+        if ($this->confirm("Did you customize the Blade templates used by Scribe?")) {
+            $this->warn('A few minor changes were made to the templates. See the release announcement for details.');
         }
+        $this->newLine();
+
+        $this->line("Scribe now supports PHP 8 attributes for annotations. "
+            . "You can use both, but we recommend switching to attributes (see the docs).");
+        if ($this->confirm("Would you like help in replacing your docblock tags with attributes?")) {
+            $this->warn('Install our Rector package knuckleswtf/scribe-rector-t2a and run it.');
+        }
+        $this->warn("For attributes to work, you need to add the attribute strategies to your config file. See the release announcement for details.");
 
         $this->newLine();
-        $this->info("✔ Upgraded your config file. Your old config is backed up at config/scribe.php.bak.");
-        $this->info("Don't forget to check out the changelog or release announcement for new features!");
+        $this->info("✔ Done.");
+        $this->line("See the release announcement at <href=https://scribe.knuckles.wtf/v4>http://scribe.knuckles.wtf/v4</> for the full upgrade guide!");
     }
 
 }