Merge feature/improve-projection into master

[LartTyler]

What's Changed

• Projection query results now differentiate between explicit and implicit results, meaning that it is possible to detect e.g. if a path was denied because the projection was an allow-list and the path wasn't found in the list. See Projection Examples for more details.

Projection Examples

The Projection class now includes a suite of methods for testing exactly why a path did or did not pass the projection.

Starting with the most basic of the methods, query(), which returns an integer describing the result of the query. The integer is a bitmask (see QueryResult) representing the states a result can take.

use DaybreakStudios\DoctrineQueryDocument\Projection\Projection;
use DaybreakStudios\DoctrineQueryDocument\Projection\QueryResult;

// ===== Allow List =====
$projection = Projection::fromFields([
    'a.b.c' => true,
]);

// Our projection is an allow-list, and the path "a.b.c" is part of the list, so
// it is both `allowed` and `explicit`.
assert($projection->query('a.b.c') === QueryResult::ALLOW | QueryResult::IS_EXPLICIT);

// Our projection is an allow-list, and the path "1.2.3" is not part of the list, so
// it is only `denied`.
assert($projection->query('1.2.3') === QueryResult::DENY);

// ===== Deny List =====
$projection = Projection::fromFields([
    'a.b.c' => false,
]);

// Our projection is a deny-list, and the path "a.b.c" is part of the list, so
// it is both `denied` and `explicit`.
assert($projection->query('a.b.c') === QueryResult::DENY | QueryResult::IS_EXPLICIT);

// Our projection is a deny-list, and the path "1.2.3" is not part of the list, so
// it is only `allowed`.
assert($projection->query('1.2.3') === QueryResult::ALLOW);

In addition to the existing Projection::isAllowed() method, there are several new methods you can use to easily test the results of a query without using QueryResult directly.

use DaybreakStudios\DoctrineQueryDocument\Projection\Projection;

$projection = Projection::fromFields([
    'a.b.c' => true,
]);

// An explicit allow is still an allow
assert($projection->isAllowed('a.b.c'));

// Explicitly allowed because the path is present in the allow-list
assert($projection->isAllowedExplicitly('a.b.c'));

// Denied by default because the path is not present in the allow-list
assert($projection->isDenied('1.2.3'));

// Not explicitly denied
assert($projection->isDeniedExplicitly('1.2.3') === false);

$projection = Projection::fromFields([
    '1.2.3' => false,
]);

// An explicit deny is still a deny
assert($projection->isDenied('1.2.3'));

// Explicitly denied because the path is present in the deny-list
assert($projection->isDeniedExplicitly('1.2.3'));

// Allowed by default because the path is not present in the deny-list
assert($projection->isAllowed('a.b.c'));

// Not explicitly allowed
assert($projection->isAllowedExplicitly('a.b.c') === false);