Add PHPStan at level 6 for static analysis

[francescobianco]

Problem

The codebase currently has no static analysis. Some methods return mixed without strict typing enforcement, which hides potential bugs.

For example in src/OauthClient.php:

private function request(string $method, string $url, ?array $body = null): string
{
    // $response could be false on curl failure — currently not typed strictly
    $response = curl_exec($ch);
    ...
}

Running phpstan analyse src/ --level=6 already reports issues like:

 ------ -------------------------------------------------------
  Line   src/OauthClient.php
 ------ -------------------------------------------------------
  78     Variable $ch might not be defined.
  83     Parameter #1 $ch of function curl_setopt expects resource, CurlHandle|false given.
 ------ -------------------------------------------------------

Proposal

• Add phpstan/phpstan to require-dev
• Add a phpstan.neon config targeting level 6
• Add a composer run analyse script

Open questions

• Level 6 or level 8? Level 8 requires full generics annotation which may be too strict for now.
• Should PHPStan run in CI on every PR?

[Seraphim200001]

@francescobianco I would like to contribute this to the project. However, the upkeep branch is no longer there. In which branch should I work?

PS: Thanks for the kind words in the release notes, they made me happy!

[francescobianco]

You’re very welcome 😊 @Seraphim200001

And yes — we officially switched back to using main as the primary branch, so you can work directly against main.

Thanks again for your contributions and support, really appreciated!

[Seraphim200001]

@francescobianco I have opened the PR for the PHPStan static analysis setup here: #35

As a follow-up, I would also suggest using this ticket to consider making the codebase more consistently PHPDoc-compliant overall. While fixing the PHPStan issues, I noticed that several array parameters and properties benefit from explicit PHPDoc annotations, especially for iterable value types.

If this is something you would like to include in the scope of this issue, I would be happy to help with that as well.

Additionally, I propose adding a second Composer command to allow more flexibility with analysis levels:
composer run analyze: This will remain the standard command, fixed at level 6.
composer run analyze:level: A specific command where we can pass the desired level as an argument (e.g., composer run analyze:level 8).This way, we have a stable baseline for CI, but can easily test higher strictness levels during development.

[francescobianco]

Thanks @Seraphim200001 for opening the PR and for the detailed suggestions — really appreciated.

I agree that improving the overall PHPDoc consistency would be a valuable addition to the scope of this work, especially if it helps make the codebase more maintainable and improves static analysis quality over time. Explicit iterable value types and clearer annotations definitely make sense.

I also like the idea of splitting the analysis commands:

• composer run analyze as the stable CI baseline at level 6
• composer run analyze:level <n> for experimenting with stricter levels locally

That sounds like a good balance between stability and flexibility.

Feel free to include these improvements as part of the PR/issue scope.

[Seraphim200001]

@francescobianco Thank you for the feedback! I’m glad you agree with the proposed changes