Skip to content

[6.x] Fix nullable return types in form docblocks#15018

Closed
jasonbaciulis wants to merge 1 commit into
statamic:6.xfrom
jasonbaciulis:fix/form-submission-nullable-docblocks
Closed

[6.x] Fix nullable return types in form docblocks#15018
jasonbaciulis wants to merge 1 commit into
statamic:6.xfrom
jasonbaciulis:fix/form-submission-nullable-docblocks

Conversation

@jasonbaciulis

@jasonbaciulis jasonbaciulis commented Jul 16, 2026

Copy link
Copy Markdown

Problem

Several docblocks in the Forms domain declare non-nullable return types for methods that can return null:

  • Form::submission($id) (concrete class and contract) is annotated @return Submission, but it delegates to FormSubmission::find($id), whose repository implementation returns ?Submission.
  • The FormSubmission facade annotates @method static SubmissionContract find($id) for the same nullable lookup.
  • FormRepository::find($handle) is annotated @return FormContract, but returns null when the form's YAML file doesn't exist, and the Form facade's @method annotation repeats the non-nullable type.

This breaks static analysis in apps consuming Statamic. For example, PHPStan (with default treatPhpDocTypesAsCertain: true) reports a guard like this as dead code:

$submission = Form::find($handle)->submission($id);

if (! $submission) { // "Negated boolean expression is always false" (booleanNot.alwaysFalse)
    return;
}

…even though the null check is genuinely reachable at runtime. It also gives IDEs false confidence, hiding potential null-dereference bugs.

Solution

Correct the five docblocks to |null, matching what the methods actually return. Docblock-only change — no behavior changes, so no new test case.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant