Cleanup: simplify configureStrategy and add docs

config/scribe.php

@@ -3,7 +3,7 @@
 use Knuckles\Scribe\Config;
 use Knuckles\Scribe\Config\{AuthIn,ExternalTheme};
 use Knuckles\Scribe\Extracting\Strategies;
-use function Knuckles\Scribe\Config\{removeStrategies, withConfiguredStrategy};
+use function Knuckles\Scribe\Config\{removeStrategies, configureStrategy};
 
 /**
  * For documentation, use your IDE's autocomplete features, or see https://scribe.knuckles.wtf/laravel/reference/config
@@ -31,9 +31,10 @@ return Config\Factory::make(
               You can retrieve your token by visiting your dashboard and clicking <b>Generate API token</b>.
             MARKDOWN
         ),
+        // The strategies Scribe will use to extract information about your routes at each stage.
         strategies: Config\Extracting::strategies(
+        // Use configureStrategy() to specify settings for a strategy in the list.
         // Use removeStrategies() to remove an included strategy.
-        // Use withConfiguredStrategy() to configure a strategy which supports it.
             metadata: [...Config\Defaults::METADATA_STRATEGIES],
             urlParameters: [...Config\Defaults::URL_PARAMETERS_STRATEGIES],
             queryParameters: [...Config\Defaults::QUERY_PARAMETERS_STRATEGIES],
@@ -45,7 +46,7 @@ return Config\Factory::make(
                 ]),
             ],
             bodyParameters: [...Config\Defaults::BODY_PARAMETERS_STRATEGIES],
-            responses: withConfiguredStrategy(
+            responses: configureStrategy(
                 Config\Defaults::RESPONSES_STRATEGIES,
                 Strategies\Responses\ResponseCalls::withSettings(
                     only: ['GET *'],

config/scribe_old.php

@@ -2,7 +2,7 @@
 
 use Knuckles\Scribe\Extracting\Strategies;
 use Knuckles\Scribe\Config;
-use function Knuckles\Scribe\Config\{removeStrategies, withConfiguredStrategy};
+use function Knuckles\Scribe\Config\{removeStrategies, configureStrategy};
 
 return [
     // The HTML <title> for the generated documentation. If this is empty, Scribe will infer it from config('app.name').
@@ -202,8 +202,8 @@ INTRO
     ],
 
     // The strategies Scribe will use to extract information about your routes at each stage.
+    // Use configureStrategy() to specify settings for a strategy in the list.
     // Use removeStrategies() to remove an included strategy.
-    // Use withConfiguredStrategy() to configure a strategy which supports it.
     'strategies' => [
         'metadata' => [
             ...Config\Defaults::METADATA_STRATEGIES,
@@ -224,12 +224,8 @@ INTRO
         'bodyParameters' => [
             ...Config\Defaults::BODY_PARAMETERS_STRATEGIES,
         ],
-        'responses' => [
-            Strategies\Responses\UseResponseAttributes::class,
-            Strategies\Responses\UseTransformerTags::class,
-            Strategies\Responses\UseApiResourceTags::class,
-            Strategies\Responses\UseResponseTag::class,
-            Strategies\Responses\UseResponseFileTag::class,
+        'responses' => configureStrategy(
+            Config\Defaults::RESPONSES_STRATEGIES,
             Strategies\Responses\ResponseCalls::withSettings(
                 only: ['GET *'],
                 // Disable debug mode when generating response calls to avoid error stack traces in responses
@@ -237,7 +233,7 @@ INTRO
                     'app.debug' => false,
                 ]
             )
-        ],
+        ),
         'responseFields' => [
             ...Config\Defaults::RESPONSE_FIELDS_STRATEGIES,
         ]

src/Config/strategies.php

@@ -6,35 +6,40 @@ use Illuminate\Support\Arr;
 
 // Strategies can be:
 // 1. (Original) A class name, e.g. Strategies\Responses\ResponseCalls::class
-// 2. (New) A tuple containing the class name as item 1, and its config array as item 2
-// 3. (New) A tuple containing "merge" as item 1, and the values to override array as item 2
+// 2. (New) A tuple containing the class name (or "static_data") as item 1, and its settings array as item 2
 
 /**
  * Remove one or more strategies from a list of strategies.
  */
