Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 51 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,57 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [0.9.0]

### Removed

- `Schema\Model\Schema::withOverrides()` is removed. Build a schema from
constraint groups with `Schema::fromConstraintGroups()` (static factory) and
apply partial updates with `Schema::withOverrideGroups()`, which takes the
four group DTOs `Schema\Model\Internal\ScalarFields`,
`ArrayFields`, `ObjectFields` and `CompositionFields` and replaces only the
fields that are non-null in the supplied groups (`nullable` is a separate
parameter, so it can be flipped back to `false`). The `Schema` constructor
is no longer deprecated: instantiating the model directly with named
arguments is the canonical API.
- `Validator\Error\ValidationContext::create()` and the public
`ValidationContext` constructor are removed. Create contexts exclusively
through the named constructor
`ValidationContext::fromInit(Validator\Error\Internal\ValidationContextInit)`;
the DTO carries `pool`, `errorFormatter`, `nullableAsType`,
`emptyArrayStrategy` and `mode`, and the context always owns a fresh
`BreadcrumbManager`, so per-request isolation is guaranteed by construction.
Branch contexts keep using `forkForBranch()`.
- The public `Validator\Validation\ValidationStack` constructor is removed.
Build a stack through `ValidationStack::fromGroup()` with a
`Validator\Validation\Internal\ValidationGroup` (`root`: `RootServices`
DTO, `options`: `ValidatorOptions` DTO, optional `bodyLimits`).
- `Validator\Exception\ValidationErrorInterface::getType()` and all of its
implementations are removed. Use `keyword()`, which returns the same
validation keyword (`'type'`, `'minLength'`, `'format'`, ...).
- `Builder\OpenApiValidatorInterface::getFormattedErrors()` is removed.
Format a `ValidationException` through
`Validator\Error\Formatter\ErrorFormatterInterface::formatException()`.
The output is byte-identical to the removed method when the validator was
built with the default formatter; otherwise call the configured formatter's
`formatException()` directly.
- `Builder\OpenApiValidatorBuilder::enableStrictCallbackRuntimeTemplate()` is
removed. Strict callback runtime template resolution is the default; use
`disableStrictCallbackRuntimeTemplate()` to opt out (see the security
warning in the README).
- `Validator\Exception\InvalidMultipleOfSchemaException::forLargeIntegerWithoutBcmath()`
is removed. `multipleOf` checks fall back to pure-PHP decimal string
modulus when the BCMath extension is unavailable, so the exception is never
thrown; `forNonPositiveValue()` remains.

### Changed

- `Validator\Error\ValidationContext` and `Validator\Validation\ValidationStack`
are now named-constructor-only services: their constructors are private and
the only creation entry points are `ValidationContext::fromInit()` and
`ValidationStack::fromGroup()`. Schema model classes keep public
constructors.

## [0.8.0]

### Added
Expand Down
13 changes: 4 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,6 @@ The interface exposes the following methods:
| `validateRequest(ServerRequestInterface $request): Operation` | Validate and return matched operation |
| `validateResponse(ResponseInterface $response, Operation $operation): void` | Validate response against operation |
| `validateSchema(mixed $data, string $schemaRef): void` | Validate data against a schema reference |
| `getFormattedErrors(ValidationException $e): string` | Format validation errors as string (**deprecated** in favor of `ErrorFormatterInterface::formatException()`, removed in 2.0) |
| `validateWebhook(ServerRequestInterface $request, string $name): Operation` | Validate webhook request |
| `validateCallback(ServerRequestInterface $request, string $name): Operation` | Validate callback request |
| `getDocument(): OpenApiDocument` | Returns the loaded OpenAPI document for introspection or routing maps (available after `build()`) |
Expand Down Expand Up @@ -242,8 +241,6 @@ $validator = OpenApiValidatorBuilder::create()

> **SECURITY WARNING**: `disableStrictCallbackRuntimeTemplate()` disables the protection against SSRF via attacker-controlled callback URLs: declared security checks still pass against an arbitrary URL when the runtime template is unresolvable. Use it only when callback URLs are validated at the application level (an allowlist of permitted outbound hosts, signed callback URLs, or destination validation before any outbound request is issued).

The previous opt-in method `enableStrictCallbackRuntimeTemplate()` is retained as a deprecated no-op for backward compatibility: strict behaviour is now the default. The method will be removed in 2.0.

### Link Resolution

