Allow class FQCN strings as authorization resources (draft, refs #135)

[dereuromark]

Closes #135 if accepted.

Why

The recurring use case from #135 is:

if ($this->Authorization->can('add', \App\Model\Entity\Article::class)) {
    echo $this->Html->link('Add new', ['action' => 'add']);
}

i.e. checking permission to create a resource at a moment when no instance exists yet (menu rendering, button visibility, list-view "New" links, before newEmptyEntity()).

Today this requires creating a throwaway entity just to satisfy the resolver, or mapping ServerRequest::class to a RequestPolicy and using RequestAuthorizationMiddleware. Both feel like workarounds.

The 2020 thread on #135 (markstory: "the only limitation … has been a lack of imagination and use cases"; LordSimal in 2023: "this will be possible in the next major version") concluded the feature is wanted but had no champion. Picking it back up.

What

OrmResolver

getPolicy() learns to accept a class FQCN string. If the string contains one of the conventional namespace markers (\Model\Entity\ or \Model\Table\), the namespace and name segments are extracted and routed through the existing findPolicy() lookup — so the resolution is identical to what would happen for an instance of that class:

$user->can('add', \App\Model\Entity\Article::class);     // App\Policy\ArticlePolicy
$user->can('access', \App\Model\Table\ArticlesTable::class); // App\Policy\ArticlesTablePolicy

A string that is not a class (class_exists() === false) is left to fall through to the existing MissingPolicyException path. A class that does not match either marker also throws MissingPolicyException — same behavior as a non-resolvable instance.

MapResolver

getPolicy() learns to accept a class FQCN string. If the string resolves to an existing class, it is used directly as the map key:

$resolver->map(Article::class, ArticlePolicy::class);
$user->can('add', Article::class);  // returns ArticlePolicy

A registered FQCN with no policy mapping raises MissingPolicyException (parity with the object case). A non-class string still raises InvalidArgumentException, just with an updated message that names the offending string instead of just its type.

The pre-existing testGetPolicyPrimitive assertion message was updated accordingly — that is the only BC-visible change in the test suite.

Discussion points for all maintainers

1. Should OrmResolver accept class_exists($resource) === false? Current draft requires the class to exist. An alternative is to accept any string that contains the marker and let findPolicy() either return a policy or throw. Stricter is friendlier IMO but I can flip it.
2. MapResolver — should we widen the type hint on getPolicy()? The interface signature is mixed, so technically nothing changes; the docblock and message strings now describe the broader contract.
3. Should we also allow registering policies by FQCN that doesn't yet exist? Right now MapResolver::map() enforces class_exists($resourceClass) so this is moot, but if anyone uses it with classes only autoloaded under certain conditions it could be a footgun.
4. ResolverCollection already chains resolvers, so a user with a partial map + ORM resolver gets the natural fallback for free. No changes there.
5. Anything you want me to split (only OrmResolver, only MapResolver, etc.) — happy to.

[markstory]

Do we really want to be doing string searches? Can't we use the interfaces instead? What do we gain from substring matching?

[dereuromark]

Two different jobs, conflated:

1. Discrimination — "is this an entity or a table?" New code decides via strpos($class, '\Model\Entity') vs '\Model\Table'.
2. Extraction — pull namespace + name segments to feed findPolicy().

The # 1:
Should probably use interfaces ideally

For # 2:
getEntityPolicy()/getRepositoryPolicy() already substring-search \Model\Entity\ to derive namespace+name for findPolicy() — even for instances. That's OrmResolver's existing convention. So interface approach removes substring from the decision, not from the lookup. A non-conventional namespace still fails at findPolicy() either way.

[dereuromark]

Applied the interface-based discrimination as suggested: the class-string path now uses is_subclass_of() against EntityInterface / RepositoryInterface instead of substring-matching the namespace markers, and folds into the existing getEntityPolicy() / getRepositoryPolicy() methods (so getPolicyByClassName() is gone and string/instance resolution share one body).

Added a FakeEntity regression test: a class that lives under the entity namespace and even has a matching FakeEntityPolicy, but does not implement EntityInterface - the old substring lookup would have wrongly resolved it, the interface check now rejects it with MissingPolicyException.

The namespace extraction that findPolicy() already relied on stays as-is; that convention is unchanged and runs for instances too.

Minor BC to flag for release notes: getEntityPolicy() / getRepositoryPolicy() change their protected signature from the object instance to a class-name string. Any subclass overriding these protected methods needs to update its signature.