recaptime.dev / phorge
@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.) hq.recaptime.dev/wiki/Phorge
phorge phabricator
1
fork

Configure Feed

Select the types of activity you want to include in your feed.

Add phpDoc to PhabricatorCursorPagedPolicyAwareQuery

Summary:
Adding class templates to `PhabricatorPolicyAwareQuery` and
`PhabricatorCursorPagedPolicyAwareQuery` to make `execute()` have the right
return signature, when the query classes are also annotated. Otherwise, the
return type is inferred as `PhabricatorPolicyInterface` as before.

Test Plan:
Add some annotations to query classes and see that `$query->execute()` infers
the more specific return type.

Diviner still works after ./bin/diviner generate. For example this page still exist:

/book/dev/class/PhabricatorCursorPagedPolicyAwareQuery/

And the method newResultObject() is now documented with the return type R|null.

Reviewers: O1 Blessed Committers, valerio.bozzolan

Reviewed By: O1 Blessed Committers, valerio.bozzolan

Subscribers: aklapper, tobiaswiese, valerio.bozzolan, Matthew, Cigaryno

Differential Revision: https://we.phorge.it/D26037

amy bones 425ab7a8 6d219783

+26 -13
+6
src/infrastructure/query/policy/PhabricatorCursorPagedPolicyAwareQuery.php
··· 12 12 * @task order Result Ordering 13 13 * @task edgelogic Working with Edge Logic 14 14 * @task spaces Working with Spaces 15 + * 16 + * @template R of PhabricatorPolicyInterface 17 + * @extends PhabricatorPolicyAwareQuery<R> 15 18 */ 16 19 abstract class PhabricatorCursorPagedPolicyAwareQuery 17 20 extends PhabricatorPolicyAwareQuery { ··· 439 442 return null; 440 443 } 441 444 445 + /** 446 + * @return R|null 447 + */ 442 448 public function newResultObject() { 443 449 return null; 444 450 }
+15 -13
src/infrastructure/query/policy/PhabricatorPolicyAwareQuery.php
··· 25 25 * @task config Query Configuration 26 26 * @task exec Executing Queries 27 27 * @task policyimpl Policy Query Implementation 28 + * 29 + * @template R of PhabricatorPolicyInterface 28 30 */ 29 31 abstract class PhabricatorPolicyAwareQuery extends PhabricatorOffsetPagedQuery { 30 32 ··· 170 172 * example, the user is trying to view or edit an object which exists but 171 173 * which they do not have permission to see) a policy exception is thrown. 172 174 * 173 - * @return mixed Single result, or null. 175 + * @return R|null Single result, or null. 174 176 * @task exec 175 177 */ 176 178 final public function executeOne() { ··· 198 200 /** 199 201 * Execute the query, loading all visible results. 200 202 * 201 - * @return list<PhabricatorPolicyInterface> Result objects. 203 + * @return R[] Result objects. 202 204 * @task exec 203 205 */ 204 206 final public function execute() { ··· 473 475 * automatically populated as a side effect of objects surviving policy 474 476 * filtering. 475 477 * 476 - * @param map<phid, PhabricatorPolicyInterface> $objects Objects to add to 478 + * @param array<phid, PhabricatorPolicyInterface> $objects Objects to add to 477 479 * the query workspace. 478 480 * @return $this 479 481 * @task workspace ··· 552 554 * 553 555 * PHIDs which are "in flight" are actively being queried for. 554 556 * 555 - * @return map<string, string> PHIDs currently in flight. 557 + * @return array<string, string> PHIDs currently in flight. 556 558 */ 557 559 public function getPHIDsInFlight() { 558 560 $results = $this->inFlightPHIDs; ··· 595 597 * from the database. They should attempt to return the number of results 596 598 * hinted by @{method:getRawResultLimit}. 597 599 * 598 - * @return list<PhabricatorPolicyInterface> List of filterable policy objects. 600 + * @return R[] List of filterable policy objects. 599 601 * @task policyimpl 600 602 */ 601 603 abstract protected function loadPage(); ··· 606 608 * return new results. Generally, you should adjust a cursor position based 607 609 * on the provided result page. 608 610 * 609 - * @param list<PhabricatorPolicyInterface> $page The current page of results. 611 + * @param R[] $page The current page of results. 610 612 * @return void 611 613 * @task policyimpl 612 614 */ ··· 627 629 * This method will only be called if data is available. Implementations 628 630 * do not need to handle the case of no results specially. 629 631 * 630 - * @param list<wild> $page Results from `loadPage()`. 631 - * @return list<PhabricatorPolicyInterface> Objects for policy filtering. 632 + * @param R[] $page Results from `loadPage()`. 633 + * @return R[] Objects for policy filtering. 632 634 * @task policyimpl 633 635 */ 634 636 protected function willFilterPage(array $page) { ··· 650 652 * This method will only be called if data is available. Implementations do 651 653 * not need to handle the case of no results specially. 652 654 * 653 - * @param list<wild> $page Results from @{method:willFilterPage()}. 654 - * @return list<PhabricatorPolicyInterface> Objects after additional 655 + * @param R[] $page Results from @{method:willFilterPage()}. 656 + * @return R[] Objects after additional 655 657 * non-policy processing. 656 658 */ 657 659 protected function didFilterPage(array $page) { ··· 665 667 * filtered for policy reasons. The query should remove them from any cached 666 668 * or partial result sets. 667 669 * 668 - * @param list<wild> $results List of objects that should not be returned by 670 + * @param R[] $results List of objects that should not be returned by 669 671 * alternate result mechanisms. 670 672 * @return void 671 673 * @task policyimpl ··· 680 682 * used by @{class:PhabricatorCursorPagedPolicyAwareQuery} to reverse results 681 683 * that are queried during reverse paging. 682 684 * 683 - * @param list<PhabricatorPolicyInterface> $results Query results. 684 - * @return list<PhabricatorPolicyInterface> Final results. 685 + * @param R[] $results Query results. 686 + * @return R[] Final results. 685 687 * @task policyimpl 686 688 */ 687 689 protected function didLoadResults(array $results) {
+5
src/view/control/AphrontCursorPagerView.php
··· 70 70 return $this->prevPageID; 71 71 } 72 72 73 + /** 74 + * @param T[] $results 75 + * @return T[] 76 + * @template T 77 + */ 73 78 public function sliceResults(array $results) { 74 79 if (count($results) > $this->getPageSize()) { 75 80 $page_size = (int)$this->getPageSize();