Resolve OpenAPI Link parameters from response data. Both methods return a `ResolvedLink` DTO exposing resolved `parameters`, `requestBody`, and the optional `server` override declared by the link.
Expand Down Expand Up @@ -521,7 +518,6 @@ $validator = OpenApiValidatorBuilder::create()
| `enableStrictFormats()` | Reject unknown format values instead of skipping | `false` |
| `enableReportDeprecated()` | Log deprecated schema elements via PSR-3 logger | `true` |
| `enableServerPathResolution()` | Strip server base path from request path before matching | `false` |
| `enableStrictCallbackRuntimeTemplate()` | Deprecated no-op: strict mode is now the default. Will be removed in 2.0 | `true` (effective) |
| `disableStrictCallbackRuntimeTemplate()` | Opt out of strict callback runtime template resolution. **SECURITY WARNING**: unresolvable callback expressions like `{$request.body#/callback_url}` are treated as wildcards that accept any URL, enabling SSRF via attacker-controlled callback URLs. Use only when callback URLs are validated at the application level. | `false` (opt-in legacy mode) |
| `withExternalRefAllowedRoot(string $path)` | Directory that external `file://` `$ref` references must stay inside | `null` (auto-derived from spec path for file-loaded specs) |
| `withExternalRefMaxBytes(int $bytes)` | Set max external ref file size | `10485760` (10 MB) |
Expand Down Expand Up @@ -714,6 +710,7 @@ All regular expressions in schemas are validated at parse time; an invalid patte
All validation errors throw `ValidationException` which contains detailed error information:

```php
use Duyler\OpenApi\Validator\Error\Formatter\SimpleFormatter;
use Duyler\OpenApi\Validator\Exception\ValidationException;

try {
Expand All @@ -731,8 +728,8 @@ try {
);
}

// Get formatted errors
$formatted = $validator->getFormattedErrors($e);
// Format errors via a formatter
$formatted = (new SimpleFormatter())->formatException($e);
echo $formatted;
}
```
Expand Down Expand Up @@ -764,8 +761,6 @@ Error formatters omit raw values unless constructed with `includeSensitiveValues

All errors implement `ValidationErrorInterface` and provide `dataPath()`, `schemaPath()`, `keyword()`, `message()`, `params()`, and `suggestion()` methods.

> Note: The `getType()` method is deprecated in favor of `keyword()` and will be removed in 2.0. Both return the same validation keyword (e.g., `'type'`, `'minLength'`, `'format'`). Use `keyword()` in new code.

#### Type and Value Errors

| Error Type | Keyword | Description |
Expand Down Expand Up @@ -905,7 +900,7 @@ $validator = OpenApiValidatorBuilder::create()
->build();
```

To format a `ValidationException` without holding a reference to the validator, call `ErrorFormatterInterface::formatException()` directly. This is the canonical replacement for the deprecated `OpenApiValidatorInterface::getFormattedErrors()` (removed in 2.0):
To format a `ValidationException` without holding a reference to the validator, call `ErrorFormatterInterface::formatException()` directly:

```php
use Duyler\OpenApi\Validator\Error\Formatter\SimpleFormatter;
Expand Down
11 changes: 0 additions & 11 deletions psalm.xml
Original file line number Diff line number Diff line change
Expand Up @@ -15,15 +15,4 @@
<directory name="vendor" />
</ignoreFiles>
</projectFiles>

<issueHandlers>
<DeprecatedMethod>
<errorLevel type="suppress">
<referencedMethod name="Duyler\OpenApi\Schema\Model\Schema::__construct" />
<referencedMethod name="Duyler\OpenApi\Schema\Model\Schema::withOverrides" />
<referencedMethod name="Duyler\OpenApi\Validator\Error\ValidationContext::__construct" />
<referencedMethod name="Duyler\OpenApi\Validator\Error\ValidationContext::create" />
</errorLevel>
</DeprecatedMethod>
</issueHandlers>
</psalm>
6 changes: 0 additions & 6 deletions rector.php
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,6 @@
use Rector\CodingStyle\Rector\Closure\ClosureDelegatingCallToFirstClassCallableRector;
use Rector\Config\RectorConfig;
use Rector\Php74\Rector\Closure\ClosureToArrowFunctionRector;
use Rector\Php84\Rector\Class_\DeprecatedAnnotationToDeprecatedAttributeRector;

return RectorConfig::configure()
->withPaths([
Expand All @@ -21,9 +20,4 @@
ArrowFunctionDelegatingCallToFirstClassCallableRector::class,
ClosureDelegatingCallToFirstClassCallableRector::class,
ClosureToArrowFunctionRector::class,
DeprecatedAnnotationToDeprecatedAttributeRector::class => [
__DIR__ . '/src/Schema/Model/Schema.php',
__DIR__ . '/src/Validator/Validation/ValidationStack.php',
__DIR__ . '/src/Validator/Error/ValidationContext.php',
],
]);
18 changes: 0 additions & 18 deletions src/Builder/OpenApiValidatorBuilder.php
Original file line number Diff line number Diff line change
Expand Up @@ -44,8 +44,6 @@
use Psr\Log\LoggerInterface;
use Psr\Log\NullLogger;

use Deprecated;

use function dirname;
use function realpath;
use function sprintf;
Expand Down Expand Up @@ -221,22 +219,6 @@ public function withMaxRegexBacktracks(int $maxBacktracks): self
return $this->with(new BuilderConfig(maxRegexBacktracks: $maxBacktracks));
}

#[Deprecated(message: <<<'TXT'
since 1.x, will be removed in 2.0. Strict mode is now the
default: callback expressions that use runtime templates
such as `{$request.body#/callback_url}` throw an
{@see \Duyler\OpenApi\Validator\Exception\UnresolvableCallbackPathException} by default instead
of being treated as wildcards that accept any URL. This
method is retained as a no-op for backward compatibility
with callers that explicitly opted in. To restore the
legacy wildcard behaviour, use
{@see disableStrictCallbackRuntimeTemplate()}.
TXT)]
public function enableStrictCallbackRuntimeTemplate(): self
{
return $this;
}

