✨ Add NamespaceRouteLoader powered by Composer's PSR-4 map

[dimitriBouteille]

Summary

Add NamespaceRouteLoader, a Composer-powered route discoverer, and mark the directory-based RouteLoader::__construct as @deprecated. The new loader resolves the filesystem location of routes from Composer's PSR-4 map and derives each candidate FQCN from its file path, so the custom token-stream parser becomes optional going forward.

Why

RouteLoader discovery currently relies on Parser::findClassName, a hand-rolled tokenizer that has several known edge cases (anonymous classes hijacking detection, block-style namespaces missed, missing early-exit). Composer already knows the class-to-file mapping via PSR-4, so re-implementing that lookup with token_get_all duplicates work and introduces bugs.

NamespaceRouteLoader swaps the convention: users declare the namespace they want to expose, the loader asks Composer where that namespace lives on disk, walks the directory, and derives each FQCN from the path. No tokenizing, no Parser invocation.

Usage

  use Dbout\WpRestApi\NamespaceRouteLoader;

  (new NamespaceRouteLoader('App\\Routes\\'))->register();

Or, with options and an injected ClassLoader (useful for tests or multi-autoloader setups):

  $loader = new NamespaceRouteLoader(
      ['App\\Routes\\', 'App\\Admin\\Routes\\'],
      new RouteLoaderOptions(cache: $cache),
      $composerClassLoader,
  );

Deprecation

RouteLoader::__construct carries an @deprecated PHPDoc tag pointing at NamespaceRouteLoader. Behaviour is unchanged at runtime — existing code keeps working — but PHPStan and IDEs will flag direct instantiation. The class itself stays as the base class NamespaceRouteLoader inherits from.

Backward compatibility

Non-breaking, minor bump. RouteLoader still discovers routes via the directory walker + Parser. Nothing was removed.