Loading
docs: #3583031 Document the access() contract and its input-validation gate
Closes #3583031 (closed)
Summary
Scoped per @michaellander's comment: item 4 plus writing the access() contract down. No behaviour change. Items 1 (Forbidden vs Neutral) and 3 (the values-free question) are left for the access-phases / runner follow-ups; item 2 was crossed out in the summary.
ToolInterface::access()docblock now states the question it answers, that the answer is value-dependent and can change aftersetInputValue(), that it is deliberately not an answer to "may this account use this tool at all", why the validation denial is generic and not cacheable (#3582961 (closed)), and that callers must callvalidateInputs()first to tell a correctable argument problem from a permission problem. Return value documented,@seelinks added.ToolBase::access(): thecatchbranch gets a comment with the same reasoning.ToolBase::checkAccess(): two stale lines fixed — "By default, it returns forbidden access" (the method is abstract) and "Defaults to current user" on$account(already resolved byaccess()).docs/configuration.mdanddocs/developers/creating-a-tool.md: the same contract for consumers and tool authors, with a validate-then-access snippet. This goes slightly past "the docblock" — happy to drop it if you want the MR tighter.
Notes for review
- The docblock cites #3583031 (closed) as where the design for splitting the two questions lives. Once the follow-up issues exist, that reference should point at them instead.
- Diff touches no executable code and no tests; the existing
ToolBaseTest::testAccess*cases already pin the documented behaviour.
Testing
| Check | Result |
|---|---|
phpcs (project phpcs.xml, all of src/) |
0 errors, 0 warnings |
| phpstan level 3, module config | no errors |
| PHPUnit full suite, Drupal 11.4.7 / PHP 8.3 | 589 tests, 2,279 assertions, 0 failures |
mkdocs build --strict |
clean, new anchor link verified |