31431102822

Committed 10 Aug 2026 08:51PM UTC coverage: 98.897% (+0.09%) from 98.811%

Build # 31431102822

Build Type

Pull #166

github

Committed by

claude

Commit Message

Merge master: adopt draft-aware $ref sibling handling

Master replaced JsonSchema's allOf rewrite hack for {$ref, siblings} with a
draft-aware producer model, and moved the reference resolution out of
PropertyFactory into RefResolver. Three things had to be adopted rather
than merged mechanically.

The object-shape classifier merged $ref siblings unconditionally, on the
assumption - true before, false now - that the constructor rewrite made
sibling handling draft-independent. Draft 07 registers $ref as an
ExclusiveProducer and ignores every sibling, so merging them classified
`allOf: [{$ref: <object>, type: string}]` as unsatisfiable and rejected a
schema master generates without complaint. classifyReference() now reads
the draft's own $ref producer and follows it, instead of restating the
policy.

The #182/#183 fixes lived in PropertyFactory::processBaseReference(),
which master rewrote from the pre-fix base into RefResolver. Re-applied
there on top of master's structure, so a base-level $ref still transfers
the referenced schema's base validators and still resolves to a
composition rather than being refused outright. The referenced-schema
failure marker likewise had to be re-wired into RefResolver, which
otherwise rewraps a target-side failure as "Unresolved Reference".

createObjectProperty()'s guarded mode was lost when master's version was
taken wholesale; restored.

checkObjectRepresentability()'s $ref exemption now covers sibling-bearing
roots too, since the rewrite that used to strip that key is gone. That is
left as-is deliberately: whether siblings apply is the draft's decision,
and the reference resolution that follows already implements it.

Suite matches master's baseline exactly - the 8 remaining errors
(ArrayContainsTest 2020-12, Issue186Test, AdditionalPropertiesAccessor)
reproduce on pristine master and are not from this branch.

Pull Request Pull Request #166: Fix crashes and silent misvalidation in object-implied compositions, reject non-representable ones

Coverage Stats

400 of 401 new or added lines in 15 files covered. (99.75%)

4 existing lines in 3 files now uncovered.

7893 of 7981 relevant lines covered (98.9%)

595.33 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

99.39

/src/SchemaProcessor/SchemaProcessor.php

<?php

declare(strict_types=1);

namespace PHPModelGenerator\SchemaProcessor;

use PHPModelGenerator\Exception\SchemaException;
use PHPModelGenerator\Model\GeneratorConfiguration;
use PHPModelGenerator\Model\Property\CompositionPropertyDecorator;
use PHPModelGenerator\Model\Property\Property;
use PHPModelGenerator\Model\Property\PropertyInterface;
use PHPModelGenerator\Model\Property\PropertyType;
use PHPModelGenerator\Model\RenderJob;
use PHPModelGenerator\Model\Schema;
use PHPModelGenerator\Model\SchemaDefinition\JsonSchema;
use PHPModelGenerator\Model\SchemaDefinition\SchemaDefinitionDictionary;
use PHPModelGenerator\Model\Validator;
use PHPModelGenerator\Model\Validator\AbstractComposedPropertyValidator;
use PHPModelGenerator\Model\Validator\ComposedPropertyValidator;
use PHPModelGenerator\Model\Validator\ConditionalPropertyValidator;
use PHPModelGenerator\Model\Validator\PropertyTemplateValidator;
use PHPModelGenerator\Model\Validator\Factory\Composition\AllOfValidatorFactory;
use PHPModelGenerator\Model\Validator\Factory\Composition\AnyOfValidatorFactory;
use PHPModelGenerator\Model\Validator\Factory\Composition\ComposedPropertiesValidatorFactoryInterface;
use PHPModelGenerator\Model\Validator\Factory\Composition\OneOfValidatorFactory;
use PHPModelGenerator\PropertyProcessor\Decorator\Property\DefaultArrayToEmptyArrayDecorator;
use PHPModelGenerator\PropertyProcessor\Decorator\Property\ObjectInstantiationDecorator;
use PHPModelGenerator\PropertyProcessor\Decorator\SchemaNamespaceTransferDecorator;
use PHPModelGenerator\PropertyProcessor\Decorator\TypeHint\CompositionTypeHintDecorator;
use PHPModelGenerator\PropertyProcessor\ObjectShape\ObjectShape;
use PHPModelGenerator\PropertyProcessor\ObjectShape\ObjectShapeResolver;
use PHPModelGenerator\PropertyProcessor\PropertyFactory;
use PHPModelGenerator\SchemaProvider\SchemaProviderInterface;
use PHPModelGenerator\Utils\PropertyAttributeSynthesizer;

class SchemaProcessor
{
    protected string $currentClassPath;
    protected string $currentClassName;

    private PropertyAttributeSynthesizer $propertyAttributeSynthesizer;

