Improve PHPDoc Consistency Across the Codebase

[francescobianco]

Summary

While working on the PHPStan static analysis setup, several areas of the codebase were identified where PHPDoc annotations could be improved for better consistency and stronger static analysis support.

In particular, many array parameters, return types, and class properties would benefit from more explicit iterable value type annotations.

Proposed Improvements

• Add explicit iterable value types for arrays
• Improve PHPDoc consistency across classes and methods
• Refine parameter and return type annotations where helpful
• Reduce ambiguous or missing PHPDoc declarations
• Improve compatibility with stricter PHPStan analysis levels

Goal

The goal of this issue is to progressively improve the maintainability and static analysis quality of the project while keeping the codebase easier to understand and contribute to.

This work would complement the PHPStan setup introduced in PR #35.

Thanks @Seraphim200001

[Seraphim200001]

@francescobianco I will work on it and implement the things we considered.

[Seraphim200001]

@francescobianco Sorry for the delay, but because of sick colleagues, it is hell at work. I think next week everything will be back to normal

[francescobianco]

@Seraphim200001 No worries at all. That's one of the beautiful things about open source: there are no deadlines or obligations here, only people sharing their time, ideas, and passion when they can.

Take care of your work priorities first, and please don't feel any pressure from our side. We wish your colleague a speedy recovery and hope things return to normal for your team soon.

Looking forward to hearing from you whenever you have time. 😊