knuckleswtf / knuckleswtf/scribe

Undefined array key "properties" when Model Policy uses custom Exception

Open
#963 1 comment 0 reactions 0 assignees View on GitHub
bug triage
Dominant language
PHP
Stars
2.3k
Forks
357
PR merge metrics
No merged PRs in 30d

Description

### Scribe version

5.0.0

### PHP version

8.3.6

### Laravel version

11.43.1

### Scribe config

```ruby
try_it_out.use_csrf => true
```

### What happened?

If any methods in a Model Controller use a Policy via the ```Gate::allows()``` facade but throws a custom Exception, the OpenAPI specification generator bombs with the following:

```
ⓘ Generating OpenAPI specification

ErrorException

Undefined array key "properties"

at vendor\knuckleswtf\scribe\src\Writing\OpenApiSpecGenerators\BaseGenerator.php:554
550▕ return [$k => $this->generateSchemaForResponseValue($v, $endpoint, "$path.$k")];
551▕ })->toArray();
552▕ }
553▕
➜ 554▕ $required = $this->filterRequiredResponseFields($endpoint, array_keys($schema['items']['properties']), $path);
555▕ if ($required) {
556▕ $schema['required'] = $required;
557▕ }
558▕ }

1 vendor\knuckleswtf\scribe\src\Writing\OpenApiSpecGenerators\BaseGenerator.php:554
Illuminate\Foundation\Bootstrap\HandleExceptions::Illuminate\Foundation\Bootstrap\{closure}("Undefined array key "properties"", "D:\project\wemax-backend\vendor\knuckleswtf\scribe\src\Writing\OpenApiSpecGenerators\BaseGenerator.php")

2 vendor\knuckleswtf\scribe\src\Writing\OpenApiSpecGenerators\BaseGenerator.php:514
Knuckles\Scribe\Writing\OpenApiSpecGenerators\BaseGenerator::generateSchemaForResponseValue(Object(Knuckles\Camel\Output\OutputEndpointData), "errors.acesso")
```

The route is simple:
```php
Route::get("/cliente", [ClienteController::class, "pesquisa"]); // search
```

The Controller method is also simple:
```php
/**
* @queryParam texto string Texto parcial de pesquisa. No-example
*/
public function pesquisa(Request $request)
{
$lista_validacao = [
"texto" => ["nullable", "string", "min:1", "max:200"],
];

// Query Parameters
$request->validate($lista_validacao);

// Autorização
if (!Gate::allows("pesquisar", Cliente::class))
{
throw new AcessoNegadoException( // <----------- This causes the problem
operacao: $nome_operacao,
);
}

// Other Stuff not related
}
```

The policy is also simple (only the relevant part pasted):
```php
public function pesquisar(User $user): bool
{
// Permissão do Operador
if (
$user->can(PermissoesOperador::CLIENTE_PESQUISA)
|| $user->can(PermissoesOperador::SUPER)
)
{
return true;
}

return false;
}
```

The custom exception only reformats the fields of a base ```Exception``` to suit the project's frontend:
```php
wantsJson())
{
return (new AcessoNegadoResponse(mensagem: $this->message, operacao: $this->operacao))->toResponse($request);
}

abort(403);
}
}
```
(it works fine)

If the ```Gate``` check is changed to:
```php
if (Gate::allows("pesquisar", Cliente::class))
```
instead of
```php
if (!Gate::allows("pesquisar", Cliente::class))
```
(note the "!")
... then the OpenAPI specification generation does not fail anymore - but app logic is broken. If I add an "else" case to the inverted logic, the error is triggered again.

For now, the OpenAPI documentation simply is not required, so for now I simply ignore the error, but I want to know what's wrong with Scribe or if there is something inherently wrong with throwing custom access denied exceptions together with Scribe.

### Docs

- [x] I've checked [the docs](https://scribe.knuckles.wtf/laravel), the [troubleshooting guide](https://scribe.knuckles.wtf/laravel/troubleshooting), and [existing issues](https://github.com/knuckleswtf/scribe/issues?q=is%3Aissue+), but I didn't find a solution

Contributor guide

Open the contributing guide

Research direction

Reproduce OpenAPI generation with the shown Laravel route, controller, policy check, and custom exception. Start at vendor/knuckleswtf/scribe/src/Writing/OpenApiSpecGenerators/BaseGenerator.php around lines 514 and 554, where items['properties'] is accessed; done means generation completes and produces the specification without the undefined-key error.

Written by the indexing model from the issue text.

Assessment

Tech stack
laravel, php
Domain
api, documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.