    /** @var Schema[] Collect processed schemas to avoid duplicated classes */
    protected array $processedSchema = [];
    /** @var PropertyInterface[] Collect processed schemas to avoid duplicated classes */
    protected array $processedMergedProperties = [];
    /**
     * Global index of schemas keyed by the canonical file path or URL returned by
     * SchemaProviderInterface::getRef(). Used to deduplicate external $ref resolutions across
     * all schema processings, making class generation order-independent.
     *
     * When a $ref triggers processTopLevelSchema() for a file that the provider has not yet
     * reached, the canonical Schema is registered here before property processing begins. If
     * the provider later iterates the same file, generateModel() detects the match via the
     * combined file-path + content-signature check and returns the already-registered Schema
     * without creating a duplicate render job.
     *
     * Note: for providers such as OpenAPIv3Provider that yield multiple distinct schemas from
     * a single source file, each schema has a unique content signature; the signature check
     * prevents false-positive deduplication across schemas that merely share the same file.
     *
     * @var Schema[]
     */
    protected array $processedFileSchemas = [];
    /** @var string[] */
    protected array $generatedFiles = [];

    public function __construct(
        protected SchemaProviderInterface $schemaProvider,
        protected string $destination,
        protected GeneratorConfiguration $generatorConfiguration,
        protected RenderQueue $renderQueue,
    ) {
        $this->propertyAttributeSynthesizer = new PropertyAttributeSynthesizer($generatorConfiguration);
    }

    /**
     * Process a given json schema file
     *
     * @throws SchemaException
     */
    public function process(JsonSchema $jsonSchema): void
    {
        $this->setCurrentClassPath($jsonSchema->getFile());
        $this->currentClassName = $this->generatorConfiguration->getClassNameGenerator()->getClassName(
            str_ireplace('.json', '', basename($jsonSchema->getFile())),
            $jsonSchema,
            false,
        );

        $this->processSchema(
            $jsonSchema,
            $this->currentClassPath,
            $this->currentClassName,
            new SchemaDefinitionDictionary($jsonSchema),
            true,
        );
    }

    /**
     * Process a JSON schema stored as an associative array
     *
     * @param SchemaDefinitionDictionary $dictionary   If a nested object of a schema is processed import the
     *                                                 definitions of the parent schema to make them available for the
     *                                                 nested schema as well
     * @param bool                       $initialClass Is it an initial class or a nested class?
     *
     * @throws SchemaException
     */
    public function processSchema(
        JsonSchema $jsonSchema,
        string $classPath,
        string $className,
        SchemaDefinitionDictionary $dictionary,
        bool $initialClass = false,
    ): ?Schema {
        if (
            (!isset($jsonSchema->getJson()['type']) || $jsonSchema->getJson()['type'] !== 'object') &&
            !array_intersect(array_keys($jsonSchema->getJson()), ['anyOf', 'allOf', 'oneOf', 'if', '$ref'])
        ) {
            // skip the JSON schema as neither an object, a reference nor a composition is defined on the root level
            return null;
        }

        return $this->generateModel($classPath, $className, $jsonSchema, $dictionary, $initialClass);
    }

    /**
     * Generate a model and store the model to the file system
     *
     * @throws SchemaException
     */
    protected function generateModel(
        string $classPath,
        string $className,
        JsonSchema $jsonSchema,
        SchemaDefinitionDictionary $dictionary,
        bool $initialClass,
    ): Schema {
        $schemaSignature = $jsonSchema->getSignature();

        if (!$initialClass && isset($this->processedSchema[$schemaSignature])) {
            $this->generatorConfiguration->getLogger()->notice(
                'Duplicated signature {signature} for class {class}. Redirecting to {redirectClass}',
                [
                    'signature' => $schemaSignature,
                    'class' => $className,
                    'redirectClass' => $this->processedSchema[$schemaSignature]->getClassName(),
                ],
            );

            return $this->processedSchema[$schemaSignature];
        }

        // For initial-class calls: if this exact file+content was already processed eagerly via
        // processTopLevelSchema() (triggered by a $ref resolution), reuse that schema to avoid a
        // duplicate render job. Both checks are required:
        // - The file-path check detects that this file was already processed via a $ref.
        // - The signature check ensures we do not short-circuit when a different schema shares
        //   the same source file (e.g. OpenAPI v3 where all component schemas are yielded from
        //   the same spec file — each has a unique signature).
        if (
            $initialClass
            && isset($this->processedSchema[$schemaSignature])
            && $this->getProcessedFileSchema($jsonSchema->getFile()) !== null
        ) {
            return $this->processedSchema[$schemaSignature];
        }

        $schema = new Schema(
            $this->getTargetFileName($classPath, $className),
            $classPath,
            $className,
            $jsonSchema,
            $dictionary,
            $initialClass,
            $this->generatorConfiguration,
        );

        // Populated here (rather than lazily inside createBaseProperty(), the only other caller)
        // because checkObjectRepresentability() below needs it ready to resolve $ref chains.
        // addDefinition() is idempotent, so createBaseProperty()'s own call stays a harmless no-op.
        $dictionary->setUpDefinitionDictionary($this, $schema);
        $this->checkObjectRepresentability($jsonSchema, $className, $dictionary);

        // Register by content signature (secondary dedup for content-identical inline schemas).
        $this->processedSchema[$schemaSignature] = $schema;
        // Register by canonical file path/URL (primary dedup for external $ref resolutions).
        // Registering here — before property processing — ensures that any $ref back to this
        // file encountered while processing the referencing schema finds this canonical schema
        // immediately, regardless of which schema was discovered first by the provider.
        $this->registerProcessedFileSchema($jsonSchema->getFile(), $schema);
        $json = $jsonSchema->getJson();
        $json['type'] = 'base';

        (new PropertyFactory())->create(
            $this,
            $schema,
            $className,
            $jsonSchema->withJson($json),
        );

        $this->generateClassFile($schema);

        return $schema;
    }

