recaptime.dev
@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<?php
2
3/**
4 * Allows an object to define a more complex policy than it can with
5 * @{interface:PhabricatorPolicyInterface} alone.
6 *
7 * Some objects have complex policies which depend on the policies of other
8 * objects. For example, users can generally only see a Revision in
9 * Differential if they can also see the Repository it belongs to.
10 *
11 * These policies are normally enforced implicitly in the Query layer, by
12 * discarding objects which have related objects that can not be loaded. In
13 * most cases this has the same effect as really applying these policy checks
14 * would.
15 *
16 * However, in some cases an object's policies are later checked by a different
17 * viewer. For example, before we execute Herald rules, we check that the rule
18 * owners can see the object we are about to evaluate.
19 *
20 * In these cases, we need to account for these complex policies. We could do
21 * this by reloading the object over and over again for each viewer, but this
22 * implies a large performance cost. Instead, extended policies make it
23 * efficient to check policies against an object for multiple viewers.
24 */
25interface PhabricatorExtendedPolicyInterface {
26
27 /**
28 * Get the extended policy for an object.
29 *
30 * Return a list of additional policy checks that the viewer must satisfy
31 * in order to have the specified capability. This allows you to encode rules
32 * like "to see a revision, the viewer must also be able to see the repository
33 * it belongs to".
34 *
35 * For example, to specify that the viewer must be able to see some other
36 * object in order to see this one, you could return:
37 *
38 * return array(
39 * array($other_object, PhabricatorPolicyCapability::CAN_VIEW),
40 * // ...
41 * );
42 *
43 * If you don't have the actual object you want to check, you can return its
44 * PHID instead:
45 *
46 * return array(
47 * array($other_phid, PhabricatorPolicyCapability::CAN_VIEW),
48 * // ...
49 * );
50 *
51 * You can return a list of capabilities instead of a single capability if
52 * you want to require multiple capabilities on a single object:
53 *
54 * return array(
55 * array(
56 * $other_object,
57 * array(
58 * PhabricatorPolicyCapability::CAN_VIEW,
59 * PhabricatorPolicyCapability::CAN_EDIT,
60 * ),
61 * ),
62 * // ...
63 * );
64 *
65 * @param string $capability Constant of the capability being tested.
66 * @param PhabricatorUser $viewer Viewer whose capabilities are being tested.
67 * @return array<array<scalar, mixed>> List of extended policies.
68 */
69 public function getExtendedPolicy($capability, PhabricatorUser $viewer);
70
71}
72
73// TEMPLATE IMPLEMENTATION /////////////////////////////////////////////////////
74
75/* -( PhabricatorExtendedPolicyInterface )--------------------------------- */
76/*
77
78 public function getExtendedPolicy($capability, PhabricatorUser $viewer) {
79 $extended = array();
80 switch ($capability) {
81 case PhabricatorPolicyCapability::CAN_VIEW:
82 // ...
83 break;
84 }
85 return $extended;
86 }
87
88*/