No OneTemporary
Actions

Size

41 KB

Referenced Files

None

Subscribers

None

View Options

	diff --git a/src/applications/policy/__tests__/PhabricatorPolicyTestCase.php b/src/applications/policy/__tests__/PhabricatorPolicyTestCase.php
	index edd41d9c6b..860ca52f69 100644
	--- a/src/applications/policy/__tests__/PhabricatorPolicyTestCase.php
	+++ b/src/applications/policy/__tests__/PhabricatorPolicyTestCase.php
	@@ -1,308 +1,337 @@
	<?php

	final class PhabricatorPolicyTestCase extends PhabricatorTestCase {

	/**
	* Verify that any user can view an object with POLICY_PUBLIC.
	*/
	public function testPublicPolicyEnabled() {
	$env = PhabricatorEnv::beginScopedEnv();
	$env->overrideEnvConfig('policy.allow-public', true);

	$this->expectVisibility(
	$this->buildObject(PhabricatorPolicies::POLICY_PUBLIC),
	array(
	'public' => true,
	'user' => true,
	'admin' => true,
	),
	'Public Policy (Enabled in Config)');
	}


	/**
	* Verify that POLICY_PUBLIC is interpreted as POLICY_USER when public
	* policies are disallowed.
	*/
	public function testPublicPolicyDisabled() {
	$env = PhabricatorEnv::beginScopedEnv();
	$env->overrideEnvConfig('policy.allow-public', false);

	$this->expectVisibility(
	$this->buildObject(PhabricatorPolicies::POLICY_PUBLIC),
	array(
	'public' => false,
	'user' => true,
	'admin' => true,
	),
	'Public Policy (Disabled in Config)');
	}


	/**
	* Verify that any logged-in user can view an object with POLICY_USER, but
	* logged-out users can not.
	*/
	public function testUsersPolicy() {
	$this->expectVisibility(
	$this->buildObject(PhabricatorPolicies::POLICY_USER),
	array(
	'public' => false,
	'user' => true,
	'admin' => true,
	),
	'User Policy');
	}


	/**
	* Verify that only administrators can view an object with POLICY_ADMIN.
	*/
	public function testAdminPolicy() {
	$this->expectVisibility(
	$this->buildObject(PhabricatorPolicies::POLICY_ADMIN),
	array(
	'public' => false,
	'user' => false,
	'admin' => true,
	),
	'Admin Policy');
	}


	/**
	* Verify that no one can view an object with POLICY_NOONE.
	*/
	public function testNoOnePolicy() {
	$this->expectVisibility(
	$this->buildObject(PhabricatorPolicies::POLICY_NOONE),
	array(
	'public' => false,
	'user' => false,
	'admin' => false,
	),
	'No One Policy');
	}


	/**
	* Test offset-based filtering.
	*/
	public function testOffsets() {
	$results = array(
	$this->buildObject(PhabricatorPolicies::POLICY_NOONE),
	$this->buildObject(PhabricatorPolicies::POLICY_NOONE),
	$this->buildObject(PhabricatorPolicies::POLICY_NOONE),
	$this->buildObject(PhabricatorPolicies::POLICY_USER),
	$this->buildObject(PhabricatorPolicies::POLICY_USER),
	$this->buildObject(PhabricatorPolicies::POLICY_USER),
	);

	$query = new PhabricatorPolicyAwareTestQuery();
	$query->setResults($results);
	$query->setViewer($this->buildUser('user'));

	$this->assertEqual(
	3,
	count($query->setLimit(3)->setOffset(0)->execute()),
	'Invisible objects are ignored.');

	$this->assertEqual(
	0,
	count($query->setLimit(3)->setOffset(3)->execute()),
	'Offset pages through visible objects only.');

	$this->assertEqual(
	2,
	count($query->setLimit(3)->setOffset(1)->execute()),
	'Offsets work correctly.');

	$this->assertEqual(
	2,
	count($query->setLimit(0)->setOffset(1)->execute()),
	'Offset with no limit works.');
	}


	/**
	* Test limits.
	*/
	public function testLimits() {
	$results = array(
	$this->buildObject(PhabricatorPolicies::POLICY_USER),
	$this->buildObject(PhabricatorPolicies::POLICY_USER),
	$this->buildObject(PhabricatorPolicies::POLICY_USER),
	$this->buildObject(PhabricatorPolicies::POLICY_USER),
	$this->buildObject(PhabricatorPolicies::POLICY_USER),
	$this->buildObject(PhabricatorPolicies::POLICY_USER),
	);

	$query = new PhabricatorPolicyAwareTestQuery();
	$query->setResults($results);
	$query->setViewer($this->buildUser('user'));

	$this->assertEqual(
	3,
	count($query->setLimit(3)->setOffset(0)->execute()),
	'Limits work.');

	$this->assertEqual(
	2,
	count($query->setLimit(3)->setOffset(4)->execute()),
	'Limit + offset work.');
	}


	/**
	* Test that omnipotent users bypass policies.
	*/
	public function testOmnipotence() {
	$results = array(
	$this->buildObject(PhabricatorPolicies::POLICY_NOONE),
	);

	$query = new PhabricatorPolicyAwareTestQuery();
	$query->setResults($results);
	$query->setViewer(PhabricatorUser::getOmnipotentUser());

	$this->assertEqual(
	1,
	count($query->execute()));
	}


	/**
	* Test that invalid policies reject viewers of all types.
	*/
	public function testRejectInvalidPolicy() {
	$invalid_policy = "the duck goes quack";
	$object = $this->buildObject($invalid_policy);

	$this->expectVisibility(
	$object = $this->buildObject($invalid_policy),
	array(
	'public' => false,
	'user' => false,
	'admin' => false,
	),
	'Invalid Policy');
	}


	/**
	* An omnipotent user should be able to see even objects with invalid
	* policies.
	*/
	public function testInvalidPolicyVisibleByOmnipotentUser() {
	$invalid_policy = "the cow goes moo";
	$object = $this->buildObject($invalid_policy);

	$results = array(
	$object,
	);

	$query = new PhabricatorPolicyAwareTestQuery();
	$query->setResults($results);
	$query->setViewer(PhabricatorUser::getOmnipotentUser());

	$this->assertEqual(
	1,
	count($query->execute()));
	}

	public function testAllQueriesBelongToActualApplications() {
	$queries = id(new PhutilSymbolLoader())
	->setAncestorClass('PhabricatorPolicyAwareQuery')
	->loadObjects();

	foreach ($queries as $qclass => $query) {
	$class = $query->getQueryApplicationClass();
	if (!$class) {
	continue;
	}
	$this->assertEqual(
	true,
	(bool)PhabricatorApplication::getByClass($class),
	"Application class '{$class}' for query '{$qclass}'");
	}
	}

	+ public function testMultipleCapabilities() {
	+ $object = new PhabricatorPolicyTestObject();
	+ $object->setCapabilities(
	+ array(
	+ PhabricatorPolicyCapability::CAN_VIEW,
	+ PhabricatorPolicyCapability::CAN_EDIT,
	+ ));
	+ $object->setPolicies(
	+ array(
	+ PhabricatorPolicyCapability::CAN_VIEW
	+ => PhabricatorPolicies::POLICY_USER,
	+ PhabricatorPolicyCapability::CAN_EDIT
	+ => PhabricatorPolicies::POLICY_NOONE,
	+ ));
	+
	+ $filter = new PhabricatorPolicyFilter();
	+ $filter->requireCapabilities(
	+ array(
	+ PhabricatorPolicyCapability::CAN_VIEW,
	+ PhabricatorPolicyCapability::CAN_EDIT,
	+ ));
	+ $filter->setViewer($this->buildUser('user'));
	+
	+ $result = $filter->apply(array($object));
	+
	+ $this->assertEqual(array(), $result);
	+ }
	+
	+
	/**
	* Test an object for visibility across multiple user specifications.
	*/
	private function expectVisibility(
	PhabricatorPolicyTestObject $object,
	array $map,
	$description) {

	foreach ($map as $spec => $expect) {
	$viewer = $this->buildUser($spec);

	$query = new PhabricatorPolicyAwareTestQuery();
	$query->setResults(array($object));
	$query->setViewer($viewer);

	$caught = null;
	try {
	$result = $query->executeOne();
	} catch (PhabricatorPolicyException $ex) {
	$caught = $ex;
	}

	if ($expect) {
	$this->assertEqual(
	$object,
	$result,
	"{$description} with user {$spec} should succeed.");
	} else {
	$this->assertEqual(
	true,
	$caught instanceof PhabricatorPolicyException,
	"{$description} with user {$spec} should fail.");
	}
	}
	}


	/**
	* Build a test object to spec.
	*/
	private function buildObject($policy) {
	$object = new PhabricatorPolicyTestObject();
	$object->setCapabilities(
	array(
	PhabricatorPolicyCapability::CAN_VIEW,
	));
	$object->setPolicies(
	array(
	PhabricatorPolicyCapability::CAN_VIEW => $policy,
	));

	return $object;
	}


	/**
	* Build a test user to spec.
	*/
	private function buildUser($spec) {
	$user = new PhabricatorUser();

	switch ($spec) {
	case 'public':
	break;
	case 'user':
	$user->setPHID(1);
	break;
	case 'admin':
	$user->setPHID(1);
	$user->setIsAdmin(true);
	break;
	default:
	throw new Exception("Unknown user spec '{$spec}'.");
	}

	return $user;
	}

	}
	diff --git a/src/applications/policy/filter/PhabricatorPolicyFilter.php b/src/applications/policy/filter/PhabricatorPolicyFilter.php
	index 969e167d30..f3cac68765 100644
	--- a/src/applications/policy/filter/PhabricatorPolicyFilter.php
	+++ b/src/applications/policy/filter/PhabricatorPolicyFilter.php
	@@ -1,405 +1,405 @@
	<?php

	final class PhabricatorPolicyFilter {

	private $viewer;
	private $objects;
	private $capabilities;
	private $raisePolicyExceptions;
	private $userProjects;
	private $customPolicies = array();

	public static function mustRetainCapability(
	PhabricatorUser $user,
	PhabricatorPolicyInterface $object,
	$capability) {

	if (!self::hasCapability($user, $object, $capability)) {
	throw new Exception(
	"You can not make that edit, because it would remove your ability ".
	"to '{$capability}' the object.");
	}
	}

	public static function requireCapability(
	PhabricatorUser $user,
	PhabricatorPolicyInterface $object,
	$capability) {
	$filter = new PhabricatorPolicyFilter();
	$filter->setViewer($user);
	$filter->requireCapabilities(array($capability));
	$filter->raisePolicyExceptions(true);
	$filter->apply(array($object));
	}

	public static function hasCapability(
	PhabricatorUser $user,
	PhabricatorPolicyInterface $object,
	$capability) {

	$filter = new PhabricatorPolicyFilter();
	$filter->setViewer($user);
	$filter->requireCapabilities(array($capability));
	$result = $filter->apply(array($object));

	return (count($result) == 1);
	}

	public function setViewer(PhabricatorUser $user) {
	$this->viewer = $user;
	return $this;
	}

	public function requireCapabilities(array $capabilities) {
	$this->capabilities = $capabilities;
	return $this;
	}

	public function raisePolicyExceptions($raise) {
	$this->raisePolicyExceptions = $raise;
	return $this;
	}

	public function apply(array $objects) {
	assert_instances_of($objects, 'PhabricatorPolicyInterface');

	$viewer = $this->viewer;
	$capabilities = $this->capabilities;

	if (!$viewer \|\| !$capabilities) {
	throw new Exception(
	'Call setViewer() and requireCapabilities() before apply()!');
	}

	// If the viewer is omnipotent, short circuit all the checks and just
	// return the input unmodified. This is an optimization; we know the
	// result already.
	if ($viewer->isOmnipotent()) {
	return $objects;
	}

	$filtered = array();
	$viewer_phid = $viewer->getPHID();

	if (empty($this->userProjects[$viewer_phid])) {
	$this->userProjects[$viewer_phid] = array();
	}

	$need_projects = array();
	$need_policies = array();
	foreach ($objects as $key => $object) {
	$object_capabilities = $object->getCapabilities();
	foreach ($capabilities as $capability) {
	if (!in_array($capability, $object_capabilities)) {
	throw new Exception(
	"Testing for capability '{$capability}' on an object which does ".
	"not have that capability!");
	}

	$policy = $object->getPolicy($capability);
	$type = phid_get_type($policy);
	if ($type == PhabricatorProjectPHIDTypeProject::TYPECONST) {
	$need_projects[$policy] = $policy;
	}

	if ($type == PhabricatorPolicyPHIDTypePolicy::TYPECONST) {
	$need_policies[$policy] = $policy;
	}
	}
	}

	if ($need_policies) {
	$this->loadCustomPolicies(array_keys($need_policies));
	}

	// If we need projects, check if any of the projects we need are also the
	// objects we're filtering. Because of how project rules work, this is a
	// common case.
	if ($need_projects) {
	foreach ($objects as $object) {
	if ($object instanceof PhabricatorProject) {
	$project_phid = $object->getPHID();
	if (isset($need_projects[$project_phid])) {
	$is_member = $object->isUserMember($viewer_phid);
	$this->userProjects[$viewer_phid][$project_phid] = $is_member;
	unset($need_projects[$project_phid]);
	}
	}
	}
	}

	if ($need_projects) {
	$need_projects = array_unique($need_projects);

	// NOTE: We're using the omnipotent user here to avoid a recursive
	// descent into madness. We don't actually need to know if the user can
	// see these projects or not, since: the check is "user is member of
	// project", not "user can see project"; and membership implies
	// visibility anyway. Without this, we may load other projects and
	// re-enter the policy filter and generally create a huge mess.

	$projects = id(new PhabricatorProjectQuery())
	->setViewer(PhabricatorUser::getOmnipotentUser())
	->withMemberPHIDs(array($viewer->getPHID()))
	->withPHIDs($need_projects)
	->execute();

	foreach ($projects as $project) {
	$this->userProjects[$viewer_phid][$project->getPHID()] = true;
	}
	}

	foreach ($objects as $key => $object) {
	$object_capabilities = $object->getCapabilities();
	foreach ($capabilities as $capability) {
	if (!$this->checkCapability($object, $capability)) {
	// If we're missing any capability, move on to the next object.
	continue 2;
	}
	-
	- // If we make it here, we have all of the required capabilities.
	- $filtered[$key] = $object;
	}
	+
	+ // If we make it here, we have all of the required capabilities.
	+ $filtered[$key] = $object;
	}

	return $filtered;
	}

	private function checkCapability(
	PhabricatorPolicyInterface $object,
	$capability) {

	$policy = $object->getPolicy($capability);

	if (!$policy) {
	// TODO: Formalize this somehow?
	$policy = PhabricatorPolicies::POLICY_USER;
	}

	if ($policy == PhabricatorPolicies::POLICY_PUBLIC) {
	// If the object is set to "public" but that policy is disabled for this
	// install, restrict the policy to "user".
	if (!PhabricatorEnv::getEnvConfig('policy.allow-public')) {
	$policy = PhabricatorPolicies::POLICY_USER;
	}

	// If the object is set to "public" but the capability is not a public
	// capability, restrict the policy to "user".
	$capobj = PhabricatorPolicyCapability::getCapabilityByKey($capability);
	if (!$capobj \|\| !$capobj->shouldAllowPublicPolicySetting()) {
	$policy = PhabricatorPolicies::POLICY_USER;
	}
	}

	$viewer = $this->viewer;

	if ($viewer->isOmnipotent()) {
	return true;
	}

	if ($object->hasAutomaticCapability($capability, $viewer)) {
	return true;
	}

	switch ($policy) {
	case PhabricatorPolicies::POLICY_PUBLIC:
	return true;
	case PhabricatorPolicies::POLICY_USER:
	if ($viewer->getPHID()) {
	return true;
	} else {
	$this->rejectObject($object, $policy, $capability);
	}
	break;
	case PhabricatorPolicies::POLICY_ADMIN:
	if ($viewer->getIsAdmin()) {
	return true;
	} else {
	$this->rejectObject($object, $policy, $capability);
	}
	break;
	case PhabricatorPolicies::POLICY_NOONE:
	$this->rejectObject($object, $policy, $capability);
	break;
	default:
	$type = phid_get_type($policy);
	if ($type == PhabricatorProjectPHIDTypeProject::TYPECONST) {
	if (!empty($this->userProjects[$viewer->getPHID()][$policy])) {
	return true;
	} else {
	$this->rejectObject($object, $policy, $capability);
	}
	} else if ($type == PhabricatorPeoplePHIDTypeUser::TYPECONST) {
	if ($viewer->getPHID() == $policy) {
	return true;
	} else {
	$this->rejectObject($object, $policy, $capability);
	}
	} else if ($type == PhabricatorPolicyPHIDTypePolicy::TYPECONST) {
	if ($this->checkCustomPolicy($policy)) {
	return true;
	} else {
	$this->rejectObject($object, $policy, $capability);
	}
	} else {
	// Reject objects with unknown policies.
	$this->rejectObject($object, false, $capability);
	}
	}

	return false;
	}

	public function rejectObject(
	PhabricatorPolicyInterface $object,
	$policy,
	$capability) {

	if (!$this->raisePolicyExceptions) {
	return;
	}

	if ($this->viewer->isOmnipotent()) {
	// Never raise policy exceptions for the omnipotent viewer. Although we
	// will never normally issue a policy rejection for the omnipotent
	// viewer, we can end up here when queries blanket reject objects that
	// have failed to load, without distinguishing between nonexistent and
	// nonvisible objects.
	return;
	}

	$capobj = PhabricatorPolicyCapability::getCapabilityByKey($capability);
	$rejection = null;
	if ($capobj) {
	$rejection = $capobj->describeCapabilityRejection();
	$capability_name = $capobj->getCapabilityName();
	} else {
	$capability_name = $capability;
	}

	if (!$rejection) {
	// We couldn't find the capability object, or it doesn't provide a
	// tailored rejection string.
	$rejection = pht(
	'You do not have the required capability ("%s") to do whatever you '.
	'are trying to do.',
	$capability);
	}

	$more = PhabricatorPolicy::getPolicyExplanation($this->viewer, $policy);
	$exceptions = $object->describeAutomaticCapability($capability);

	$details = array_filter(array_merge(array($more), (array)$exceptions));

	// NOTE: Not every type of policy object has a real PHID; just load an
	// empty handle if a real PHID isn't available.
	$phid = nonempty($object->getPHID(), PhabricatorPHIDConstants::PHID_VOID);

	$handle = id(new PhabricatorHandleQuery())
	->setViewer($this->viewer)
	->withPHIDs(array($phid))
	->executeOne();

	$object_name = pht(
	'%s %s',
	$handle->getTypeName(),
	$handle->getObjectName());

	$is_serious = PhabricatorEnv::getEnvConfig('phabricator.serious-business');
	if ($is_serious) {
	$title = pht(
	'Access Denied: %s',
	$object_name);
	} else {
	$title = pht(
	'You Shall Not Pass: %s',
	$object_name);
	}

	$full_message = pht(
	'[%s] (%s) %s // %s',
	$title,
	$capability_name,
	$rejection,
	implode(' ', $details));

	$exception = id(new PhabricatorPolicyException($full_message))
	->setTitle($title)
	->setRejection($rejection)
	->setCapabilityName($capability_name)
	->setMoreInfo($details);

	throw $exception;
	}

	private function loadCustomPolicies(array $phids) {
	$viewer = $this->viewer;
	$viewer_phid = $viewer->getPHID();

	$custom_policies = id(new PhabricatorPolicyQuery())
	->setViewer($viewer)
	->withPHIDs($phids)
	->execute();
	$custom_policies = mpull($custom_policies, null, 'getPHID');


	$classes = array();
	$values = array();
	foreach ($custom_policies as $policy) {
	foreach ($policy->getCustomRuleClasses() as $class) {
	$classes[$class] = $class;
	$values[$class][] = $policy->getCustomRuleValues($class);
	}
	}

	foreach ($classes as $class => $ignored) {
	$object = newv($class, array());
	$object->willApplyRules($viewer, array_mergev($values[$class]));
	$classes[$class] = $object;
	}

	foreach ($custom_policies as $policy) {
	$policy->attachRuleObjects($classes);
	}

	if (empty($this->customPolicies[$viewer_phid])) {
	$this->customPolicies[$viewer_phid] = array();
	}

	$this->customPolicies[$viewer->getPHID()] += $custom_policies;
	}

	private function checkCustomPolicy($policy_phid) {
	$viewer = $this->viewer;
	$viewer_phid = $viewer->getPHID();

	$policy = $this->customPolicies[$viewer_phid][$policy_phid];

	$objects = $policy->getRuleObjects();
	$action = null;
	foreach ($policy->getRules() as $rule) {
	$object = idx($objects, idx($rule, 'rule'));
	if (!$object) {
	// Reject, this policy has a bogus rule.
	return false;
	}

	// If the user matches this rule, use this action.
	if ($object->applyRule($viewer, idx($rule, 'value'))) {
	$action = idx($rule, 'action');
	break;
	}
	}

	if ($action === null) {
	$action = $policy->getDefaultAction();
	}

	if ($action === PhabricatorPolicy::ACTION_ALLOW) {
	return true;
	}

	return false;
	}

	}
	diff --git a/src/infrastructure/query/policy/PhabricatorPolicyAwareQuery.php b/src/infrastructure/query/policy/PhabricatorPolicyAwareQuery.php
	index 55c6edc277..d2fd056e7f 100644
	--- a/src/infrastructure/query/policy/PhabricatorPolicyAwareQuery.php
	+++ b/src/infrastructure/query/policy/PhabricatorPolicyAwareQuery.php
	@@ -1,628 +1,628 @@
	<?php

	/**
	* A @{class:PhabricatorQuery} which filters results according to visibility
	* policies for the querying user. Broadly, this class allows you to implement
	* a query that returns only objects the user is allowed to see.
	*
	* $results = id(new ExampleQuery())
	* ->setViewer($user)
	* ->withConstraint($example)
	* ->execute();
	*
	* Normally, you should extend @{class:PhabricatorCursorPagedPolicyAwareQuery},
	* not this class. @{class:PhabricatorCursorPagedPolicyAwareQuery} provides a
	* more practical interface for building usable queries against most object
	* types.
	*
	* NOTE: Although this class extends @{class:PhabricatorOffsetPagedQuery},
	* offset paging with policy filtering is not efficient. All results must be
	* loaded into the application and filtered here: skipping `N` rows via offset
	* is an `O(N)` operation with a large constant. Prefer cursor-based paging
	* with @{class:PhabricatorCursorPagedPolicyAwareQuery}, which can filter far
	* more efficiently in MySQL.
	*
	* @task config Query Configuration
	* @task exec Executing Queries
	* @task policyimpl Policy Query Implementation
	*/
	abstract class PhabricatorPolicyAwareQuery extends PhabricatorOffsetPagedQuery {

	private $viewer;
	private $raisePolicyExceptions;
	private $parentQuery;
	private $rawResultLimit;
	private $capabilities;
	private $workspace = array();
	private $policyFilteredPHIDs = array();
	private $canUseApplication;


	/* -( Query Configuration )------------------------------------------------ */


	/**
	* Set the viewer who is executing the query. Results will be filtered
	* according to the viewer's capabilities. You must set a viewer to execute
	* a policy query.
	*
	* @param PhabricatorUser The viewing user.
	* @return this
	* @task config
	*/
	final public function setViewer(PhabricatorUser $viewer) {
	$this->viewer = $viewer;
	return $this;
	}


	/**
	* Get the query's viewer.
	*
	* @return PhabricatorUser The viewing user.
	* @task config
	*/
	final public function getViewer() {
	return $this->viewer;
	}


	/**
	* Set the parent query of this query. This is useful for nested queries so
	* that configuration like whether or not to raise policy exceptions is
	* seamlessly passed along to child queries.
	*
	* @return this
	* @task config
	*/
	final public function setParentQuery(PhabricatorPolicyAwareQuery $query) {
	$this->parentQuery = $query;
	return $this;
	}


	/**
	* Get the parent query. See @{method:setParentQuery} for discussion.
	*
	* @return PhabricatorPolicyAwareQuery The parent query.
	* @task config
	*/
	final public function getParentQuery() {
	return $this->parentQuery;
	}


	/**
	* Hook to configure whether this query should raise policy exceptions.
	*
	* @return this
	* @task config
	*/
	final public function setRaisePolicyExceptions($bool) {
	$this->raisePolicyExceptions = $bool;
	return $this;
	}


	/**
	* @return bool
	* @task config
	*/
	final public function shouldRaisePolicyExceptions() {
	- return (bool) $this->raisePolicyExceptions;
	+ return (bool)$this->raisePolicyExceptions;
	}


	/**
	* @task config
	*/
	final public function requireCapabilities(array $capabilities) {
	$this->capabilities = $capabilities;
	return $this;
	}


	/* -( Query Execution )---------------------------------------------------- */


	/**
	* Execute the query, expecting a single result. This method simplifies
	* loading objects for detail pages or edit views.
	*
	* // Load one result by ID.
	* $obj = id(new ExampleQuery())
	* ->setViewer($user)
	* ->withIDs(array($id))
	* ->executeOne();
	* if (!$obj) {
	* return new Aphront404Response();
	* }
	*
	* If zero results match the query, this method returns `null`.
	* If one result matches the query, this method returns that result.
	*
	* If two or more results match the query, this method throws an exception.
	* You should use this method only when the query constraints guarantee at
	* most one match (e.g., selecting a specific ID or PHID).
	*
	* If one result matches the query but it is caught by the policy filter (for
	* example, the user is trying to view or edit an object which exists but
	* which they do not have permission to see) a policy exception is thrown.
	*
	* @return mixed Single result, or null.
	* @task exec
	*/
	final public function executeOne() {

	$this->setRaisePolicyExceptions(true);
	try {
	$results = $this->execute();
	} catch (Exception $ex) {
	$this->setRaisePolicyExceptions(false);
	throw $ex;
	}

	if (count($results) > 1) {
	throw new Exception("Expected a single result!");
	}

	if (!$results) {
	return null;
	}

	return head($results);
	}


	/**
	* Execute the query, loading all visible results.
	*
	* @return list<PhabricatorPolicyInterface> Result objects.
	* @task exec
	*/
	final public function execute() {
	if (!$this->viewer) {
	throw new Exception("Call setViewer() before execute()!");
	}

	$parent_query = $this->getParentQuery();
	if ($parent_query) {
	$this->setRaisePolicyExceptions(
	$parent_query->shouldRaisePolicyExceptions());
	}

	$results = array();

	$filter = $this->getPolicyFilter();

	$offset = (int)$this->getOffset();
	$limit = (int)$this->getLimit();
	$count = 0;

	if ($limit) {
	$need = $offset + $limit;
	} else {
	$need = 0;
	}

	$this->willExecute();

	do {
	if ($need) {
	$this->rawResultLimit = min($need - $count, 1024);
	} else {
	$this->rawResultLimit = 0;
	}

	if ($this->canViewerUseQueryApplication()) {
	try {
	$page = $this->loadPage();
	} catch (PhabricatorEmptyQueryException $ex) {
	$page = array();
	}
	} else {
	$page = array();
	}

	if ($page) {
	$maybe_visible = $this->willFilterPage($page);
	} else {
	$maybe_visible = array();
	}

	if ($this->shouldDisablePolicyFiltering()) {
	$visible = $maybe_visible;
	} else {
	$visible = $filter->apply($maybe_visible);

	$policy_filtered = array();
	foreach ($maybe_visible as $key => $object) {
	if (empty($visible[$key])) {
	$phid = $object->getPHID();
	if ($phid) {
	$policy_filtered[$phid] = $phid;
	}
	}
	}
	$this->addPolicyFilteredPHIDs($policy_filtered);
	}

	if ($visible) {
	$this->putObjectsInWorkspace($this->getWorkspaceMapForPage($visible));
	$visible = $this->didFilterPage($visible);
	}

	$removed = array();
	foreach ($maybe_visible as $key => $object) {
	if (empty($visible[$key])) {
	$removed[$key] = $object;
	}
	}

	$this->didFilterResults($removed);

	foreach ($visible as $key => $result) {
	++$count;

	// If we have an offset, we just ignore that many results and start
	// storing them only once we've hit the offset. This reduces memory
	// requirements for large offsets, compared to storing them all and
	// slicing them away later.
	if ($count > $offset) {
	$results[$key] = $result;
	}

	if ($need && ($count >= $need)) {
	// If we have all the rows we need, break out of the paging query.
	break 2;
	}
	}

	if (!$this->rawResultLimit) {
	// If we don't have a load count, we loaded all the results. We do
	// not need to load another page.
	break;
	}

	if (count($page) < $this->rawResultLimit) {
	// If we have a load count but the unfiltered results contained fewer
	// objects, we know this was the last page of objects; we do not need
	// to load another page because we can deduce it would be empty.
	break;
	}

	$this->nextPage($page);
	} while (true);

	$results = $this->didLoadResults($results);

	return $results;
	}

	private function getPolicyFilter() {
	$filter = new PhabricatorPolicyFilter();
	$filter->setViewer($this->viewer);
	if (!$this->capabilities) {
	$capabilities = array(
	PhabricatorPolicyCapability::CAN_VIEW,
	);
	} else {
	$capabilities = $this->capabilities;
	}
	$filter->requireCapabilities($capabilities);
	$filter->raisePolicyExceptions($this->shouldRaisePolicyExceptions());

	return $filter;
	}

	protected function didRejectResult(PhabricatorPolicyInterface $object) {
	$this->getPolicyFilter()->rejectObject(
	$object,
	$object->getPolicy(PhabricatorPolicyCapability::CAN_VIEW),
	PhabricatorPolicyCapability::CAN_VIEW);
	}

	public function addPolicyFilteredPHIDs(array $phids) {
	$this->policyFilteredPHIDs += $phids;
	if ($this->getParentQuery()) {
	$this->getParentQuery()->addPolicyFilteredPHIDs($phids);
	}
	return $this;
	}

	/**
	* Return a map of all object PHIDs which were loaded in the query but
	* filtered out by policy constraints. This allows a caller to distinguish
	* between objects which do not exist (or, at least, were filtered at the
	* content level) and objects which exist but aren't visible.
	*
	* @return map<phid, phid> Map of object PHIDs which were filtered
	* by policies.
	* @task exec
	*/
	public function getPolicyFilteredPHIDs() {
	return $this->policyFilteredPHIDs;
	}


	/* -( Query Workspace )---------------------------------------------------- */


	/**
	* Put a map of objects into the query workspace. Many queries perform
	* subqueries, which can eventually end up loading the same objects more than
	* once (often to perform policy checks).
	*
	* For example, loading a user may load the user's profile image, which might
	* load the user object again in order to verify that the viewer has
	* permission to see the file.
	*
	* The "query workspace" allows queries to load objects from elsewhere in a
	* query block instead of refetching them.
	*
	* When using the query workspace, it's important to obey two rules:
	*
	* **Never put objects into the workspace which the viewer may not be able
	* to see**. You need to apply all policy filtering //before// putting
	* objects in the workspace. Otherwise, subqueries may read the objects and
	* use them to permit access to content the user shouldn't be able to view.
	*
	* Fully enrich objects pulled from the workspace. After pulling objects
	* from the workspace, you still need to load and attach any additional
	* content the query requests. Otherwise, a query might return objects without
	* requested content.
	*
	* Generally, you do not need to update the workspace yourself: it is
	* automatically populated as a side effect of objects surviving policy
	* filtering.
	*
	* @param map<phid, PhabricatorPolicyInterface> Objects to add to the query
	* workspace.
	* @return this
	* @task workspace
	*/
	public function putObjectsInWorkspace(array $objects) {
	assert_instances_of($objects, 'PhabricatorPolicyInterface');

	$viewer_phid = $this->getViewer()->getPHID();

	// The workspace is scoped per viewer to prevent accidental contamination.
	if (empty($this->workspace[$viewer_phid])) {
	$this->workspace[$viewer_phid] = array();
	}

	$this->workspace[$viewer_phid] += $objects;

	return $this;
	}


	/**
	* Retrieve objects from the query workspace. For more discussion about the
	* workspace mechanism, see @{method:putObjectsInWorkspace}. This method
	* searches both the current query's workspace and the workspaces of parent
	* queries.
	*
	* @param list<phid> List of PHIDs to retreive.
	* @return this
	* @task workspace
	*/
	public function getObjectsFromWorkspace(array $phids) {
	$viewer_phid = $this->getViewer()->getPHID();

	$results = array();
	foreach ($phids as $key => $phid) {
	if (isset($this->workspace[$viewer_phid][$phid])) {
	$results[$phid] = $this->workspace[$viewer_phid][$phid];
	unset($phids[$key]);
	}
	}

	if ($phids && $this->getParentQuery()) {
	$results += $this->getParentQuery()->getObjectsFromWorkspace($phids);
	}

	return $results;
	}


	/**
	* Convert a result page to a `<phid, PhabricatorPolicyInterface>` map.
	*
	* @param list<PhabricatorPolicyInterface> Objects.
	* @return map<phid, PhabricatorPolicyInterface> Map of objects which can
	* be put into the workspace.
	* @task workspace
	*/
	protected function getWorkspaceMapForPage(array $results) {
	$map = array();
	foreach ($results as $result) {
	$phid = $result->getPHID();
	if ($phid !== null) {
	$map[$phid] = $result;
	}
	}

	return $map;
	}


	/* -( Policy Query Implementation )---------------------------------------- */


	/**
	* Get the number of results @{method:loadPage} should load. If the value is
	* 0, @{method:loadPage} should load all available results.
	*
	* @return int The number of results to load, or 0 for all results.
	* @task policyimpl
	*/
	final protected function getRawResultLimit() {
	return $this->rawResultLimit;
	}


	/**
	* Hook invoked before query execution. Generally, implementations should
	* reset any internal cursors.
	*
	* @return void
	* @task policyimpl
	*/
	protected function willExecute() {
	return;
	}


	/**
	* Load a raw page of results. Generally, implementations should load objects
	* from the database. They should attempt to return the number of results
	* hinted by @{method:getRawResultLimit}.
	*
	* @return list<PhabricatorPolicyInterface> List of filterable policy objects.
	* @task policyimpl
	*/
	abstract protected function loadPage();


	/**
	* Update internal state so that the next call to @{method:loadPage} will
	* return new results. Generally, you should adjust a cursor position based
	* on the provided result page.
	*
	* @param list<PhabricatorPolicyInterface> The current page of results.
	* @return void
	* @task policyimpl
	*/
	abstract protected function nextPage(array $page);


	/**
	* Hook for applying a page filter prior to the privacy filter. This allows
	* you to drop some items from the result set without creating problems with
	* pagination or cursor updates. You can also load and attach data which is
	* required to perform policy filtering.
	*
	* Generally, you should load non-policy data and perform non-policy filtering
	* later, in @{method:didFilterPage}. Strictly fewer objects will make it that
	* far (so the program will load less data) and subqueries from that context
	* can use the query workspace to further reduce query load.
	*
	* This method will only be called if data is available. Implementations
	* do not need to handle the case of no results specially.
	*
	* @param list<wild> Results from `loadPage()`.
	* @return list<PhabricatorPolicyInterface> Objects for policy filtering.
	* @task policyimpl
	*/
	protected function willFilterPage(array $page) {
	return $page;
	}

	/**
	* Hook for performing additional non-policy loading or filtering after an
	* object has satisfied all policy checks. Generally, this means loading and
	* attaching related data.
	*
	* Subqueries executed during this phase can use the query workspace, which
	* may improve performance or make circular policies resolvable. Data which
	* is not necessary for policy filtering should generally be loaded here.
	*
	* This callback can still filter objects (for example, if attachable data
	* is discovered to not exist), but should not do so for policy reasons.
	*
	* This method will only be called if data is available. Implementations do
	* not need to handle the case of no results specially.
	*
	* @param list<wild> Results from @{method:willFilterPage()}.
	* @return list<PhabricatorPolicyInterface> Objects after additional
	* non-policy processing.
	*/
	protected function didFilterPage(array $page) {
	return $page;
	}


	/**
	* Hook for removing filtered results from alternate result sets. This
	* hook will be called with any objects which were returned by the query but
	* filtered for policy reasons. The query should remove them from any cached
	* or partial result sets.
	*
	* @param list<wild> List of objects that should not be returned by alternate
	* result mechanisms.
	* @return void
	* @task policyimpl
	*/
	protected function didFilterResults(array $results) {
	return;
	}


	/**
	* Hook for applying final adjustments before results are returned. This is
	* used by @{class:PhabricatorCursorPagedPolicyAwareQuery} to reverse results
	* that are queried during reverse paging.
	*
	* @param list<PhabricatorPolicyInterface> Query results.
	* @return list<PhabricatorPolicyInterface> Final results.
	* @task policyimpl
	*/
	protected function didLoadResults(array $results) {
	return $results;
	}


	/**
	* Allows a subclass to disable policy filtering. This method is dangerous.
	* It should be used only if the query loads data which has already been
	* filtered (for example, because it wraps some other query which uses
	* normal policy filtering).
	*
	* @return bool True to disable all policy filtering.
	* @task policyimpl
	*/
	protected function shouldDisablePolicyFiltering() {
	return false;
	}


	/**
	* If this query belongs to an application, return the application class name
	* here. This will prevent the query from returning results if the viewer can
	* not access the application.
	*
	* If this query does not belong to an application, return `null`.
	*
	* @return string\|null Application class name.
	*/
	abstract public function getQueryApplicationClass();


	/**
	* Determine if the viewer has permission to use this query's application.
	* For queries which aren't part of an application, this method always returns
	* true.
	*
	* @return bool True if the viewer has application-level permission to
	* execute the query.
	*/
	public function canViewerUseQueryApplication() {
	if ($this->canUseApplication === null) {
	$class = $this->getQueryApplicationClass();
	if (!$class) {
	$this->canUseApplication = true;
	} else {
	$result = id(new PhabricatorApplicationQuery())
	->setViewer($this->getViewer())
	->withClasses(array($class))
	->execute();

	$this->canUseApplication = (bool)$result;
	}
	}

	return $this->canUseApplication;
	}

	}

File Metadata

Mime Type: text/x-diff
Expires: Tue, Apr 29, 5:13 PM (23 h, 29 m)
Storage Engine: blob
Storage Format: Raw Data
Storage Handle: 108457
Default Alt Text: (41 KB)

No OneTemporaryActions

View Options

File Metadata

Event Timeline

No OneTemporary
Actions