    /**
     * Every schema reaching this point becomes a generated PHP class, so its value must be
     * guaranteed to be a JSON object - a composition that only sometimes resolves to an object
     * cannot be faithfully represented by a single generated class. Classifies the pristine
     * schema JSON, before generateModel() overwrites `type` with the internal 'base' dispatch
     * sentinel and thereby erases whether the author declared `type: object` themselves.
     *
     * A `$ref` schema is skipped here on purpose: the real reference resolution that runs moments
     * later already handles every non-representable-target case with better attribution than a
     * speculative peek from here could - and peeking was tried and reverted, since it triggers
     * that same real (non-speculative) resolution as a side effect, and a legitimate failure from
     * it gets swallowed by the peek's own conservative error handling, replacing a precise,
     * correctly-attributed error with a confusing one blaming the referencing wrapper instead.
     *
     * The check is on the raw top-level key, so it covers a `$ref` root whether or not it carries
     * siblings. That is deliberate for both: whether siblings apply at all is the draft's
     * decision (Draft 07 suppresses them, Draft 2019-09 applies them), and the reference
     * resolution that follows implements whichever rule is in force, so deferring to it keeps this
     * method out of a policy it would otherwise have to duplicate. A `$ref` nested inside a
     * composition has no top-level `$ref` key and is therefore still classified below, where
     * ObjectShapeResolver applies the same draft-derived sibling rule.
     *
     * A filter-bearing schema is not exempted by an early return at all (a filter nested inside a
     * composition branch, e.g. an `allOf` branch, has no top-level `filter` key to check for, so
     * an early return here could never have covered that shape anyway). It is instead classified
     * below like everything else: ObjectShapeResolver deliberately classifies filter-bearing
     * schemas as Undecidable (they are owned by the filter-composition subsystem, not the object
     * path), and the guard just after the shape is resolved lets that verdict through without
     * throwing here, so the filter subsystem's own compatibility check - which runs moments later
     * and reports a precise, correctly-attributed error (e.g. naming the incompatible filter and
     * property type) - is not preempted by a generic "does not resolve to a definite object"
     * verdict from this method.
     *
     * @throws SchemaException
     */
    private function checkObjectRepresentability(
        JsonSchema $jsonSchema,
        string $className,
        SchemaDefinitionDictionary $dictionary,
    ): void {
        if (array_key_exists('$ref', $jsonSchema->getJson())) {
            return;
        }

        $shape = ObjectShapeResolver::forDictionary(
            $this,
            $dictionary,
            $this->generatorConfiguration->getBuiltDraft($jsonSchema),
        )->resolve($jsonSchema->getJson());

        // Object-ness could not be determined at all (an unresolvable/cyclic $ref, or a
        // filter-bearing branch owned by another subsystem); let the real pipeline run and
        // produce its own precise, correctly-attributed error rather than rejecting here with a
        // generic representability message that would name the wrong cause.
        if ($shape === ObjectShape::Undecidable) {
            return;
        }

        $acceptedShapes = $this->generatorConfiguration->isImplicitObjectCompositionAllowed()
            ? [ObjectShape::ObjectAsserting, ObjectShape::ObjectDescribing]
            : [ObjectShape::ObjectAsserting];

        if (!in_array($shape, $acceptedShapes, true)) {
            $message = sprintf(
                "Composition for '%s' in file '%s' does not resolve to a definite object and"
                    . ' cannot be represented as a generated class',
                $className,
                $jsonSchema->getFile(),
            );

            // The flag only ever widens acceptance from ObjectAsserting to
            // ObjectAsserting|ObjectDescribing (see $acceptedShapes above), so it can rescue an
            // ObjectDescribing composition but never a NotObject one - mentioning either fix for a
            // NotObject rejection would point the user at options that provably cannot help.
            // Declaring the type is named first because it is the better fix: it makes the
            // author's intent explicit and is what the generator actually needs, whereas the
            // flag is only an escape hatch that leaves the ambiguity in the schema unresolved.
            if ($shape === ObjectShape::ObjectDescribing) {
                $message .= ': add an explicit \'"type": "object"\' constraint, or enable'
                    . " 'GeneratorConfiguration::setImplicitObjectComposition(true)' to accept it";
            }

            throw new SchemaException($message, $jsonSchema);
        }
    }

