HEAD Routes break generation

[Smudge3806]

• [x] I confirm that I have read and attempted the tips in the Troubleshooting Guide.

What happened?

1. Using the out-of-the-box configuration with minor alterations
2. When we run php artisan scribe:generate
3. We get an error during generation of the example-requests

Screenshots and stack traces:

In 3666cec63a5bc7f130fc7f39cdbc92fbb87d6d5c.php line 2:

  Undefined offset: 0 (View: /web/html/vendor/knuckleswtf/scribe/resources/views/partials/example-requests/bash.blade.php) (View:
   /web/html/vendor/knuckleswtf/scribe/resources/views/partials/example-requests/bash.blade.php)

TL;SR; Already found the cause of the bug! It just needs fixing :) Click Here or scroll to Additional Info

My environment:

• PHP version: 7.3.14
• Framework (Laravel/Lumen) and version: Lumen v6.3.5 (74d61ebf4f022a874bcea560054a2a2050d0e75d)
• Scribe Version: 1.1.0 (42d034f6267518c05050ccd18da2989bdfce35d3)

My Scribe config (minus the comments):

return [
    'static' => [
        'output_path' => 'public/docs',
    ],
    'laravel' => [
        'add_routes' => true,
        'docs_url' => '/docs',
        'middleware' => [],
    ],
    'auth' => [
        'enabled' => true,
        'in' => 'bearer',
        'name' => 'bearer',
        'use_value' => null,
        'extra_info' => 'JWT Tokens are App Specific.',
    ],
    'intro_text' => 'api intro',
    'example_languages' => [
        'bash',
        'javascript',
        'php'
    ],
    'base_url' => null,
    'title' => 'XEDI API Documentation',
    'postman' => [
        'enabled' => true,
        'base_url' => null,
        'description' => null,
        'auth' => null,
    ],
    'default_group' => 'Misc',
    'logo' =>  null,
    'router' => 'laravel',
    'routes' => [
        [
            'match' => [
                'domains' => ['*'],
                'prefixes' => ['*'],
                'versions' => ['v1'],
            ],
            'include' => [],
            'exclude' => [
                'status.*', 'version'
            ],
            'apply' => [
                'headers' => [
                    'Content-Type' => 'application/json',
                    'Accept' => 'application/json',
                    'Authorization' => 'Bearer {token}',
                ],
                'response_calls' => [
                    'methods' => ['GET', 'POST', 'PUT'],
                    'config' => [
                        'app.env' => 'localhost',
                    ],
                    'cookies' => [],
                    'queryParams' => [],
                    'bodyParams' => [],
                    'fileParams' => [],
                ],
            ],
        ],
    ],
    'fractal' => [
        'serializer' => null,
    ],
    'faker_seed' => null,
    'strategies' => [
        'metadata' => [
            \Knuckles\Scribe\Extracting\Strategies\Metadata\GetFromDocBlocks::class,
        ],
        'urlParameters' => [
            \Knuckles\Scribe\Extracting\Strategies\UrlParameters\GetFromUrlParamTag::class,
        ],
        'queryParameters' => [
            \Knuckles\Scribe\Extracting\Strategies\QueryParameters\GetFromQueryParamTag::class,
        ],
        'headers' => [
            \Knuckles\Scribe\Extracting\Strategies\Headers\GetFromRouteRules::class,
            \Knuckles\Scribe\Extracting\Strategies\Headers\GetFromHeaderTag::class,
        ],
        'bodyParameters' => [
            \Knuckles\Scribe\Extracting\Strategies\BodyParameters\GetFromFormRequest::class,
            \Knuckles\Scribe\Extracting\Strategies\BodyParameters\GetFromBodyParamTag::class,
        ],
        'responses' => [
            \Knuckles\Scribe\Extracting\Strategies\Responses\UseTransformerTags::class,
            \Knuckles\Scribe\Extracting\Strategies\Responses\UseResponseTag::class,
            \Knuckles\Scribe\Extracting\Strategies\Responses\UseResponseFileTag::class,
            \Knuckles\Scribe\Extracting\Strategies\Responses\UseApiResourceTags::class,
            \Knuckles\Scribe\Extracting\Strategies\Responses\ResponseCalls::class,
        ],
        'responseFields' => [
            \Knuckles\Scribe\Extracting\Strategies\ResponseFields\GetFromResponseFieldTag::class,
        ],
    ],
    'routeMatcher' => \Knuckles\Scribe\Matching\RouteMatcher::class,
];

Additional info:

• Debugging of the partial that throws the error reveals a route with an empty methods array.
• Debugging of the RouteMatcher reveals that all routes have entries in the methods array.
• Placing a try/catch around the render call responsible for triggering the error reveals the route without the method. It's a HEAD route. The method has been lost somewhere.
• Tracing the call stack back to the GenerateCommand leads us to Line 118 and $generator->processRoute() as the point where the method is "lost".
• On stepping into the Knuckles\Scribe\Extracting\Generator source code, the getMethods method is observed.

    /**
     * @param Route $route
     *
     * @return mixed
     */
    public function getMethods(Route $route)
    {
        return array_diff($route->methods(), ['HEAD']);
    }

Because HEAD is the only method in the methods array, it is striped out. We are using the HEAD verb in our API in accordance to its semantic purpose.

Proposed Fixes

1. Remove the use of array_diff. The addition of the HEAD verb is Laravel's doing and therefore they should fix that.
2. Add a defensive check to make sure that there is always one value in the methods array.

Thoughts?

TIA

[Smudge3806]

/cc @th0rn0 for visibility

[Smudge3806]

Another potential solution maybe to add an additional configuration variable the allows HEAD verbs to be used.

[shalvah]

I think your first solution is fine. 👍