[php] Fix PHP generator validation for nullable required properties by achton · Pull Request #22292 · OpenAPITools/openapi-generator

achton · 2025-11-06T11:23:02Z

Fix PHP generator bug where nullable-but-required model properties were always flagged as invalid when set to null. Update validation/docblocks so explicit null assignments are honored. Closes #21497.

@jebentier @dkarlovi @mandrean @jfastnacht @ybelenko @renepardon

PR checklist

Read the contribution guidelines.
Pull Request title clearly describes the work in the pull request and Pull Request description provides details about how to validate the work. Missing information here may result in delayed response from the community.
Run the following to build the project and update samples:
```
./mvnw clean package || exit
./bin/generate-samples.sh ./bin/configs/*.yaml || exit
./bin/utils/export_docs_generators.sh || exit
```
(For Windows users, please run the script in WSL)
Commit all changed files.
This is important, as CI jobs will verify all generator outputs of your HEAD commit as it would merge with master.
These must match the expectations made by your contribution.
You may regenerate an individual generator by passing the relevant config(s) as an argument to the script, for example ./bin/generate-samples.sh bin/configs/java*.
IMPORTANT: Do NOT purge/delete any folders/files (e.g. tests) when regenerating the samples as manually written tests may be removed.
File the PR against the correct branch: master (upcoming 7.x.0 minor release - breaking changes with fallbacks), 8.0.x (breaking changes without fallbacks)
If your PR solves a reported issue, reference it using GitHub's linking syntax (e.g., having "fixes #123" present in the PR description)
If your PR is targeting a particular programming language, @mention the technical committee members, so they are more likely to review the pull request.

… models. Also fix PHP annotations related to same.

wing328 · 2025-11-07T13:13:38Z

     * Sets {{name}}
     *
