Skip to content

[5.x] Add native parameter, return and property types - #107

Open
Hackwar wants to merge 3 commits into
joomla-framework:5.x-devfrom
Hackwar:5.x-native-types
Open

Hackwar wants to merge 3 commits into
joomla-framework:5.x-devfrom
Hackwar:5.x-native-types

Conversation

@Hackwar

@Hackwar Hackwar commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Summary of Changes

No method in the package had native parameter or return types, and several doc blocks were wrong. This adds:

  • Parameter types from the doc blocks (string, int, bool, array, unions where documented), nullable where the default is null. Parameters whose default does not match the documented type, or that are documented as mixed, stay untyped (e.g. Gists::create($files), Users::edit($hireable), processResponse($expectedCode) — the latter accepts a list of codes after [4.x] Fix the expected status codes and fail on invalid JSON responses #92).
  • Wrong doc blocks corrected first, so the types follow GitHub's API: gist IDs are string (as in [4.x] Treat gist IDs as strings #86), Issues::create()/edit() milestone int|string|null, Milestones::create()/edit() title string, Pulls\Comments::create() position int, Releases::edit() body string and draft/prerelease bool, Data\Trees::create() tree array, Users::edit() hireable boolean|string. Two tests passed values of the wrong type and were adjusted (TreesTest::testCreate, ReleasesTest::testEdit).
  • Return types where a method always returns one type: bool (check…(), is…()), string, void, plus fetchUrl(): Uri, processResponse(): mixed, Github::getOption(): mixed, Github::setOption(): static, __get(). Methods returning the decoded JSON stay without a return type (object, array or null depending on the endpoint).
  • Property types for $options, $client, $package, $hookEvents.

Not done: making classes final. The package classes are meant to be extended and mocked (the tests mock them), so whether any of them should be final is left to the maintainers.

Depends on #106 (removal of the dead-endpoint wrappers, so they are not typed) and #105 (update guide); this branch contains both commits until they are merged.

Merge-up: this touches almost every method signature, so every open 4.x PR that changes a signature or doc block conflicts with it when 4.x-dev is merged into 5.x-dev (in particular #86, #87, #89, #90, #91, #92, #93, #96–#101 and the new API packages #68–#85, which need the same typing afterwards). Take the 4.x behaviour and re-apply the types.

Testing Instructions

vendor/bin/phpunit, phpstan (no new errors) and phpcs pass on 5.x-dev.

Documentation Changes Required

docs/v4-to-v5-update.md: new section on the native types and the corrected parameter types.

🤖 Generated with Claude Code

Hackwar and others added 3 commits November 13, 2026 00:21
Several 5.0 changes need to be listed in the update guide. Add it with
an empty list so those changes do not conflict over creating the file.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
These methods and classes target endpoints that GitHub has removed or
replaced, so they cannot work against the live API: the OAuth
Authorizations API, the Downloads API, the legacy search API, the legacy
watching and /teams/{team_id} routes, Orgs\Hooks::edit(), which created a
hook instead of editing one, and Users\Keys::edit(), for which GitHub has
no endpoint. They are deprecated in 4.x; remove them and list them with
their replacements in the update guide.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
No method had native types, and several doc blocks were wrong (gist IDs
documented as integer, the release draft flag as string, the milestone
title as integer, among others). Add parameter types from the doc
blocks after correcting them, return types where a method always
returns the same type, and property types, and list the changes in the
update guide.

Co-Authored-By: Claude Opus 5.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