    /**
     * Create the merged Schema for a property-level $ref+object-sibling merge (Draft 2019-09+).
     *
     * Processes the sibling structural keywords (properties, required, additionalProperties, …)
     * directly into the merged Schema via a base-property pass. The caller is responsible for
     * transferring the $ref's nested Schema's properties into the merged Schema (with allOf
     * semantics for name collisions) inside an onResolve callback, and for calling
     * generateClassFile() once the ref has resolved.
     *
     * @throws SchemaException
     */
    public function createObjectRefSiblingMergedSchema(
        Schema $parentSchema,
        string $propertyName,
        JsonSchema $propertySchema,
        array $siblingJson,
    ): Schema {
        $mergedClassName = $this->generatorConfiguration->getClassNameGenerator()->getClassName(
            $propertyName,
            $propertySchema,
            true,
            $this->currentClassName,
        );

        // Exclude keywords that belong to the outer property (not the merged class body).
        // Mirrors the exclusions that createObjectProperty() applies before passing the schema
        // to processSchema().
        $mergedBaseJson = $siblingJson;
        unset($mergedBaseJson['filter'], $mergedBaseJson['enum'], $mergedBaseJson['default']);
        $mergedBaseJson['type'] = 'base';

        $mergedSchemaJson = $propertySchema->withJson($mergedBaseJson);

        $mergedSchema = new Schema(
            $this->getTargetFileName($parentSchema->getClassPath(), $mergedClassName),
            $parentSchema->getClassPath(),
            $mergedClassName,
            $mergedSchemaJson,
            $parentSchema->getSchemaDictionary(),
            false,
            $this->generatorConfiguration,
        );

        // Process the sibling structural keywords directly into the merged Schema as a base
        // property. This registers sibling-defined properties (via PropertiesValidatorFactory,
        // RequiredPropertyValidator, etc.) on the merged Schema before the $ref's properties
        // are wired in with allOf semantics.
        (new PropertyFactory())->create(
            $this,
            $mergedSchema,
            $mergedClassName,
            $mergedSchemaJson,
        );

        return $mergedSchema;
    }

    /**
     * Attach a new class file render job to the render proxy
     */
    public function generateClassFile(Schema $schema): void
    {
        $this->renderQueue->addRenderJob(new RenderJob($schema));

        $this->generatorConfiguration->getLogger()->info(
            'Generated class {class}',
            [
                'class' => join(
                    '\\',
                    array_filter([
                        $this->generatorConfiguration->getNamespacePrefix(),
                        $schema->getClassPath(),
                        $schema->getClassName(),
                    ]),
                ),
            ],
        );

        $this->generatedFiles[] = $schema->getTargetFileName();
    }


    /**
     * Gather all nested object properties and merge them together into a single merged property
     *
     * @param CompositionPropertyDecorator[] $compositionProperties
     *
     * @throws SchemaException
     */
    public function createMergedProperty(
        Schema $schema,
        PropertyInterface $property,
        array $compositionProperties,
        JsonSchema $propertySchema,
    ): ?PropertyInterface {
        $redirectToProperty = $this->redirectMergedProperty($compositionProperties);
        if ($redirectToProperty === null || $redirectToProperty instanceof PropertyInterface) {
            if ($redirectToProperty) {
                $property->addTypeHintDecorator(new CompositionTypeHintDecorator($redirectToProperty));
            }

            return $redirectToProperty;
        }

        /** @var JsonSchema $jsonSchema */
        $jsonSchema = $propertySchema->getJson()['propertySchema'];
        $schemaSignature = $jsonSchema->getSignature();

        if (!isset($this->processedMergedProperties[$schemaSignature])) {
            $mergedClassName = $this
                ->getGeneratorConfiguration()
                ->getClassNameGenerator()
                ->getClassName(
                    $property->getName(),
                    $propertySchema,
                    true,
                    $this->getCurrentClassName(),
                );

            $mergedPropertySchema = new Schema(
                $this->getTargetFileName($schema->getClassPath(), $mergedClassName),
                $schema->getClassPath(),
                $mergedClassName,
                $propertySchema,
            );

            $this->processedMergedProperties[$schemaSignature] = (new Property(
                'MergedProperty',
                new PropertyType($mergedClassName),
                $mergedPropertySchema->getJsonSchema(),
            ))
                ->addDecorator(new ObjectInstantiationDecorator($mergedClassName, $this->getGeneratorConfiguration()))
                ->setNestedSchema($mergedPropertySchema);

            $this->transferPropertiesToMergedSchema($schema, $mergedPropertySchema, $compositionProperties);

            // make sure the merged schema knows all imports of the parent schema
            $mergedPropertySchema->addNamespaceTransferDecorator(new SchemaNamespaceTransferDecorator($schema));

            $this->generateClassFile($mergedPropertySchema);
        }

        $mergedSchema = $this->processedMergedProperties[$schemaSignature]->getNestedSchema();
        $schema->addUsedClass(
            join(
                '\\',
                array_filter([
                    $this->generatorConfiguration->getNamespacePrefix(),
                    $mergedSchema->getClassPath(),
                    $mergedSchema->getClassName(),
                ]),
            )
        );

        $property->addTypeHintDecorator(
            new CompositionTypeHintDecorator($this->processedMergedProperties[$schemaSignature]),
        );

        return $this->processedMergedProperties[$schemaSignature];
    }

    /**
     * Check if multiple $compositionProperties contain nested schemas. Only in this case a merged property must be
     * created. If no nested schemas are detected null will be returned. If only one $compositionProperty contains a
     * nested schema the $compositionProperty will be used as a replacement for the merged property.
     *
     * Returns false if a merged property must be created.
     *
     * @param CompositionPropertyDecorator[] $compositionProperties
     *
     * @return PropertyInterface|null|false
     */
    private function redirectMergedProperty(array $compositionProperties)
    {
        $redirectToProperty = null;
        foreach ($compositionProperties as $property) {
            if ($property->getNestedSchema()) {
                if ($redirectToProperty !== null) {
                    return false;
                }

                $redirectToProperty = $property;
            }
        }

        return $redirectToProperty;
    }

