← Back to branch summary

~ubuntu-branches/ubuntu/wily/phabricator/wily

« back to all changes in this revision

Viewing changes to phabricator/src/applications/policy/interface/PhabricatorExtendedPolicyInterface.php

  • Committer: Package Import Robot
  • Author(s): Richard Sellam
  • Date: 2015-06-13 10:52:10 UTC
  • mfrom: (0.30.1) (0.29.1) (0.17.4) (2.1.9 sid)
  • Revision ID: package-import@ubuntu.com-20150613105210-5uirr7tvnk0n6e6y
Tags: 0~git20150613-1
http://bugs.debian.org/787805
http://bugs.debian.org/787645
* New snapshot release (closes: #787805)
* fixed typo in logrotate script (closes: #787645)

Show diffs side-by-side

added added

removed removed

Lines of Context:
phabricator/src/applications/policy/interface/PhabricatorExtendedPolicyInterface.php
 
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
 */
 
25
interface 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 const Capability being tested.
 
66
   * @param PhabricatorUser Viewer whose capabilities are being tested.
 
67
   * @return list<pair<wild, wild>> 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
*/