-function removeStrategies(array $strategies, array $strategyNamesToRemove): array
+function removeStrategies(array $strategiesList, array $strategyNamesToRemove): array
 {
-    $correspondingStrategies = Arr::where($strategies, function ($strategy) use ($strategyNamesToRemove) {
+    $correspondingStrategies = Arr::where($strategiesList, function ($strategy) use ($strategyNamesToRemove) {
         $strategyName = is_string($strategy) ? $strategy : $strategy[0];
         return in_array($strategyName, $strategyNamesToRemove);
     });
 
     foreach ($correspondingStrategies as $key => $value) {
-        unset($strategies[$key]);
+        unset($strategiesList[$key]);
     }
 
-    return $strategies;
+    return $strategiesList;
 }
 
 /**
- * Configure a strategy and add or update it in a list of strategies.
- * This method generates a tuple containing [strategy_name, config_array],
+ * Add/replace a strategy and its settings in a list of strategies.
+ * This method generates a tuple containing [strategyName, settingsArray],
  * and adds or replaces the strategy entry in the list.
+ *
+ * @param array $strategiesList
+ * @param array $configurationTuple Tuple of [strategyName, settingsArray].
+ *   By default, all strategies support the "only" and "except" setting to apply them to specific endpoints.
+ *   You can easily create the tuple by calling Strategy::wrapWithSettings(only: [], except: []).
+ * @return array
  */
-function withConfiguredStrategy(array $strategies, array $configurationTuple): array
+function configureStrategy(array $strategiesList, array $configurationTuple): array
 {
     $strategyFound = false;
-    $strategies = array_map(function ($strategy) use ($configurationTuple, &$strategyFound) {
+    $strategiesList = array_map(function ($strategy) use ($configurationTuple, &$strategyFound) {
         $strategyName = is_string($strategy) ? $strategy : $strategy[0];
         if ($strategyName == $configurationTuple[0]) {
             $strategyFound = true;
@@ -42,11 +47,11 @@ function withConfiguredStrategy(array $strategies, array $configurationTuple): a
         }
 
         return $strategy;
-    }, $strategies);
+    }, $strategiesList);
 
     // If strategy wasn't in there, add it.
     if (!$strategyFound) {
-        $strategies = array_merge($strategies, [$configurationTuple]);
+        $strategiesList = array_merge($strategiesList, [$configurationTuple]);
     }
-    return $strategies;
+    return $strategiesList;
 }

src/Extracting/Strategies/Responses/ResponseCalls.php

@@ -313,12 +313,14 @@ class ResponseCalls extends Strategy
     ): array
     {
         return static::wrapWithSettings(
-            static::class, only: $only, except: $except, otherSettings: compact(
-            'config',
-            'queryParams',
-            'bodyParams',
-            'fileParams',
-            'cookies',
-        ));
+            only: $only,
+            except: $except,
+            otherSettings: compact(
+                'config',
+                'queryParams',
+                'bodyParams',
+                'fileParams',
+                'cookies',
+            ));
     }
 }

src/Extracting/Strategies/StaticData.php

@@ -21,8 +21,10 @@ class StaticData extends Strategy
     ): array
     {
         return static::wrapWithSettings(
-            static::class, only: $only, except: $except, otherSettings: compact(
-            'data',
-        ));
+            only: $only, except: $except,
+            otherSettings: compact(
+                'data',
+            )
+        );
     }
 }

src/Extracting/Strategies/Strategy.php

@@ -41,8 +41,7 @@ abstract class Strategy
      *   Specify route names ("users.index", "users.*"), or method and path ("GET *", "POST /safe/*").
      * @return array{string,array} Tuple of strategy class FQN and specified settings.
      */
-    protected static function wrapWithSettings(
-        string $strategyName = self::class,
+    public static function wrapWithSettings(
         array $only = [],
         array $except = [],
         array $otherSettings = []
@@ -55,7 +54,7 @@ abstract class Strategy
         }
 
         return [
-            $strategyName,
+            static::class,
             ['only' => $only, 'except' => $except, ...$otherSettings],
         ];
     }

tests/BaseLaravelTest.php

@@ -6,7 +6,7 @@ use DMS\PHPUnitExtensions\ArraySubset\ArraySubsetAsserts;
 use Knuckles\Scribe\Config\AuthIn;
 use Knuckles\Scribe\ScribeServiceProvider;
 use Orchestra\Testbench\TestCase;
-use function Knuckles\Scribe\Config\withConfiguredStrategy;
+use function Knuckles\Scribe\Config\configureStrategy;
 use Knuckles\Scribe\Config;
 use Knuckles\Scribe\Extracting\Strategies;
 
@@ -68,7 +68,7 @@ class BaseLaravelTest extends TestCase
                     queryParameters: Config\Defaults::QUERY_PARAMETERS_STRATEGIES,
                     headers: Config\Defaults::HEADERS_STRATEGIES,
                     bodyParameters: Config\Defaults::BODY_PARAMETERS_STRATEGIES,
-                    responses: withConfiguredStrategy(
+                    responses: configureStrategy(
                         Config\Defaults::RESPONSES_STRATEGIES,
                         Strategies\Responses\ResponseCalls::withSettings(
                             only: [],

tests/GenerateDocumentation/OutputTest.php

@@ -21,7 +21,7 @@ use Knuckles\Scribe\Tools\Utils;
 use Symfony\Component\DomCrawler\Crawler;
 use Symfony\Component\Yaml\Yaml;
 use Knuckles\Scribe\Extracting\Strategies;
-use function Knuckles\Scribe\Config\withConfiguredStrategy;
+use function Knuckles\Scribe\Config\configureStrategy;
 
 class OutputTest extends BaseLaravelTest
 {
@@ -593,7 +593,7 @@ class OutputTest extends BaseLaravelTest
     protected function enableResponseCalls(): void
     {
         $this->setConfig([
-            'strategies.responses' => withConfiguredStrategy(
+            'strategies.responses' => configureStrategy(
                 config('scribe.strategies.responses'),
                 Strategies\Responses\ResponseCalls::withSettings(only: ['GET *'], except: [])
             )