    /**
     * @param PropertyInterface[] $compositionProperties
     */
    private function transferPropertiesToMergedSchema(
        Schema $schema,
        Schema $mergedPropertySchema,
        array $compositionProperties,
    ): void {
        foreach ($compositionProperties as $property) {
            if (!$property->getNestedSchema()) {
                continue;
            }

            $property->getNestedSchema()->onAllPropertiesResolved(
                function () use ($property, $schema, $mergedPropertySchema): void {
                    foreach ($property->getNestedSchema()->getProperties() as $nestedProperty) {
                        $mergedPropertySchema->addProperty(
                        // don't validate fields in merged properties. All fields were validated before
                        // corresponding to the defined constraints of the composition property.
                            (clone $nestedProperty)->filterValidators(static fn(): bool => false),
                        );
                    }
                },
            );
        }
    }

    /**
     * Get the class path out of the file path of a schema file
     */
    protected function setCurrentClassPath(string $jsonSchemaFile): void
    {
        $fileDir  = str_replace('\\', '/', dirname($jsonSchemaFile));
        $baseDir  = str_replace('\\', '/', $this->schemaProvider->getBaseDirectory());
        $relative = str_replace($baseDir, '', $fileDir);

        // If the file is outside the provider's base directory, str_replace leaves the absolute
        // path untouched. In that case fall back to using just the last directory component so
        // the generated class path stays sensible rather than encoding an absolute path.
        if ($relative === $fileDir) {
            $relative = basename($fileDir);
        }

        $pieces = array_map(
            static fn(string $directory): string => ucfirst((string) preg_replace('/\W/', '', $directory)),
            explode('/', $relative),
        );

        $this->currentClassPath = join('\\', array_filter($pieces));
    }

    public function getCurrentClassPath(): string
    {
        return $this->currentClassPath;
    }

    public function getCurrentClassName(): string
    {
        return $this->currentClassName;
    }

    public function getGeneratedFiles(): array
    {
        return $this->generatedFiles;
    }

    public function getGeneratorConfiguration(): GeneratorConfiguration
    {
        return $this->generatorConfiguration;
    }

    public function getSchemaProvider(): SchemaProviderInterface
    {
        return $this->schemaProvider;
    }

    public function getProcessedFileSchema(string $fileKey): ?Schema
    {
        return $this->processedFileSchemas[$this->normaliseFileKey($fileKey)] ?? null;
    }

    public function registerProcessedFileSchema(string $fileKey, Schema $schema): void
    {
        $this->processedFileSchemas[$this->normaliseFileKey($fileKey)] = $schema;
    }

    /**
     * Normalise a file path or URL to a consistent key for processedFileSchemas.
     * On Windows, RecursiveDirectoryIterator may produce backslash-separated paths while
     * RefResolverTrait produces forward-slash paths for the same file. Normalising to forward
     * slashes ensures the two representations map to the same key.
     */
    private function normaliseFileKey(string $fileKey): string
    {
        return str_replace('\\', '/', $fileKey);
    }

    /**
     * Process an external schema file with its canonical class name and path, exactly as
     * process() would, but without overwriting the current class path / class name context
     * (which belongs to the schema that triggered the $ref resolution).
     *
     * Returns the resulting Schema, or null if the file does not define an object/composition.
     *
     * @throws SchemaException
     */
    public function processTopLevelSchema(JsonSchema $jsonSchema): ?Schema
    {
        $savedClassPath  = $this->currentClassPath;
        $savedClassName  = $this->currentClassName;

        $this->setCurrentClassPath($jsonSchema->getFile());
        $this->currentClassName = $this->generatorConfiguration->getClassNameGenerator()->getClassName(
            str_ireplace('.json', '', basename($jsonSchema->getFile())),
            $jsonSchema,
            false,
        );

        try {
            $schema = $this->processSchema(
                $jsonSchema,
                $this->currentClassPath,
                $this->currentClassName,
                new SchemaDefinitionDictionary($jsonSchema),
                true,
            );
        } catch (SchemaException $exception) {
            // Everything thrown here is a fault in the referenced schema itself, not a failure to
            // reach it - this method only runs once the reference has already resolved to a file.
            // Marking it keeps PropertyFactory::processReference() from restating it as
            // "Unresolved Reference", which would blame the reference site for a problem in the
            // content it points at.
            throw $exception->markAsReferencedSchemaFailure();
        }

        $this->currentClassPath = $savedClassPath;
        $this->currentClassName = $savedClassName;

        return $schema;
    }