public function disableStrictCallbackRuntimeTemplate(): self
{
return $this->with(new BuilderConfig(strictCallbackRuntimeTemplate: false));
Expand Down
16 changes: 0 additions & 16 deletions src/Builder/OpenApiValidatorInterface.php
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,6 @@

use Duyler\OpenApi\Builder\Exception\BuilderException;
use Duyler\OpenApi\Schema\OpenApiDocument;
use Duyler\OpenApi\Validator\Error\Formatter\ErrorFormatterInterface;
use Duyler\OpenApi\Validator\Exception\BodyTooLargeException;
use Duyler\OpenApi\Validator\Exception\OperationNotFoundException;
use Duyler\OpenApi\Validator\Exception\UnsupportedSecuritySchemeException;
Expand All @@ -17,7 +16,6 @@
use InvalidArgumentException;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Deprecated;
use RuntimeException;

/**
Expand Down Expand Up @@ -73,20 +71,6 @@ public function validateResponse(ResponseInterface $response, Operation $operati
*/
public function validateSchema(mixed $data, string $schemaRef): void;

/**
* Get validation errors as formatted string.
*
* @see ErrorFormatterInterface::formatException()
*
* @param ValidationException $e Validation exception containing errors
* @return string Formatted error messages
*/
#[Deprecated(message: <<<'TXT'
Use ErrorFormatterInterface::formatException() instead.
This method will be removed in 2.0.
TXT)]
public function getFormattedErrors(ValidationException $e): string;

