Discussion: Missing PHP return type declarations in Session, Config, and Console classes

[sumaiazaman]

Background

PR #57343 was recently closed, which aimed to add missing PHP return type declarations to various Laravel framework classes. The PR included improvements to type safety and developer experience by adding explicit return type declarations to methods that had docblock types but were missing PHP return types.

Affected Areas

The PR addressed missing return type declarations in:

Session Classes

• EncryptedStore::getEncrypter(): EncrypterContract
• CacheBasedSessionHandler::getCache(): CacheContract
• SessionManager methods: shouldBlock(): bool, blockDriver(): ?string, etc.

Config Classes

• Repository methods: has(): bool, get(): mixed, getMany(): array, etc.

Console Classes

• PruneStaleTagsCommand::getArguments(): array
• ConfigMakeCommand::promptForMissingArgumentsUsing(): array
• ConfigCacheCommand::handle(): void

Benefits of Adding Return Types

1. Enhanced Type Safety: Explicit return types catch type-related errors at compile time
2. Better IDE Support: Improved autocompletion and static analysis
3. Developer Experience: Clearer method contracts and better documentation
4. Modern PHP Standards: Aligns with PHP 8.2+ best practices
5. Backward Compatibility: All proposed changes were fully backward compatible

Questions for Discussion

1. Policy Clarification: Is there a specific policy or guideline regarding when to add return type declarations to existing methods?

2. Incremental Approach: Would a more targeted approach be preferred (e.g., focusing on one subsystem at a time)?

3. Breaking Changes Concern: Are there concerns about potential breaking changes, even though return type declarations are generally backward compatible?

4. Timing: Is this type of improvement better suited for major version releases?

5. Community Input: Should this type of enhancement go through an RFC process or community discussion first?

Proposed Next Steps

• Clarify the framework's stance on adding return type declarations to existing methods
• Determine if there are specific guidelines or criteria for such improvements
• Consider whether a more focused or phased approach would be more appropriate
• Gather community feedback on the value and timing of such improvements

Related

• Closed PR: [12.x] Add missing PHP return type declarations to Session, Config, and Console classes #57343
• This discussion aims to understand the reasoning behind the closure and explore potential paths forward for improving type safety in the Laravel framework.

---

Note: This issue is created to foster discussion and understanding, not to challenge the maintainers' decision. The goal is to learn and potentially find alternative approaches that align with the project's direction.

[macropay-solutions]

This discussion aims to understand the reasoning behind the closure and explore potential paths forward for improving type safety in the Laravel framework.

If you add return types will result in bugs and breaking changes.

[shaedrich]

As they are potential breaking changes, these should be directed at master/13.x

[mbabker]

This discussion aims to understand the reasoning behind the closure and explore potential paths forward for improving type safety in the Laravel framework.

If you add return types will result in bugs and breaking changes.

TBF, some of the bugs I've seen from the added return types boil down to the framework's apparent philosophy of "types are optional" colliding with the greater PHP ecosystem's shift toward well typed applications and integrations (one PR was reverted this week because folks were returning a value not implementing an interface in their test factories, and the proper signature broke their tests, so the framework instead made a change to keep this undocumented use case supported).

So long as the framework treats ignoring the doc block type information as a feature, there's no point in trying to go any further with these changes.