    /**
     * Transfer properties of composed properties to the given schema to offer a complete model
     * including all composed properties.
     *
     * This is an internal pipeline mechanic (Q5.1): not a JSON Schema keyword and therefore not
     * a Draft modifier. It is called as an explicit post-step from generateModel after all Draft
     * modifiers have run on the root-level BaseProperty.
     *
     * @throws SchemaException
     */
    public function transferComposedPropertiesToSchema(PropertyInterface $property, Schema $schema): void
    {
        foreach ($property->getValidators() as $validator) {
            $validator = $validator->getValidator();

            if (!is_a($validator, AbstractComposedPropertyValidator::class)) {
                continue;
            }

            // If the transferred validator of the composed property is also a composed property
            // strip the nested composition validations from the added validator. The nested
            // composition will be validated in the object generated for the nested composition
            // which will be executed via an instantiation. Consequently, the validation must not
            // be executed in the outer composition.
            $schema->addBaseValidator(
                ($validator instanceof ComposedPropertyValidator)
                    ? $validator->withoutNestedCompositionValidation()
                    : $validator,
            );

            if (
                !is_a(
                    $validator->getCompositionProcessor(),
                    ComposedPropertiesValidatorFactoryInterface::class,
                    true,
                )
            ) {
                continue;
            }

            $branchesForValidator = $validator instanceof ConditionalPropertyValidator
                ? $validator->getConditionBranches()
                : $validator->getComposedProperties();

            $totalBranches = count($branchesForValidator);
            $resolvedPropertiesCallbacks = 0;
            $seenBranchPropertyNames = [];

            foreach ($validator->getComposedProperties() as $branchIndex => $composedProperty) {
                $composedProperty->onResolve(function () use (
                    $branchIndex,
                    $composedProperty,
                    $property,
                    $validator,
                    $branchesForValidator,
                    $totalBranches,
                    $schema,
                    &$resolvedPropertiesCallbacks,
                    &$seenBranchPropertyNames,
                ): void {
                    if (!$composedProperty->getNestedSchema()) {
                        if ($composedProperty->getType() !== null) {
                            throw new SchemaException(
                                sprintf(
                                    "No nested schema for composed property %s in file %s found",
                                    $property->getName(),
                                    $property->getJsonSchema()->getFile(),
                                ),
                                $property->getJsonSchema(),
                            );
                        }

                        // A branch with neither a nested schema nor an explicit type (e.g. a $ref
                        // to a definition carrying only annotation keywords such as example)
                        // matches any value and contributes no named properties to transfer -
                        // this is not a schema error, unlike a branch with an explicit type that
                        // still lacks a nested schema (a genuine type conflict, handled above).
                        $this->finalizeComposedBranchResolution(
                            in_array($composedProperty, $branchesForValidator, true),
                            $totalBranches,
                            $resolvedPropertiesCallbacks,
                            $seenBranchPropertyNames,
                            $validator,
                            $property,
                            $schema,
                        );

                        return;
                    }

                    $isBranchForValidator = in_array($composedProperty, $branchesForValidator, true);

                    $composedProperty->getNestedSchema()->onAllPropertiesResolved(
                        function () use (
                            $branchIndex,
                            $composedProperty,
                            $property,
                            $validator,
                            $isBranchForValidator,
                            $totalBranches,
                            $schema,
                            &$resolvedPropertiesCallbacks,
                            &$seenBranchPropertyNames,
                        ): void {
                            $branchLabel = $this->getCompositionBranchLabel(
                                $validator,
                                $composedProperty,
                                $branchIndex,
                            );

                            foreach ($composedProperty->getNestedSchema()->getProperties() as $branchProperty) {
                                if ($branchLabel !== null) {
                                    $this->checkRootBranchDefaultConflict(
                                        $branchProperty,
                                        $branchLabel,
                                        $validator,
                                        $schema,
                                    );
                                }

                                $schema->addProperty(
                                    $this->cloneTransferredProperty(
                                        $branchProperty,
                                        $composedProperty,
                                        $validator,
                                    ),
                                    $validator->getCompositionProcessor(),
                                );

                                $composedProperty->appendAffectedObjectProperty($branchProperty);
                                $seenBranchPropertyNames[$branchProperty->getName()] = true;
                            }

                            $this->finalizeComposedBranchResolution(
                                $isBranchForValidator,
                                $totalBranches,
                                $resolvedPropertiesCallbacks,
                                $seenBranchPropertyNames,
                                $validator,
                                $property,
                                $schema,
                            );
                        },
                    );
                });
            }
        }
    }

    /**
     * Run the once-per-composition cross-branch checks and property-attribute synthesis after the
     * final branch of a composed property has finished contributing its properties to the schema -
     * whether by transferring named properties from a nested schema, or by contributing none
     * because the branch has neither a nested schema nor an explicit type.
     *
     * @param array<string, true> $seenBranchPropertyNames
     */
    private function finalizeComposedBranchResolution(
        bool $isBranchForValidator,
        int $totalBranches,
        int &$resolvedPropertiesCallbacks,
        array $seenBranchPropertyNames,
        AbstractComposedPropertyValidator $validator,
        PropertyInterface $property,
        Schema $schema,
    ): void {
        if (!$isBranchForValidator || ++$resolvedPropertiesCallbacks !== $totalBranches) {
            return;
        }

        foreach (array_keys($seenBranchPropertyNames) as $branchPropertyName) {
            $schema->getPropertyMerger()->checkForTotalConflict(
                $branchPropertyName,
                $totalBranches,
                $schema->getJsonSchema(),
            );
        }

        $this->checkCrossBranchDefaultConflicts($validator, $property);

        $this->propertyAttributeSynthesizer->synthesiseForValidator($validator, $schema, $seenBranchPropertyNames);
    }