/**
* Validate webhook request against OpenAPI specification and return matched operation.
*
Expand Down
147 changes: 0 additions & 147 deletions src/Schema/Model/Schema.php
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,6 @@
* @param list<mixed>|null $enum
* @param array<string, mixed>|null $examples
* @param Xml|null $xml
* @deprecated since 1.x, will be removed in 2.0. Use {@see fromConstraintGroups()} instead.
*/
public function __construct(
public ?string $ref = null,
Expand Down Expand Up @@ -100,152 +99,6 @@ public function __construct(
public ?Xml $xml = null,
) {}

/**
* @param string|list<string>|null $type
* @param array<string, Schema>|null $properties
* @param list<string>|null $required
* @param list<Schema>|null $allOf
* @param list<Schema>|null $anyOf
* @param list<Schema>|null $oneOf
* @param Schema|bool|null $not
* @param Schema|bool|null $items
* @param list<Schema>|null $prefixItems
* @param array<string, Schema>|null $patternProperties
* @param array<string, Schema>|null $dependentSchemas
* @param Schema|bool|null $additionalProperties
* @param Schema|bool|null $unevaluatedProperties
* @param Schema|bool|null $contentSchema
* @param Schema|bool|null $contains
* @param Schema|bool|null $propertyNames
* @param Schema|bool|null $if
* @param Schema|bool|null $then
* @param Schema|bool|null $else
* @param Schema|bool|null $unevaluatedItems
* @param list<mixed>|null $enum
* @param array<string, mixed>|null $examples
* @param Xml|null $xml
* @deprecated since 1.x, will be removed in 2.0. Use {@see withOverrideGroups()} instead.
*/
public function withOverrides(
?string $ref = null,
?string $refSummary = null,
?string $refDescription = null,
?string $format = null,
?string $title = null,
?string $description = null,
string|int|float|bool|array|null $default = null,
?bool $hasDefault = null,
?bool $deprecated = null,
?bool $readOnly = null,
?bool $writeOnly = null,
string|array|null $type = null,
?bool $nullable = null,
string|int|float|bool|array|null $const = null,
?bool $hasConst = null,
?float $multipleOf = null,
?float $maximum = null,
?float $exclusiveMaximum = null,
?float $minimum = null,
?float $exclusiveMinimum = null,
?int $maxLength = null,
?int $minLength = null,
?string $pattern = null,
?int $maxItems = null,
?int $minItems = null,
?bool $uniqueItems = null,
?int $maxProperties = null,
?int $minProperties = null,
?array $required = null,
?array $allOf = null,
?array $anyOf = null,
?array $oneOf = null,
Schema|bool|null $not = null,
?Discriminator $discriminator = null,
?array $properties = null,
Schema|bool|null $additionalProperties = null,
Schema|bool|null $unevaluatedProperties = null,
Schema|bool|null $items = null,
?array $prefixItems = null,
Schema|bool|null $contains = null,
?int $minContains = null,
?int $maxContains = null,
?array $patternProperties = null,
Schema|bool|null $propertyNames = null,
?array $dependentSchemas = null,
Schema|bool|null $if = null,
Schema|bool|null $then = null,
Schema|bool|null $else = null,
Schema|bool|null $unevaluatedItems = null,
string|int|float|bool|array|null $example = null,
?array $examples = null,
?array $enum = null,
?string $contentEncoding = null,
?string $contentMediaType = null,
Schema|bool|null $contentSchema = null,
?string $jsonSchemaDialect = null,
?Xml $xml = null,
): self {
return new self(
ref: $ref ?? $this->ref,
refSummary: $refSummary ?? $this->refSummary,
refDescription: $refDescription ?? $this->refDescription,
format: $format ?? $this->format,
title: $title ?? $this->title,
description: $description ?? $this->description,
default: $default ?? $this->default,
hasDefault: $hasDefault ?? $this->hasDefault,
deprecated: $deprecated ?? $this->deprecated,
readOnly: $readOnly ?? $this->readOnly,
writeOnly: $writeOnly ?? $this->writeOnly,
type: $type ?? $this->type,
nullable: $nullable ?? $this->nullable,
const: $const ?? $this->const,
hasConst: $hasConst ?? $this->hasConst,
multipleOf: $multipleOf ?? $this->multipleOf,
maximum: $maximum ?? $this->maximum,
exclusiveMaximum: $exclusiveMaximum ?? $this->exclusiveMaximum,
minimum: $minimum ?? $this->minimum,
exclusiveMinimum: $exclusiveMinimum ?? $this->exclusiveMinimum,
maxLength: $maxLength ?? $this->maxLength,
minLength: $minLength ?? $this->minLength,
pattern: $pattern ?? $this->pattern,
maxItems: $maxItems ?? $this->maxItems,
minItems: $minItems ?? $this->minItems,
uniqueItems: $uniqueItems ?? $this->uniqueItems,
maxProperties: $maxProperties ?? $this->maxProperties,
minProperties: $minProperties ?? $this->minProperties,
required: $required ?? $this->required,
allOf: $allOf ?? $this->allOf,
anyOf: $anyOf ?? $this->anyOf,
oneOf: $oneOf ?? $this->oneOf,
not: $not ?? $this->not,
discriminator: $discriminator ?? $this->discriminator,
properties: $properties ?? $this->properties,
additionalProperties: $additionalProperties ?? $this->additionalProperties,
unevaluatedProperties: $unevaluatedProperties ?? $this->unevaluatedProperties,
items: $items ?? $this->items,
prefixItems: $prefixItems ?? $this->prefixItems,
contains: $contains ?? $this->contains,
minContains: $minContains ?? $this->minContains,
maxContains: $maxContains ?? $this->maxContains,
patternProperties: $patternProperties ?? $this->patternProperties,
propertyNames: $propertyNames ?? $this->propertyNames,
dependentSchemas: $dependentSchemas ?? $this->dependentSchemas,
if: $if ?? $this->if,
then: $then ?? $this->then,
else: $else ?? $this->else,
unevaluatedItems: $unevaluatedItems ?? $this->unevaluatedItems,
example: $example ?? $this->example,
examples: $examples ?? $this->examples,
enum: $enum ?? $this->enum,
contentEncoding: $contentEncoding ?? $this->contentEncoding,
contentMediaType: $contentMediaType ?? $this->contentMediaType,
contentSchema: $contentSchema ?? $this->contentSchema,
jsonSchemaDialect: $jsonSchemaDialect ?? $this->jsonSchemaDialect,
xml: $xml ?? $this->xml,
);
}

/**
* @param ?bool $nullable
*/
Expand Down
5 changes: 2 additions & 3 deletions src/Validator/Error/Formatter/ErrorFormatterInterface.php
Original file line number Diff line number Diff line change
Expand Up @@ -19,9 +19,8 @@ public function formatMultiple(array $errors): string;
/**
* Format a ValidationException's errors into a single string.
*
* Replaces OpenApiValidatorInterface::getFormattedErrors() as the
* canonical way to format validation errors without holding a
* reference to the validator.
* This is the canonical way to format validation errors without
* holding a reference to the validator.
*/
public function formatException(ValidationException $exception): string;
}
Loading
Loading