[petrknap]

• This pull request does not contain any breaking change.
• I asked the AI to briefly summarize, use and improve the feature(s), and I'm okay with the output:

Here is a thorough code review of the pull request for petrknap/php-optional:

---

1. Summary of Changes

This pull request introduces minor refactorings to improve API design, documentation clarity, and usage recommendations:

• README.md Update:

• Replaced an older, verbose isPresent() + get() pattern in the basic usage example with a cleaner orElse('missing data') approach.

• Added clarifying comments to the example snippet.

• Deprecations in src/Optional.php:

• Formally marked get() as @deprecated Not recommended; use self::orElseThrow() instead. (previously it only had a @see reference).

• Formally marked ifPresentOrElse() as @deprecated Not recommended; use self::ifPresent() instead. (aligning with ifPresent's newly updated support for an else callback).

---

2. Code Quality & Standards Assessment

• Adherence to Library Patterns: The changes are clean and fully consistent with the library’s goal of matching Java-like optional semantics while leaning into ergonomic PHP idioms (such as inline fallback values and unified consumer-else structures).
• Backward Compatibility: Marking methods as @deprecated in docblocks is safe and non-breaking for existing consumers, giving them a clear migration path toward orElseThrow() and ifPresent(..., else: ...) without causing immediate fatal errors or deprecation notices in older PHP versions unless configured.
• Documentation & Tests: The changes to the README.md keep the documentation aligned with best practices recommended by the library. Existing test suites (ReadmeTest, OptionalTest) continue to validate execution.

---

3. Recommendation

• Status: Approve / Ready to Merge
• Reasoning: The changes are low-risk, well-documented, improve developer experience, and correctly steer users toward safer/cleaner API alternatives.