    /**
     * Clone the provided property to transfer it to a schema. Sets the nullability and required
     * flag based on the composition processor used to set up the composition. Widens the type to
     * mixed when the property is exclusive to one anyOf/oneOf branch and at least one other branch
     * allows additional properties, preventing TypeError when raw input values of an arbitrary
     * type are stored in the property slot.
     */
    private function cloneTransferredProperty(
        PropertyInterface $property,
        CompositionPropertyDecorator $sourceBranch,
        AbstractComposedPropertyValidator $validator,
    ): PropertyInterface {
        $compositionProcessor = $validator->getCompositionProcessor();

        $transferredProperty = (clone $property)
            ->filterValidators(static fn(Validator $v): bool =>
                is_a($v->getValidator(), PropertyTemplateValidator::class))
            ->setDefaultValue(null)
            ->filterDecorators(static fn($decorator): bool =>
                !($decorator instanceof DefaultArrayToEmptyArrayDecorator));

        if (!is_a($compositionProcessor, AllOfValidatorFactory::class, true)) {
            $transferredProperty->setRequired(false);

            if ($transferredProperty->getType()) {
                $transferredProperty->setType(
                    new PropertyType($transferredProperty->getType()->getNames(), true),
                    new PropertyType($transferredProperty->getType(true)->getNames(), true),
                );
            }

            $wideningBranches = $validator instanceof ConditionalPropertyValidator
                ? $validator->getConditionBranches()
                : $validator->getComposedProperties();

            if ($this->exclusiveBranchPropertyNeedsWidening($property->getName(), $sourceBranch, $wideningBranches)) {
                $transferredProperty->setType(null, null, reset: true);
            }

            // Blank the branch schema for disjunctive compositions (anyOf/oneOf/if): a constraint
            // declared on one branch (e.g. an enum on a single oneOf branch while another branch
            // accepts free-form values) must not leak onto the outer merged property, which a
            // value may satisfy via a different branch. For allOf every branch constraint applies
            // to the same value, so the schema is preserved instead - keeping representation-level
            // information such as enum sub-schemas visible to post processors on the merged
            // property, matching the dedicated _Merged_ class path.
            $transferredProperty->setJsonSchema($transferredProperty->getJsonSchema()->withJson([]));
        }

        return $transferredProperty;
    }

    /**
     * Returns true when the property named $propertyName is exclusive to $sourceBranch and at
     * least one other anyOf/oneOf branch allows additional properties (i.e. does NOT declare
     * additionalProperties: false). In that case the property slot can receive an
     * arbitrarily-typed raw input value from a non-matching branch, so the type hint is removed.
     *
     * Returns false when the property appears in another branch too (Schema::addProperty handles
     * that via type merging) or when all other branches have additionalProperties: false (making
     * the property mutually exclusive with the other branches' properties).
     *
     * @param CompositionPropertyDecorator[] $allBranches
     */
    private function exclusiveBranchPropertyNeedsWidening(
        string $propertyName,
        CompositionPropertyDecorator $sourceBranch,
        array $allBranches,
    ): bool {
        foreach ($allBranches as $branch) {
            if ($branch === $sourceBranch) {
                continue;
            }

            $branchPropertyNames = $branch->getNestedSchema()
                ? array_map(
                    static fn(PropertyInterface $p): string => $p->getName(),
                    $branch->getNestedSchema()->getProperties(),
                )
                : [];

            if (in_array($propertyName, $branchPropertyNames, true)) {
                return false;
            }
        }

        foreach ($allBranches as $branch) {
            if ($branch === $sourceBranch) {
                continue;
            }

            if (($branch->getBranchSchema()->getJson()['additionalProperties'] ?? true) !== false) {
                return true;
            }
        }

        return false;
    }

    /**
     * Throws a SchemaException when a branch property carries a non-null default that differs
     * from a root-registered property of the same name in the parent schema.
     *
     * After the branch-default fix, all transferred branch properties have their default cleared
     * to null before being added to the parent schema. Only root-level properties therefore carry
     * a non-null default. This invariant makes `getDefaultValue() !== null` a reliable proxy for
     * "this property was added at the root level with a meaningful default."
     *
     * Does NOT classify against output-space defaults — only the raw branch default (before
     * transfer clears it) is compared to the existing root default.
     *
     * @param string $branchLabel Human-readable branch identifier for the error message
     *                            (e.g. 'allOf/0', 'then', 'else').
     */
    private function checkRootBranchDefaultConflict(
        PropertyInterface $branchProperty,
        string $branchLabel,
        AbstractComposedPropertyValidator $validator,
        Schema $schema,
    ): void {
        $branchDefault = $branchProperty->getDefaultValue();

        if ($branchDefault !== null) {
            $existingDefault = $schema->getProperty($branchProperty->getName())?->getDefaultValue();

            if ($existingDefault !== null && $existingDefault !== $branchDefault) {
                throw new SchemaException(
                    sprintf(
                        "Conflicting default values for property '%s' under %s composition in file %s:"
                            . " root=%s, %s=%s.",
                        $branchProperty->getName(),
                        $this->getCompositionKeyword($validator),
                        $branchProperty->getJsonSchema()->getFile(),
                        $existingDefault,
                        $branchLabel,
                        $branchDefault,
                    ),
                    $branchProperty->getJsonSchema(),
                );
            }
        }

        // Check patternProperties defaults declared on the outer schema. Any pattern that matches
        // the branch property name either agrees with the branch default (fine) or conflicts with
        // it (SchemaException). When the branch property has no explicit default, the first
        // matching pattern default is propagated to it; subsequent patterns must agree.
        $patternProperties = $schema->getJsonSchema()->getJson()['patternProperties'] ?? [];
        $effectiveBranchDefault = $branchDefault;

        foreach ($patternProperties as $pattern => $patternSchema) {
            if (!isset($patternSchema['default'])) {
                continue;
            }

            if (!preg_match('/' . addcslashes($pattern, '/') . '/', $branchProperty->getName())) {
                continue;
            }

            $patternDefault = var_export($patternSchema['default'], true);

            if ($effectiveBranchDefault !== null && $effectiveBranchDefault !== $patternDefault) {
                throw new SchemaException(
                    sprintf(
                        "Conflicting default values for property '%s' under %s composition in file %s:"
                            . " pattern '%s'=%s, %s=%s.",
                        $branchProperty->getName(),
                        $this->getCompositionKeyword($validator),
                        $branchProperty->getJsonSchema()->getFile(),
                        $pattern,
                        $patternDefault,
                        $branchLabel,
                        $effectiveBranchDefault,
                    ),
                    $branchProperty->getJsonSchema(),
                );
            }

            if ($effectiveBranchDefault === null) {
                $branchProperty->setDefaultValue($patternSchema['default']);
                $effectiveBranchDefault = $patternDefault;
            }
        }
    }