-     * @param {{{dataType}}}{{^required}}|null{{/required}} ${{name}}{{#description}} {{{.}}}{{/description}}{{^description}} {{{name}}}{{/description}}
+     * @param {{{dataType}}}{{#isNullable}}|null{{/isNullable}} ${{name}}{{#description}} {{{.}}}{{/description}}{{^description}} {{{name}}}{{/description}}


can we also apply the same update here to handle both required and optional properties?

wing328 · 2025-11-07T13:13:45Z

        {{#vars}}
        {{#required}}
-        if ($this->container['{{name}}'] === null) {
+        if ($this->container['{{name}}'] === null{{#isNullable}} && !$this->isNullableSetToNull('{{name}}'){{/isNullable}}) {


can we also apply the same update here to handle both required and optional properties?

wing328 · 2025-11-08T14:28:30Z

I'll address those comments with a separate PR

UPDATE: merged #22307

wing328 · 2025-11-09T10:42:18Z

FYI. Merged another PR (#22310) to refactor the template a bit

…penAPITools#22292) * [php] Fix null+required properties to accept null values in generated models. Also fix PHP annotations related to same. * [php] Update samples.

…re not allowing a `null` value applies an upstream patch to our custom model mustache template. fixes "[name] can't be null" errors when setting a required value to `null` if a null value was allowed (eg presence is required, but can be empty) see OpenAPITools/openapi-generator#22292

Completes the OpenAPITools/openapi-generator#22292 backport started in 3e9953a. That commit fixed listInvalidProperties() but left the generated getter/setter PHPDoc showing e.g. `@return int` for required+nullable properties like RefTypesMoneyNullableAmount::amount, which can legitimately be null. Append the |null that the upstream fix adds for these properties and regenerate. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

## [11.0.0-beta.29](v11.0.0-beta.28...v11.0.0-beta.29) (2026-07-09) ### ⚠ BREAKING CHANGES * **openapi:** loosen and apply consistent validation for enum values, fix required nullables (#623) ### ✨ New Features * **openapi:** loosen and apply consistent validation for enum values, fix required nullables ([#623](#623)) ([2164721](2164721)), closes [OpenAPITools/openapi-generator#22292](OpenAPITools/openapi-generator#22292) [OpenAPITools/openapi-generator#22292](OpenAPITools/openapi-generator#22292)

@todo

…s, fix required nullables (#623) * build(openapi): allow for unknown enum values do not error when the API returns a new value for an enum but the SDK has not yet been updated. prevents our customers from having runtime breakages fixes INT-1684 * feat(openapi)!: loosen and apply consistent validation for enum values We now allow for unknown enum values in API responses to be passed to consumers without error. On the request side, you still need to conform to the spec - but its been made more consistent now. * loosens enum restrictions for incoming responses (`deserialize`) unknown values now pass through without errors. this fixes cases where new values were added to the api and the client would error when these values came in, requiring consumers to update to a new client before their application works * consistent enum validation for outgoing requests (`serialize`) previously inline- and "shared" enums had different validation paths when setting values on an openapi model. this is now consistent: errors are only thrown when the model is serialized, not when setting a value. this now applies to both inline- and attributes that cast to dedicated enum classes in the same way fixes INT-1684 * fix(openapi): fix a problem where nullable but required properties were not allowing a `null` value applies an upstream patch to our custom model mustache template. fixes "[name] can't be null" errors when setting a required value to `null` if a null value was allowed (eg presence is required, but can be empty) see OpenAPITools/openapi-generator#22292 * feat(orderapi): add ViaTim carrier to OrderApi client (orderv2) * fix(openapi): add |null to PHPDoc for required nullable properties Completes the OpenAPITools/openapi-generator#22292 backport started in 3e9953a. That commit fixed listInvalidProperties() but left the generated getter/setter PHPDoc showing e.g. `@return int` for required+nullable properties like RefTypesMoneyNullableAmount::amount, which can legitimately be null. Append the |null that the upstream fix adds for these properties and regenerate. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(openapi): enforce enum validity for array-typed enums on serialization With setter-side enum validation removed, sanitizeForSerialization() is the single enforcement point for outgoing requests, but two array cases slipped through: - referenced enum arrays (e.g. OrdersGetFilterParameter::carrier typed as Carrier[]) were never validated, because getAllowableEnumValues() was looked up on the literal "...[]" type string. Strip the [] suffix and validate each item against the base enum class. - inline enum arrays used array_diff(), which compares loosely ('1' == 1). Use a strict per-item in_array() check instead. Add ReferencedEnumArrayBehaviorTest covering passthrough on read and strict validation on write for referenced enum arrays. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(openapi): skip value-less pseudo-enums and drop redundant Fixed* overrides openapi-generator collapses spec fields shaped like `anyOf(<string> | enum[null,""])` (email, billing_email, secondary_emails, from_address_email, …) into a pseudo-enum whose only allowable value is "". The serialization-time enum validation then rejected every real value, and array-typed referenced pseudo-enums (secondary_emails) threw too. Guard all three enum enforcement points to skip enums with no non-empty allowable value (real enums stay validated): - referenced-enum block in ObjectSerializer.mustache (scalar + array) - inline-enum block in ObjectSerializer.mustache - isEnum check in model_generic.mustache listInvalidProperties() With the pseudo-enum handled generically, the email-only override classes are redundant: delete FixedShipmentSender and FixedShipmentGeneralSettingsTracktrace, and slim FixedShipmentRecipient to the still-needed street-pattern fix. Reduce the typeMappings in coreapi.yaml accordingly. Add openapiNormalizer flags (SIMPLIFY_ANYOF_STRING_AND_ENUM_STRING, SIMPLIFY_ONEOF_ANYOF) as a documented no-op on generator 7.12.0 (its normalizer cannot process OpenAPI 3.1 multi-type schemas); after upgrading to >= 7.17 they take effect and the runtime guards + FixedShipmentRecipient can be removed. Add PseudoEnumSerializationTest covering inline, referenced-scalar and referenced-array pseudo-enums. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(openapi): guard listInvalidProperties bounds checks for null values The maxLength/minLength/maximum/minimum/pattern/maxItems/minItems checks in listInvalidProperties() only skipped null for non-required properties ({{^required}}). Since the isNullableSetToNull work made required+nullable null a legitimately valid state, those checks now ran on null for such fields — coercing null to 0/"" and producing false invalids (e.g. RefShippingRulesImplications shipping_rule_id reported "must be bigger than or equal to 1"), plus mb_strlen(null) /preg_match(null) deprecation notices on PHP 8.1+. Emit the !is_null() guard unconditionally, matching the setter's isNullable guard. It is a harmless no-op for required non-nullable properties, which are already reported via the separate required-null check. Note: this only affects manual validation via valid()/listInvalidProperties(); the serialization path (sanitizeForSerialization) does not call them. Also fix a docblock typo in UnknownEnumPassthroughTest. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * test(openapi): use a fresh Configuration instead of the global singleton CarrierContractDefinitionsServiceTest mutated the global default Configuration singleton via getDefaultConfiguration()->setApiKey(), which can leak auth state into other tests and cause order-dependent failures. Use a fresh Configuration instance. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(openapi): correct bigid maximum that overflowed PHP_INT_MAX common_parameters_bigid (and an inline shipping_rule_id schema) in the private spec declared maximum: 9223372036854776000, which exceeds PHP_INT_MAX (9223372036854775807). The generator emitted it as a PHP int literal that overflowed to a negative int64, so the generated bound check ($id > -9223372036854775616) was always true — setId() threw and listInvalidProperties() falsely rejected every real id. Correct the maximum to the actual int64 max (9223372036854775807). Private client only; the remote CoreApi/OrderApi/IamApi specs do not define this bound. Note: openapi/specs/coreapi-private.yaml is a local stand-in (see its inputSpec @todo); the authoritative private spec should carry the same correction to avoid regressing once it is hosted. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

## [11.0.0-beta.29](v11.0.0-beta.28...v11.0.0-beta.29) (2026-07-09) ### ⚠ BREAKING CHANGES * **openapi:** loosen and apply consistent validation for enum values, fix required nullables (#623) ### ✨ New Features * **openapi:** loosen and apply consistent validation for enum values, fix required nullables ([#623](#623)) ([2164721](2164721)), closes [OpenAPITools/openapi-generator#22292](OpenAPITools/openapi-generator#22292) [OpenAPITools/openapi-generator#22292](OpenAPITools/openapi-generator#22292)

## [11.0.0-beta.1](v10.7.13...v11.0.0-beta.1) (2026-09-15) ### ⚠ BREAKING CHANGES * **openapi:** loosen and apply consistent validation for enum values, fix required nullables (#623) * remove legacy consignment stack and finalize v11 migration paths (#615) * remove dropoff point from maintained code (#589) * **api:** add clients for iam- and order (v2) services (#590) * **capabilities:** add capabilities functionality to the SDK (#551) ### ⏪ Reverts * Revert "ci: block broken release action" ([36352e0](36352e0)) * remove legacy consignment stack and finalize v11 migration paths ([#615](#615)) ([8e7bf22](8e7bf22)) ### 🐛 Bug Fixes * accept tracktrace sender email values ([83dcb2a](83dcb2a)) * add Italian carriers to legacy factory ([9f2e75d](9f2e75d)) * align service calls with regenerated user-agent parameter ([35be807](35be807)) * **api:** fix `isBusiness` defaulting to `true` rathern than `null` in capabilities requests ([#631](#631)) ([847d86f](847d86f)) * **ci:** correct phpunit coverage exclude path to ./src/Client/Generated ([1335e9d](1335e9d)), closes [#590](#590) * conform to json standard in composer ([e4faff5](e4faff5)) * consumer portal link mapping ([#620](#620)) ([a38d977](a38d977)) * harden v11 shipment service wrappers against spec/client drift ([#614](#614)) ([1a43a87](1a43a87)) * **openapi:** fix monetary amounts not being serialized ([#598](#598)) ([8fe3148](8fe3148)) * override iam principal deserialization ([#611](#611)) ([d190cbf](d190cbf)) * pass tracktrace user agent correctly ([bcabf79](bcabf79)) * replace deprecated JSON encoding ([#635](#635)) ([04d81e2](04d81e2)) * **v11:** security fix tar vulnerability and update @myparcel-dev/semantic-release-config ([#600](#600)) ([a82c1bb](a82c1bb)) * **v11:** Shipment extends correct generated class ([5510e6b](5510e6b)) ### ✨ New Features * add carrier contract definitions service ([#619](#619)) ([4d10df2](4d10df2)) * add pickup support to capabilities request ([8968981](8968981)) * **api:** add clients for iam- and order (v2) services ([#590](#590)) ([5dcff2c](5dcff2c)) * **api:** add private coreapi client for shipping rules ([#617](#617)) ([48dbee8](48dbee8)) * **api:** add the ecommerce api factory ([#646](#646)) ([809863c](809863c)), closes [#645](#645) [#645](#645) [#645](#645) * **api:** generate the ecommerce api client ([#643](#643)) ([88a1977](88a1977)), closes [#638](#638) * **api:** include API updates in releases ([a42b978](a42b978)) * **api:** update API clients ([658d49f](658d49f)) * **api:** update API clients ([#594](#594)) ([dc9addb](dc9addb)) * **api:** update API clients ([#597](#597)) ([d771ebe](d771ebe)) * **api:** update API clients ([#601](#601)) ([09a6c99](09a6c99)) * **api:** update API clients ([#603](#603)) ([e73d7a8](e73d7a8)) * **api:** update API clients ([#604](#604)) ([6e570d3](6e570d3)) * **api:** update API clients ([#608](#608)) ([11d17cc](11d17cc)) * **api:** update API clients ([#610](#610)) ([82d9ad9](82d9ad9)) * **api:** update API clients ([#621](#621)) ([e944f0f](e944f0f)) * **api:** update API clients ([#622](#622)) ([ee94860](ee94860)) * **api:** update API clients ([#633](#633)) ([cccc3e3](cccc3e3)) * **api:** update API clients ([#637](#637)) ([4e1e58b](4e1e58b)) * capabilities from shipments ([#584](#584)) ([3c5a6bc](3c5a6bc)) * **capabilities:** add capabilities functionality to the SDK ([#551](#551)) ([41d76e0](41d76e0)) * **connect:** add connect config, state and storage contract ([#639](#639)) ([9f93d1a](9f93d1a)), closes [#643](#643) * **connect:** add DPoP crypto primitives ([#638](#638)) ([fd4a30f](fd4a30f)) * **connect:** add the connect proof of concept ([#649](#649)) ([7b1843a](7b1843a)), closes [#646](#646) * **connect:** add the connect service and its transport ([#641](#641)) ([85ccefc](85ccefc)), closes [#639](#639) * **connect:** sign ecommerce requests with DPoP ([#645](#645)) ([8214bfe](8214bfe)), closes [#641](#641) * introduce label- and track & trace services for shipment domain ([#588](#588)) ([22b97fa](22b97fa)) * introduce shipment query, delete, return and multi-collo services ([#596](#596)) ([a0773b3](a0773b3)) * **openapi:** loosen and apply consistent validation for enum values, fix required nullables ([#623](#623)) ([9d20c57](9d20c57)), closes [OpenAPITools/openapi-generator#22292](OpenAPITools/openapi-generator#22292) [OpenAPITools/openapi-generator#22292](OpenAPITools/openapi-generator#22292) * remove dropoff point from maintained code ([#589](#589)) ([d7d9f0c](d7d9f0c)) * Shipment-first create flow (generated Core API client) ([#587](#587)) ([4bff98a](4bff98a))

achton changed the title ~~[php]~~ [php] Fix PHP generator validation for nullable required properties Nov 6, 2025

achton mentioned this pull request Nov 6, 2025

[BUG] [php] Property is both nullable and non-nullable #21497

Closed

wing328 reviewed Nov 6, 2025

View reviewed changes

Comment thread modules/openapi-generator/src/main/resources/php/model_generic.mustache Outdated

achton added 2 commits November 7, 2025 13:15

[php] Fix null+required properties to accept null values in generated…

b9db5f2

… models. Also fix PHP annotations related to same.

[php] Update samples.

5e2e7e5

achton force-pushed the fix-issue-21497-php-null-nullable branch from ec75a1d to 5e2e7e5 Compare November 7, 2025 12:15

wing328 reviewed Nov 7, 2025

View reviewed changes

wing328 merged commit fb444bf into OpenAPITools:master Nov 8, 2025
27 checks passed

wing328 added this to the 7.18.0 milestone Nov 8, 2025

wing328 added Client: PHP Issue: Bug labels Nov 8, 2025

wing328 mentioned this pull request Nov 8, 2025

Add check for optional to show null in doc (php) #22307

Merged

6 tasks

JulianVennen mentioned this pull request Nov 11, 2025

[BUG] [PHP] generator ignores oneOf null branch, treating property as non-nullable #22185

Open

6 tasks

Navigation Menu

Uh oh!

[php] Fix PHP generator validation for nullable required properties - #22292

[php] Fix PHP generator validation for nullable required properties#22292
wing328 merged 2 commits into
OpenAPITools:masterfrom
achton:fix-issue-21497-php-null-nullable

achton commented Nov 6, 2025

Uh oh!

Uh oh!

wing328 Nov 7, 2025

Uh oh!

wing328 Nov 7, 2025

Uh oh!

wing328 commented Nov 8, 2025 •

edited

Loading

Uh oh!

Uh oh!

wing328 commented Nov 9, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

achton commented Nov 6, 2025

PR checklist

Uh oh!

Uh oh!

wing328 Nov 7, 2025

Choose a reason for hiding this comment

Uh oh!

wing328 Nov 7, 2025

Choose a reason for hiding this comment

Uh oh!

wing328 commented Nov 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

wing328 commented Nov 9, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

wing328 commented Nov 8, 2025 •

edited

Loading