    /**
     * Returns a human-readable label for the given branch suitable for use in conflict error
     * messages, or null when the branch should be excluded from conflict checks.
     *
     * For if/then/else compositions the 'if' branch is purely a condition check and carries no
     * applied defaults, so it returns null. The 'then' and 'else' branches return their keyword.
     * For allOf / anyOf / oneOf the label is '<keyword>/<branchIndex>'.
     */
    private function getCompositionBranchLabel(
        AbstractComposedPropertyValidator $validator,
        CompositionPropertyDecorator $composedProperty,
        int $branchIndex,
    ): ?string {
        if (!($validator instanceof ConditionalPropertyValidator)) {
            return $this->getCompositionKeyword($validator) . '/' . $branchIndex;
        }

        $conditionBranches = $validator->getConditionBranches();
        $conditionIndex = array_search($composedProperty, $conditionBranches, true);

        if ($conditionIndex === false) {
            // This is the 'if' branch — it applies no defaults, so skip it.
            return null;
        }

        // Use object identity rather than the filtered-array index. When only an else branch
        // is present (no then), it occupies index 0 in conditionBranches after array_values,
        // so an index-based check would incorrectly return 'then' for the else branch.
        return $composedProperty === $validator->getThenBranch() ? 'then' : 'else';
    }

    /**
     * Checks all composition branches for properties with conflicting non-null default values.
     * Only meaningful for allOf and anyOf, where multiple branches can match simultaneously —
     * for oneOf and if/then/else at most one branch matches, so per-branch defaults cannot
     * conflict at runtime and this check is skipped.
     */
    private function checkCrossBranchDefaultConflicts(
        AbstractComposedPropertyValidator $validator,
        PropertyInterface $compositionProperty,
    ): void {
        // Only allOf and anyOf can have multiple simultaneously-matching branches.
        // For oneOf and if/then/else exactly one branch matches, so different per-branch
        // defaults are not a conflict.
        if (
            !is_a($validator->getCompositionProcessor(), AllOfValidatorFactory::class, true)
            && !is_a($validator->getCompositionProcessor(), AnyOfValidatorFactory::class, true)
        ) {
            return;
        }

        $keyword = $this->getCompositionKeyword($validator);

        /** @var array<string, array<int, mixed>> $defaultsByProperty Property name → [branchIndex => default] */
        $defaultsByProperty = [];

        foreach ($validator->getComposedProperties() as $branchIndex => $composedBranch) {
            $nestedSchema = $composedBranch->getNestedSchema();
            if ($nestedSchema === null) {
                continue;
            }

            foreach ($nestedSchema->getProperties() as $branchProperty) {
                $branchDefault = $branchProperty->getDefaultValue();
                if ($branchDefault !== null) {
                    $defaultsByProperty[$branchProperty->getName()][$branchIndex] = $branchDefault;
                }
            }
        }

        foreach ($defaultsByProperty as $propertyName => $defaultsByBranch) {
            $firstDefault = reset($defaultsByBranch);
            $hasConflict = false;
            foreach ($defaultsByBranch as $branchDefault) {
                if ($branchDefault !== $firstDefault) {
                    $hasConflict = true;
                    break;
                }
            }

            if (!$hasConflict) {
                continue;
            }

            $sites = [];
            foreach ($defaultsByBranch as $branchIndex => $branchDefault) {
                $sites[] = sprintf('%s/%d=%s', $keyword, $branchIndex, $branchDefault);
            }

            throw new SchemaException(
                sprintf(
                    "Conflicting default values for property '%s' under %s composition in file %s: %s.",
                    $propertyName,
                    $keyword,
                    $compositionProperty->getJsonSchema()->getFile(),
                    implode(', ', $sites),
                ),
                $compositionProperty->getJsonSchema(),
            );
        }
    }

    private function getCompositionKeyword(AbstractComposedPropertyValidator $validator): string
    {
        return match (true) {
            is_a($validator->getCompositionProcessor(), AllOfValidatorFactory::class, true) => 'allOf',
            is_a($validator->getCompositionProcessor(), AnyOfValidatorFactory::class, true) => 'anyOf',
            is_a($validator->getCompositionProcessor(), OneOfValidatorFactory::class, true) => 'oneOf',
            default                                                                          => 'if/then/else',
        };
    }

    private function getTargetFileName(string $classPath, string $className): string
    {
        return join(
            DIRECTORY_SEPARATOR,
            array_filter([$this->destination, str_replace('\\', DIRECTORY_SEPARATOR, $classPath), $className]),
        ) . '.php';
    }
}

wol-soft / php-json-schema-model-generator / 31431102822

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous