From 1e0219ba484ee54efd42bdb73c78b834cc0c4aaf Mon Sep 17 00:00:00 2001 From: Joey Smith Date: Mon, 5 Oct 2026 01:01:02 -0500 Subject: [PATCH 1/3] docs: correct the ACL API references MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The docs described an API that no longer exists and named the wrong namespaces, so a reader following them would look for a method that is not there and an interface that lives in another package. - `Webware\Acl\AclInterface` -> `Webware\Core\AclInterface` (the contract moved to webware-core; the implementation stays in webware-acl as `Webware\Acl\Acl`). - `Webware\UserManager\UserInterface`, which does not exist, -> `Webware\Core\UserInterface`. - `isAllowedByRouteName()` -> the inherited Laminas `isAllowed()` that `NavigationFilterIterator` actually calls, passing the route name as the resource. `isAllowedByRouteName()` was removed because it duplicated `isAllowedRoute()` in all but name. `build: align tooling with webware-tools` (61e3192) made the code change and the docs were never brought along. architecture.md's Decision 8 is marked SUPERSEDED rather than rewritten — it records why the method was introduced, and the route-mapping subsystem it describes was removed with it. The webware-tools alignment audit keeps its point-in-time findings and gains a note saying so. Signed-off-by: Joey Smith --- README.md | 7 +++---- docs/architecture.md | 9 ++++++++- docs/component-reference.md | 26 ++++++++++++++++---------- docs/extending.md | 4 ++-- docs/overview.md | 2 +- docs/testing.md | 13 ++++++------- docs/webware-tools-alignment.md | 8 ++++++++ 7 files changed, 44 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 47512dc..b23894f 100644 --- a/README.md +++ b/README.md @@ -37,10 +37,9 @@ Private package — not published to Packagist. Consume via a VCS repository ent After each change run `composer update webware/webware-navigation` (the lock pins the commit hash). -Note: the package types against `Webware\Acl\AclInterface` and -`Webware\UserManager\UserInterface`, which the consuming application provides -until `webware-acl` + `webware-usermanager` publish — see -`docs/webware-tools-alignment.md`. +Note: the package types against `Webware\Core\AclInterface` and +`Webware\Core\UserInterface`, both provided by `webware/webware-core`, which this +package requires — see `docs/webware-tools-alignment.md`. Add to `config/config.php`: diff --git a/docs/architecture.md b/docs/architecture.md index 347880e..36b108a 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -209,7 +209,14 @@ Placing it before `RouteMiddleware` (as was briefly the case during development) --- -## Decision 8 — isAllowedByRouteName on AclInterface +## Decision 8 — isAllowedByRouteName on AclInterface — SUPERSEDED + +> **Superseded — do not implement from this section.** `isAllowedByRouteName()` was +> removed from the ACL contract because it duplicated `isAllowedRoute()` in all but +> name, and the route-mapping subsystem (`$this->routeMappings`) described below was +> removed with it. `NavigationFilterIterator` now calls the inherited Laminas +> `isAllowed()` with the route name as the resource. The text below is retained as the +> record of why the method was introduced. `AclInterface::isAllowedRoute()` requires a `ServerRequestInterface` because it reads `RouteResult` from the request. The view helper and filter iterator have no request diff --git a/docs/component-reference.md b/docs/component-reference.md index a78748b..fadbd84 100644 --- a/docs/component-reference.md +++ b/docs/component-reference.md @@ -64,7 +64,8 @@ public function __construct( Called internally by SPL for each item in the inner iterator. Returns `true` when: 1. `options['navigation']` equals `$navId` (string) or contains it (array). -2. `AclInterface::isAllowedByRouteName($route->getName(), $roles)` returns `true`. +2. The ACL allows the route name for the current user — `isAllowed()` with + `$route->getName()` as the resource — returns `true`. Both conditions must be satisfied. If either fails the route is excluded. @@ -241,16 +242,21 @@ Webware\Navigation\ConfigProvider::class, --- -## AclInterface additions +## The ACL check -Two methods were added to `Webware\Acl\AclInterface` to support request-free ACL -checks from the filter iterator: +The iterator asks the ACL directly, passing the route name as the resource: -### `isAllowedByRouteName(string $routeName, $roles): bool` +```php +$this->acl->isAllowed(role: $this->user, resource: $route->getName()); +``` + +`Webware\Core\AclInterface` extends `Laminas\Permissions\Acl\AclInterface`, so +`isAllowed()` is the inherited Laminas method, and `Acl::load()` registers resources +under their route names — which is why the route name is what gets passed. -Looks up `$routeName` in the internal route-to-resource/privilege mapping. Returns -`true` (visible) when the route has no ACL mapping — unmapped routes are not protected. -Returns `false` when the mapping exists and no role in `$roles` is permitted. +The interface itself adds `isAllowedRoute(?UserInterface $user, ResourceInterface +$resource)`, a thin wrapper over the same call for callers that already hold a +`ResourceInterface`. -This is distinct from `isAllowedRoute(ServerRequestInterface, $roles)` which reads the -mapping from the live `RouteResult` on the request. +`isAllowedByRouteName()` is not part of the API. It was removed because it duplicated +`isAllowedRoute()` in all but name. diff --git a/docs/extending.md b/docs/extending.md index 9a79cdc..9c18624 100644 --- a/docs/extending.md +++ b/docs/extending.md @@ -143,9 +143,9 @@ Then render each independently: ## Overriding the ACL check -`NavigationFilterIterator` calls `AclInterface::isAllowedByRouteName()`. To change +`NavigationFilterIterator` calls `AclInterface::isAllowed()`. To change ACL filtering behaviour, implement `AclInterface` and register your implementation -in the DI container under `AclInterface::class`. This affects all ACL consumers +in the DI container under `Webware\Core\AclInterface::class`. This affects all ACL consumers including `AuthorizationMiddleware`. To change filtering only for navigation without affecting the main ACL, wrap the diff --git a/docs/overview.md b/docs/overview.md index cafad60..30887bb 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -12,7 +12,7 @@ the result without any separate navigation configuration file. | Goal | How it is met | |---|---| | Single source of truth for nav membership | `Route::setOptions(['navigation' => 'admin', ...])` lives beside the route definition | -| ACL enforcement before render time | `NavigationFilterIterator` calls `AclInterface::isAllowedByRouteName()` per route | +| ACL enforcement before render time | `NavigationFilterIterator` calls `AclInterface::isAllowed()` per route | | Multiple representations from one filtered tree | `NavigationContainer` exposes `menu()`, `breadcrumbs()`, and `sitemap()` | | Replaceable rendering | Every render method delegates to an optional `RendererInterface` before falling back to inline markup | | Active-item highlighting | `NavigationMiddleware` injects the matched route name from `RouteResult` after routing completes | diff --git a/docs/testing.md b/docs/testing.md index b38d3fb..d1f8032 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -12,10 +12,9 @@ ## Unit testing the filter iterator -**Blocked until dependencies publish:** these tests type against -`Webware\Acl\AclInterface` and `Webware\UserManager\UserInterface` — neither -package is published yet (see `docs/webware-tools-alignment.md`, Research -section). Skip until then. +Both contracts — `Webware\Core\AclInterface` and `Webware\Core\UserInterface` — +ship in `webware/webware-core`, which this package requires, so these tests run like +any other. `NavigationFilterIterator` is the easiest component to test in isolation. Construct it with a stub `AclInterface` and an array of `Route` objects: @@ -23,7 +22,7 @@ it with a stub `AclInterface` and an array of `Route` objects: ```php use Mezzio\Router\Route; use PHPUnit\Framework\TestCase; -use Webware\Acl\AclInterface; +use Webware\Core\AclInterface; use Webware\Navigation\NavigationFilterIterator; final class NavigationFilterIteratorTest extends TestCase @@ -45,7 +44,7 @@ final class NavigationFilterIteratorTest extends TestCase { $route = $this->makeRoute('/secret', 'admin.secret', ['navigation' => 'admin']); $acl = $this->createStub(AclInterface::class); - $acl->method('isAllowedByRouteName')->willReturn(false); + $acl->method('isAllowed')->willReturn(false); $iterator = new NavigationFilterIterator([$route], 'admin', ['guest'], $acl); $results = iterator_to_array($iterator); @@ -75,7 +74,7 @@ final class NavigationFilterIteratorTest extends TestCase private function alwaysAllowAcl(): AclInterface { $acl = $this->createStub(AclInterface::class); - $acl->method('isAllowedByRouteName')->willReturn(true); + $acl->method('isAllowed')->willReturn(true); return $acl; } } diff --git a/docs/webware-tools-alignment.md b/docs/webware-tools-alignment.md index 75e8188..e8ac744 100644 --- a/docs/webware-tools-alignment.md +++ b/docs/webware-tools-alignment.md @@ -8,6 +8,14 @@ established by `webware/webware-tools` (reusable workflow webware-mailer alignment (`webware-mailer/docs/webware-tools-alignment.md`) — mailer is the aligned consumer and the template this repo adopts. +> **Names in this audit are point-in-time.** It records the state as it was during +> the alignment and is not maintained, so class and method names below reflect what +> the code looked like then. In particular `Webware\Acl\AclInterface` now lives in +> `webware/webware-core` as `Webware\Core\AclInterface`, and +> `Webware\UserManager\UserInterface` is provided by core as +> `Webware\Core\UserInterface`. For the current API see +> `docs/component-reference.md` and `docs/architecture.md`. + **Scope:** CI/CD pipeline, tooling configs, composer metadata, baseline files, and the minimum test scaffolding required for a green pipeline. From dab654335285077c19d6ac2623477a2a39aa6c06 Mon Sep 17 00:00:00 2001 From: Joey Smith Date: Mon, 5 Oct 2026 01:03:44 -0500 Subject: [PATCH 2/3] docs: drop the historical framing, describe current behaviour architecture.md's Decision 8 documented a method that no longer exists, a routeMappings lookup that was removed with it, and an "unmapped routes are allowed" default that is the opposite of the current fail-closed check. It is replaced with a section describing what the iterator actually does. The point-in-time note on the alignment audit is reverted: that document is untouched in this branch and needs its own decision, not a caveat. Signed-off-by: Joey Smith --- docs/architecture.md | 47 +++++++++++++++------------------ docs/component-reference.md | 2 +- docs/webware-tools-alignment.md | 8 ------ 3 files changed, 23 insertions(+), 34 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index 36b108a..0b35f2b 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -209,38 +209,35 @@ Placing it before `RouteMiddleware` (as was briefly the case during development) --- -## Decision 8 — isAllowedByRouteName on AclInterface — SUPERSEDED +## Decision 8 — How the filter iterator checks the ACL -> **Superseded — do not implement from this section.** `isAllowedByRouteName()` was -> removed from the ACL contract because it duplicated `isAllowedRoute()` in all but -> name, and the route-mapping subsystem (`$this->routeMappings`) described below was -> removed with it. `NavigationFilterIterator` now calls the inherited Laminas -> `isAllowed()` with the route name as the resource. The text below is retained as the -> record of why the method was introduced. - -`AclInterface::isAllowedRoute()` requires a `ServerRequestInterface` because it reads -`RouteResult` from the request. The view helper and filter iterator have no request -object — they run inside a renderer context. - -Rather than inject the request into the helper (see Decision 6), a second method was -added to `AclInterface`: +`NavigationFilterIterator` runs inside a renderer context and inspects routes before +any of them is dispatched, so it has no request and cannot build the `RouteResource` +that `isAllowedRoute()` takes. It calls the ACL directly, passing the route name as +the resource: ```php -public function isAllowedByRouteName( - string $routeName, - array|RoleInterface|string|null $roles = null, -): bool; +$this->acl->isAllowed(role: $this->user, resource: $route->getName()); ``` -The implementation looks up the route name in `$this->routeMappings`. If no mapping -exists for the route name, it returns `true` — the route is not ACL-protected and is -visible to all authenticated users. +Resource ids are route names — `Acl::load()` registers every route from the route +collector — so a route name is a valid id and resolves to the same rule an +`isAllowedRoute()` call would find. There is no route-name variant on the interface: +one would duplicate `isAllowedRoute()` in all but name. -This is the correct default because routes without ACL mappings are intentionally -public-access routes. Denying them by default would hide unprotected routes from -navigation, which would be wrong. +Three properties of `Acl::isAllowed()` decide the result: ---- +1. **Fail-closed** — a resource id the ACL has not registered is denied before + Laminas sees it. +2. **Lazy load** — the first call materialises the rules from the `acl_rule` table + and registers the routes as resources. +3. **Ancestor rules apply** — a route with no rule of its own inherits from its + nearest registered ancestor, so rules on an anchor such as `user` cover the + routes beneath it. + +The result decides visibility, so the ACL rows and `Route::setOptions(['navigation' +=> ...])` have to agree: a nav entry whose route the ACL denies is filtered out +before render. ## Active-item detection algorithm diff --git a/docs/component-reference.md b/docs/component-reference.md index fadbd84..3038e70 100644 --- a/docs/component-reference.md +++ b/docs/component-reference.md @@ -258,5 +258,5 @@ The interface itself adds `isAllowedRoute(?UserInterface $user, ResourceInterfac $resource)`, a thin wrapper over the same call for callers that already hold a `ResourceInterface`. -`isAllowedByRouteName()` is not part of the API. It was removed because it duplicated +There is no route-name variant on the interface: one would duplicate `isAllowedRoute()` in all but name. diff --git a/docs/webware-tools-alignment.md b/docs/webware-tools-alignment.md index e8ac744..75e8188 100644 --- a/docs/webware-tools-alignment.md +++ b/docs/webware-tools-alignment.md @@ -8,14 +8,6 @@ established by `webware/webware-tools` (reusable workflow webware-mailer alignment (`webware-mailer/docs/webware-tools-alignment.md`) — mailer is the aligned consumer and the template this repo adopts. -> **Names in this audit are point-in-time.** It records the state as it was during -> the alignment and is not maintained, so class and method names below reflect what -> the code looked like then. In particular `Webware\Acl\AclInterface` now lives in -> `webware/webware-core` as `Webware\Core\AclInterface`, and -> `Webware\UserManager\UserInterface` is provided by core as -> `Webware\Core\UserInterface`. For the current API see -> `docs/component-reference.md` and `docs/architecture.md`. - **Scope:** CI/CD pipeline, tooling configs, composer metadata, baseline files, and the minimum test scaffolding required for a green pipeline. From 8fb3f564873b4a14c32d0b27c3bbbba1a5f514cc Mon Sep 17 00:00:00 2001 From: Joey Smith Date: Mon, 5 Oct 2026 01:20:28 -0500 Subject: [PATCH 3/3] docs: record the current state, verified against the source Every claim in these documents was checked against src/ and corrected where it did not match. Nothing is written as history, as intent, or as a plan. - NavigationFilterIterator takes (routes, navId, UserInterface, AclInterface). component-reference.md documented the third parameter as `array $roles`, which is what put ['guest'] into the testing examples. - NavigationMiddleware is Webware\Navigation\Http\Middleware in src/Http/Middleware/. It calls setUser(), setAcl() and setActiveRouteName(); setRoles() does not exist on the helper. - NavigationFactory passes null for all three renderers, so the inline fallbacks run. There is no RendererPluginManager in this package, and the sections describing one are removed rather than described as planned. - overview.md's package layout showed a monorepo path and the middleware in a namespace it no longer occupies. - README.md pointed at a document that no longer exists, and at the 0.1.x line for the mutation badge and the install constraint. Removes docs/webware-tools-alignment.md: an audit of an alignment exercise whose findings are resolved and whose paths predate the standalone repositories. Not touched: docblocks in src/ still name a planned RendererPluginManager (RendererInterface.php, Navigation.php, NavigationFactory.php, NavigationContainer.php). Signed-off-by: Joey Smith --- README.md | 10 +- docs/architecture.md | 43 ++-- docs/component-reference.md | 41 ++-- docs/extending.md | 38 +-- docs/overview.md | 32 +-- docs/testing.md | 19 +- docs/webware-tools-alignment.md | 421 -------------------------------- 7 files changed, 80 insertions(+), 524 deletions(-) delete mode 100644 docs/webware-tools-alignment.md diff --git a/README.md b/README.md index b23894f..e7dfbaf 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ [![License](https://img.shields.io/github/license/webinertia/webware-navigation)](LICENSE) [![Continuous Integration](https://github.com/webinertia/webware-navigation/actions/workflows/required/webinertia/.github/.github/workflows/org-required-ci.yml/badge.svg)](https://github.com/webinertia/webware-navigation/actions/workflows/required/webinertia/.github/.github/workflows/org-required-ci.yml) [![codecov](https://codecov.io/gh/webinertia/webware-navigation/graph/badge.svg)](https://codecov.io/gh/webinertia/webware-navigation) -[![Mutation testing badge](https://img.shields.io/endpoint?style=flat&url=https%3A%2F%2Fbadge-api.stryker-mutator.io%2Fgithub.com%2Fwebinertia%2Fwebware-navigation%2F0.1.x)](https://dashboard.stryker-mutator.io/reports/github.com/webinertia/webware-navigation/0.1.x) +[![Mutation testing badge](https://img.shields.io/endpoint?style=flat&url=https%3A%2F%2Fbadge-api.stryker-mutator.io%2Fgithub.com%2Fwebinertia%2Fwebware-navigation%2F1.0.x)](https://dashboard.stryker-mutator.io/reports/github.com/webinertia/webware-navigation/1.0.x) ACL-aware navigation trees for Mezzio, driven by `Route::setOptions()`. @@ -16,7 +16,7 @@ ACL-aware navigation trees for Mezzio, driven by `Route::setOptions()`. | [Overview](docs/overview.md) | Goals, quick start, route options reference | | [Architecture](docs/architecture.md) | Design decisions and rationale | | [Component Reference](docs/component-reference.md) | API docs for every class | -| [Extending](docs/extending.md) | Custom renderers, planned RendererPluginManager | +| [Extending](docs/extending.md) | Custom renderers, replacing the factory | | [Testing](docs/testing.md) | Unit test examples and guidance | ## Installation @@ -29,7 +29,7 @@ Private package — not published to Packagist. Consume via a VCS repository ent { "type": "vcs", "url": "https://github.com/webinertia/webware-navigation" } ], "require": { - "webware/webware-navigation": "0.1.x-dev" + "webware/webware-navigation": "1.0.x-dev" } } ``` @@ -39,7 +39,7 @@ pins the commit hash). Note: the package types against `Webware\Core\AclInterface` and `Webware\Core\UserInterface`, both provided by `webware/webware-core`, which this -package requires — see `docs/webware-tools-alignment.md`. +package requires. Add to `config/config.php`: @@ -69,6 +69,6 @@ cannot express safely. See [Architecture](docs/architecture.md), Decision 7. ## Namespace ``` -Package: webware/navigation +Package: webware/webware-navigation Namespace: Webware\Navigation\ ``` diff --git a/docs/architecture.md b/docs/architecture.md index 0b35f2b..1b69cfb 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -138,9 +138,9 @@ NavigationContainer::menu() → else: inline Bootstrap markup ``` -The renderers are constructor parameters on `NavigationContainer`, injected by -`Navigation` helper which receives them from `NavigationFactory`. The factory currently -passes `null` for all three with a comment marking the future injection point. +The renderers are constructor parameters on `NavigationContainer`, injected by the +`Navigation` helper, which receives them from `NavigationFactory`. The factory passes +`null` for all three, so the inline fallbacks run. **Why plan for renderers now rather than deferring entirely:** - The constructor signature is the public API surface. Adding renderer parameters @@ -148,32 +148,20 @@ passes `null` for all three with a comment marking the future injection point. - The `null` default means zero cost until renderers exist. - The `RendererInterface` contract is documented so implementors know what to build. -**Planned renderer injection via PluginManager:** -```php -// Future NavigationFactory -$renderers = $container->get(RendererPluginManager::class); -return new Navigation( - routeCollector: $container->get(RouteCollectorInterface::class), - acl: $container->get(AclInterface::class), - menuRenderer: $renderers->get(MenuRenderer::class), - breadcrumbRenderer: $renderers->get(BreadcrumbRenderer::class), - sitemapRenderer: $renderers->get(SitemapRenderer::class), -); -``` - -Custom renderers will be registered via service-manager config, allowing per-application -override of any representation without forking the package. +A custom renderer is supplied by replacing `NavigationFactory` in the consumer's +service-manager configuration and passing it to the shown parameter. See +[Extending](extending.md). --- -## Decision 6 — StatefulHelperInterface for role injection +## Decision 6 — StatefulHelperInterface for per-request state The `Navigation` view helper implements `Laminas\View\Helper\StatefulHelperInterface`. This pattern is used throughout the Laminas/Mezzio ecosystem (e.g. `UrlHelper`) for helpers that need per-request state injected after construction but before invocation. -`NavigationMiddleware` calls `$helper->setRoles()` and `$helper->setActiveRouteName()` -on the **same shared instance** the DI container holds. The helper is a long-lived +`NavigationMiddleware` calls `$helper->setUser()`, `$helper->setAcl()` and +`$helper->setActiveRouteName()` on the **same shared instance** the DI container holds. The helper is a long-lived service; `resetState()` is called by Laminas' `HelperPluginManager` between requests (in long-lived runtimes) to prevent state leakage. @@ -250,9 +238,9 @@ admin.users ← active (because descendant is active) admin.users.edit ← active (matched route) ``` -`NavigationContainer::isActive(NavigationItem)` walks the tree depth-first. -`NavigationContainer::findTrail(NavigationItem)` does the same for breadcrumbs, -returning the ancestor chain from the root to the active item. +`NavigationContainer::isActive(NavigationItem)` walks the tree depth-first. The private +`findTrail()` helper does the same for breadcrumbs, returning the ancestor chain from the +root to the active item. --- @@ -263,7 +251,8 @@ Request │ ▼ NavigationMiddleware - setRoles([...]) + setUser($user) + setAcl($acl) — only when the attribute is already set setActiveRouteName('admin.users.edit') │ ▼ @@ -272,10 +261,10 @@ Template: $this->navigation('admin') ▼ Navigation::__invoke('admin') │ - ├── NavigationFilterIterator(routes, 'admin', $roles, $acl) + ├── NavigationFilterIterator(routes, 'admin', $user, $acl) │ forEach route: │ belongsToNav(options, 'admin') ? - │ isAllowedByRouteName(routeName, $roles) ? + │ isAllowed(role: $user, resource: routeName) ? │ ├── Build NavigationItem objects from filtered routes ├── Wire parent→child relationships diff --git a/docs/component-reference.md b/docs/component-reference.md index 3038e70..7d9e58c 100644 --- a/docs/component-reference.md +++ b/docs/component-reference.md @@ -46,7 +46,7 @@ name, `icon` = `''`, `parent` = `null`, `order` = `0`. **Extends:** `FilterIterator` SPL filter iterator that accepts only routes belonging to a given nav identifier that -the current user's roles are permitted to access. +the current user is permitted to access. ### Constructor @@ -54,7 +54,7 @@ the current user's roles are permitted to access. public function __construct( array $routes, // list from RouteCollectorInterface::getRoutes() string $navId, // navigation identifier to filter for - array $roles, // string[] current user's roles + UserInterface $user, // current user object AclInterface $acl, ) ``` @@ -114,7 +114,7 @@ Inline fallback options: | Key | Default | Description | |---|---|---| -| `type` | `'sidebar'` | `'sidebar'` → `nav flex-column`; `'horizontal'` → `navbar-nav` | +| `type` | `'sidebar'` | `'sidebar'` → `nav flex-column gap-1`; `'horizontal'` → `navbar-nav` | Active items receive the `active` CSS class. If an item has children a nested `
    ` is emitted. @@ -157,22 +157,23 @@ public function __construct( ) ``` -The three `RendererInterface` parameters are `null` until a `RendererPluginManager` is -implemented (see [Extending / Custom Renderers](extending.md)). +`NavigationFactory` passes `null` for all three. With no renderer injected, each render +method uses its inline fallback (see [Extending](extending.md)). ### Per-request state methods (called by NavigationMiddleware) | Method | Description | |---|---| -| `setRoles(string[] $roles)` | Sets roles used for ACL filtering. | +| `setUser(?UserInterface $user)` | Sets the user passed to the ACL check. | +| `setAcl(AclInterface $acl)` | Replaces the ACL used for filtering. | | `setActiveRouteName(?string $name)` | Sets the matched route name for active detection. | -| `resetState()` | Clears roles and active route name. Called between requests in long-lived runtimes. | +| `resetState()` | Clears the user and the matched route name. Does not reset the ACL. Called between requests in long-lived runtimes. | ### `__invoke(string $navId): NavigationContainer` Builds and returns the container: -1. Creates `NavigationFilterIterator` with all routes, nav ID, current roles, and ACL. +1. Creates `NavigationFilterIterator` with all routes, nav ID, the current user, and the ACL. 2. Iterates the filtered routes, building `NavigationItem` objects keyed by route name. 3. Wires parent→child relationships. 4. Sorts top-level items by `order`. @@ -182,8 +183,8 @@ Builds and returns the container: ## NavigationMiddleware -**Namespace:** `Webware\Navigation\Middleware` -**File:** `src/Middleware/NavigationMiddleware.php` +**Namespace:** `Webware\Navigation\Http\Middleware` +**File:** `src/Http/Middleware/NavigationMiddleware.php` **Implements:** `MiddlewareInterface` **Pipeline position:** after `UrlHelperMiddleware` (which runs after `RouteMiddleware`). @@ -191,11 +192,16 @@ This guarantees `RouteResult` is on the request. ### Behaviour -1. Reads `UserInterface` from `$request->getAttribute(UserInterface::class)`. - If present, calls `$helper->setRoles([...$user->getRoles()])`. -2. Reads `RouteResult` from `$request->getAttribute(RouteResult::class)`. - If matched, calls `$helper->setActiveRouteName($routeResult->getMatchedRouteName())`. -3. Calls `$handler->handle($request)` — the helper is now primed for template use. +1. Reads `UserInterface` from `$request->getAttribute(UserInterface::class)` and calls + `$helper->setUser($user)`. +2. Reads `AclInterface` from `$request->getAttribute(AclInterface::class)` and calls + `$helper->setAcl($acl)` when the attribute is set. `AclMiddleware` runs after this + middleware in the shipped pipeline, so the attribute is not populated yet and the + helper keeps the ACL that `NavigationFactory` injected. +3. Reads `RouteResult` from `$request->getAttribute(RouteResult::class)`. When it is + present and not a failure, calls `$helper->setActiveRouteName()` with the matched + route name, or `null` when that name is empty. +4. Calls `$handler->handle($request)` — the helper is now primed for template use. ### Important: same helper instance @@ -218,8 +224,9 @@ interface RendererInterface } ``` -Implementations are resolved by a `RendererPluginManager` (planned). Register custom -renderers via service-manager configuration. See [Extending](extending.md). +Nothing resolves these from configuration: `Navigation` and `NavigationContainer` take +them as constructor arguments, and `NavigationFactory` passes `null`. See +[Extending](extending.md). --- diff --git a/docs/extending.md b/docs/extending.md index 9c18624..bc7675d 100644 --- a/docs/extending.md +++ b/docs/extending.md @@ -2,9 +2,8 @@ ## Custom renderers -The fastest way to customise output is to implement `RendererInterface` and wire it -via service-manager configuration. Until the `RendererPluginManager` is implemented -(see below), you can inject renderers by overriding `NavigationFactory`. +Implement `RendererInterface` and pass it to the `Navigation` constructor by replacing +`NavigationFactory` in your own service-manager configuration. --- @@ -60,13 +59,13 @@ final class TailwindMenuRenderer implements RendererInterface --- -## Wiring a custom renderer (current approach) +## Wiring a custom renderer -Override `NavigationFactory` in your own module's `ConfigProvider` until the -`RendererPluginManager` is available: +Replace `NavigationFactory` in your own module's `ConfigProvider` with a factory that +injects the renderer: ```php -// src/MyApp/src/Navigation/NavigationFactory.php +// Replaces Webware\Navigation\View\Helper\NavigationFactory, which is final final class NavigationFactory { public function __invoke(ContainerInterface $container): Navigation @@ -92,31 +91,6 @@ Register the override in your `ConfigProvider`: --- -## Planned: RendererPluginManager - -The intended future implementation is a dedicated `AbstractPluginManager` subclass -keyed to `RendererInterface`. This will allow renderer override via standard -service-manager config without replacing the factory: - -```php -// config/autoload/navigation.local.php -return [ - 'navigation' => [ - 'renderers' => [ - 'factories' => [ - MenuRenderer::class => TailwindMenuRendererFactory::class, - BreadcrumbRenderer::class => TailwindBreadcrumbRendererFactory::class, - ], - ], - ], -]; -``` - -`NavigationFactory` will detect the `RendererPluginManager` in the container and -resolve all three renderer slots from it, with `null` fallback when a renderer is not -registered. - ---- ## Adding a new nav identifier diff --git a/docs/overview.md b/docs/overview.md index 30887bb..eac3ec9 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -23,22 +23,22 @@ the result without any separate navigation configuration file. ## Package layout ``` -src/webware-navigation/ -└── src/ - ├── ConfigProvider.php - ├── NavigationItem.php - ├── NavigationContainer.php - ├── NavigationFilterIterator.php - ├── Container/ - │ └── NavigationMiddlewareFactory.php - ├── Middleware/ - │ └── NavigationMiddleware.php - ├── Renderer/ - │ └── RendererInterface.php - └── View/ - └── Helper/ - ├── Navigation.php - └── NavigationFactory.php +src/ +├── ConfigProvider.php +├── NavigationItem.php +├── NavigationContainer.php +├── NavigationFilterIterator.php +├── Http/ +│ └── Middleware/ +│ ├── NavigationMiddleware.php +│ └── Container/ +│ └── NavigationMiddlewareFactory.php +├── Renderer/ +│ └── RendererInterface.php +└── View/ + └── Helper/ + ├── Navigation.php + └── NavigationFactory.php ``` --- diff --git a/docs/testing.md b/docs/testing.md index d1f8032..9c99cf2 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -23,6 +23,7 @@ it with a stub `AclInterface` and an array of `Route` objects: use Mezzio\Router\Route; use PHPUnit\Framework\TestCase; use Webware\Core\AclInterface; +use Webware\Core\UserInterface; use Webware\Navigation\NavigationFilterIterator; final class NavigationFilterIteratorTest extends TestCase @@ -33,7 +34,7 @@ final class NavigationFilterIteratorTest extends TestCase $other = $this->makeRoute('/home', 'home', ['navigation' => 'main']); $acl = $this->alwaysAllowAcl(); - $iterator = new NavigationFilterIterator([$route, $other], 'admin', ['admin'], $acl); + $iterator = new NavigationFilterIterator([$route, $other], 'admin', $this->makeUser(), $acl); $results = iterator_to_array($iterator); self::assertCount(1, $results); @@ -46,7 +47,7 @@ final class NavigationFilterIteratorTest extends TestCase $acl = $this->createStub(AclInterface::class); $acl->method('isAllowed')->willReturn(false); - $iterator = new NavigationFilterIterator([$route], 'admin', ['guest'], $acl); + $iterator = new NavigationFilterIterator([$route], 'admin', $this->makeUser(), $acl); $results = iterator_to_array($iterator); self::assertEmpty($results); @@ -57,8 +58,8 @@ final class NavigationFilterIteratorTest extends TestCase $route = $this->makeRoute('/home', 'home', ['navigation' => ['main', 'footer']]); $acl = $this->alwaysAllowAcl(); - $mainResults = iterator_to_array(new NavigationFilterIterator([$route], 'main', ['guest'], $acl)); - $footerResults = iterator_to_array(new NavigationFilterIterator([$route], 'footer', ['guest'], $acl)); + $mainResults = iterator_to_array(new NavigationFilterIterator([$route], 'main', $this->makeUser(), $acl)); + $footerResults = iterator_to_array(new NavigationFilterIterator([$route], 'footer', $this->makeUser(), $acl)); self::assertCount(1, $mainResults); self::assertCount(1, $footerResults); @@ -77,6 +78,11 @@ final class NavigationFilterIteratorTest extends TestCase $acl->method('isAllowed')->willReturn(true); return $acl; } + + private function makeUser(): UserInterface + { + return $this->createStub(UserInterface::class); + } } ``` @@ -167,8 +173,9 @@ $routeCollector->method('getRoutes')->willReturn([$route1, $route2]); Tests that verify ACL filtering end-to-end should use the real `Acl` class (injected with a pre-built `Laminas\Permissions\Acl\Acl`) rather than a stub -so the fail-closed `isAllowed` logic is exercised — blocked until -`webware/acl` + `webware/usermanager` publish. +so the fail-closed `isAllowed` logic is exercised. `Webware\Acl\Acl` lives in +`webware-acl`, which this package does not require, so that test belongs to the +consuming application. --- diff --git a/docs/webware-tools-alignment.md b/docs/webware-tools-alignment.md deleted file mode 100644 index 75e8188..0000000 --- a/docs/webware-tools-alignment.md +++ /dev/null @@ -1,421 +0,0 @@ -# Webware Tools Alignment — webware-navigation (Audit) - -## Purpose - -Audit of `webware/webware-navigation` against the CI/CD and dev-tooling shape -established by `webware/webware-tools` (reusable workflow -`webinertia/webware-tools@0.1.x`). The reference for this audit is the -webware-mailer alignment (`webware-mailer/docs/webware-tools-alignment.md`) — -mailer is the aligned consumer and the template this repo adopts. - -**Scope:** CI/CD pipeline, tooling configs, composer metadata, baseline files, -and the minimum test scaffolding required for a green pipeline. - -**Explicitly out of scope (same as webware-mailer):** - -- PHPStan (`phpstan.neon.dist`, stubs, type-coverage, PHPStan deps). -- Local Docker dev tooling (`bin/install-deps.sh`, `compose.yml`, `docker/`). -- Full test suite for all classes — only scaffolding / minimum required to - keep the pipeline green. -- Benchmarks (`benchmarks/*Bench.php`) — config only. - -## Current state - -Branch `0.1.x` (matches the `[0-9]+.[0-9]+.x` branch pattern the workflow -triggers on). `git ls-files` shows `LICENSE` as the only tracked file; -everything else (src, tests, docs, configs) is untracked — same pre-alignment -state mailer started from. `composer install` has been run this session, so -`vendor/` and a fresh `composer.lock` now exist locally. - -| Artifact | webware-mailer (reference) | webware-navigation (current) | Action | -|---|---|---|---| -| `.github/workflows/continuous-integration.yml` | wrapper calling webware-tools | absent | create | -| `.github/copilot-instructions.md` | present | absent | port | -| `phpunit.xml.dist` | PHPUnit 13.1 schema, suites `unit test` / `integration test`, `ignoreIndirectDeprecations="true"` | **monorepo leftover** — 16 suites, none named `unit test`/`integration test`; suites point at `src/webware-{core,acl,admin,navigation,usermanager,configmanager}/test/*`; `` missing `ignoreIndirectDeprecations` | rewrite to mailer shape | -| `mago.toml` | extends webware-tools, `php-version = "8.4.1"`, baselines | created this session (untracked) | verify, keep | -| `lint-baseline.toml` / `analysis-baseline.toml` | present (3 approved lint issues, empty analysis) | created empty this session | keep empty until fix pass | -| `infection.json5.dist` | present | absent | create | -| `codecov.yml` | present | absent | copy | -| `renovate.json` | present | absent | copy | -| `phpbench.json.dist` | present (no benchmarks dir) | absent | copy (config only) | -| `composer.lock` | committed | absent (generated locally, untracked) | commit | -| `composer.json` scripts | `test`, `test-coverage`, `test-integration`, `mutation-test` | **none** | add | -| require-dev | infection, phpbench, phpunit `^13.3.0`, roave/backward-compatibility-check, roave/security-advisories, webware-tools | phpunit `^13.3.0` ✓, webware-tools ✓, roave/security-advisories ✓, laminas-permissions-acl; **missing** infection, phpbench, backward-compatibility-check | add | -| `config.platform.php` | `8.4.99` | absent | add | -| `config.allow-plugins` | laminas-component-installer, package-versions-deprecated, infection/extension-installer | absent | add as applicable | -| `extra.laminas.config-provider` | present | absent | add (`Webware\Navigation\ConfigProvider`) | -| autoload-dev namespaces | `WebwareTest\\` + `WebwareTestIntegration\\` | `Webware\NavigationTest\` + `Webware\NavigationIntegrationTest\` | rename to mailer pattern | -| `require.php` | `~8.4.1 \|\| ~8.5.0` | `~8.4.0 \|\| ~8.5.0` | align | -| `.gitattributes` / `.gitignore` | mago/phpbench/infection/codecov export-ignore set | php-cs-fixer, phpstan, k6 leftovers; missing mago/phpbench/infection/codecov entries | rewrite to mailer set | -| test suites | both populated | `test/unit` + `test/integration` exist with `.gitkeep` only | keep scaffold; suite is a later step | - -## Probe results (mago runs, this session) - -`mago` 1.46.0, config `mago.toml` as created (extends webware-tools base, -`php-version = "8.4.1"`): - -- `mago format --check` — **6 files need formatting** (list TBD at fix pass). -- `mago lint` — **28 issues**: 3 error, 5 warning, 20 help. - - errors: `cyclomatic-complexity`, `kan-defect`, `too-many-methods` (all in - `src/NavigationContainer.php`) - - warnings: `no-isset` (×2), `literal-named-argument` (×2), - `no-shorthand-ternary` (×1) - - helps: `yoda-conditions` (×10), `string-style` (×5), `no-else-clause` - (×2), `no-negated-ternary` (×1), `ambiguous-function-call` (×1) -- `mago analyze` — **49 issues**: 31 error, 16 warning, 2 help. Dominant - clusters: - - `non-existent-use-import` / `non-existent-class-like` (≈20) for - `Webware\Acl\Acl`, `Webware\Acl\AclInterface`, - `Webware\UserManager\UserInterface` — **blocker**, see Findings. - - `unhandled-thrown-type` (×10) — `Psr\Container\*ExceptionInterface` in the - three `__invoke` factories. - - `side-effects-in-condition` (×7), `mixed-assignment` (×4), - `imprecise-type` (×3), `less-specific-argument` (×2), - `possibly-invalid-argument` (×3), `invalid-method-access` (×1), - `redundant-docblock-type` (×1), `unused-parameter` (×2). -- `mago guard` — no-op. Base webware-tools config defines no guard rules - (perimeter and structural checks report "skipped due to missing - configuration"). Nothing to do here; matches mailer. - -## Findings - -### F1 — Undeclared package dependencies — RESOLVED (Option 3) - -`src/` imports `Webware\Acl\Acl`, `Webware\Acl\AclInterface`, and -`Webware\UserManager\UserInterface`, but no composer package provides them -(verified against the IMS monorepo: neither module has a standalone repo). - -**Resolution: keep the coupling.** Tooling-only alignment (Option 3). The -package is private to IMS, consumed via a VCS repository entry, never published -to Packagist. `mago analyze` stays red on the ≈20 unresolved-symbol errors and -the test jobs stay red until `webware-acl` + `webware-usermanager` publish as a -pair. Full analysis and rejected alternatives: see Research section. - -### F2 — phpunit.xml.dist is a monorepo leftover - -16 suites, 6 of which are sibling-component suites (`webware-core`, -`webware-acl`, `webware-admin`, `webware-usermanager`, -`webware-configmanager`, plus `default` → `test/AppTest`, `async` → -`test/AsyncTest`) that do not exist in this standalone repo. None of the -suites is named `unit test` or `integration test`, which is what the reusable -workflow's `composer test` / `test-coverage` / `test-integration` scripts -select. Strict flags are already correct; missing -`ignoreIndirectDeprecations="true"` on ``. - -### F3 — composer.json gaps - -- No `scripts` section (workflow jobs call `composer test`, - `test-coverage`, `test-integration`, `mutation-test`). -- require-dev missing `infection/infection: ^0.34.1`, - `phpbench/phpbench: ^1.7`, `roave/backward-compatibility-check: ^8.21.0`. -- No `config.platform.php` (mailer pins `8.4.99` for lock resolution). -- No `config.allow-plugins` (`infection/extension-installer` needed once - Infection is added). -- No `extra.laminas.config-provider` despite shipping a `ConfigProvider`. -- autoload-dev namespace convention differs from the mailer/log pattern - (`Webware\NavigationTest\` vs `WebwareTest\Navigation\` / - `WebwareTestIntegration\Navigation\`); test namespaces in `docs/testing.md` - are silent on this, so no code depends on it yet. -- `require.php` is `~8.4.0 || ~8.5.0` (mailer: `~8.4.1 || ~8.5.0`). - -### F4 — Repo-level tool configs absent - -`infection.json5.dist`, `codecov.yml`, `renovate.json`, `phpbench.json.dist` -all missing. Straight copies of the mailer files (infection badge regex -`/^\d+\.\d+\.x$/` matches the `0.1.x` branch). - -### F5 — .gitignore / .gitattributes stale - -Navigation versions carry php-cs-fixer / phpstan / k6 entries and are missing -the mago/phpbench/infection/codecov exports mailer ships. Align to mailer set. - -### F6 — CI wrapper + copilot-instructions absent - -No `.github/` at all. Wrapper mirrors mailer verbatim except inputs: -navigation integration tests run against laminas-view + mezzio-router in -process — no DB image needed (`db-image` omitted). PHPUnit 13 -mock-vs-stub and `requireCoverageMetadata` rules (already present in the -mailer attachment) must be ported to this repo's own -`.github/copilot-instructions.md`. - -### F7 — Empty suites are expected-red until the test-suite step - -`test/unit` + `test/integration` contain only `.gitkeep`. PHPUnit 13 errors on -zero executed tests and Infection cannot score an empty suite, so `test` and -`mutation-test` jobs stay red until tests land. `mago` and `codecov` jobs are -independent of test content. Same accepted-risk posture as mailer's D1. - -### F8 — Docs carry monorepo leftovers - -- `README.md`: "Registered as a path-repository package" and "The PSR-4 - namespace `Webware\Navigation\` maps to `src/webware-navigation/src/`" — - stale monorepo instructions. -- `docs/testing.md`: examples type against `Webware\Acl\AclInterface` - (see F1) and use `final class` test names without namespace guidance - matching the planned autoload-dev rename (F3). -- Docs refresh depends on F1/F3 decisions; flagging, not fixing. - -## Research: interconnection with webware-acl / webware-usermanager (2026-08-17) - -### Sources - -- App monorepo: `/home/jsmith/github.com/tyrsson/inventory-management-system` -- Migration plan: `docs/module/component-migration-plan.md` (§6.6 navigation, - §10.8 extraction order, §12 release availability matrix) - -### In-tree parity - -- `src/webware-navigation/src` in the app is byte-identical to this repo's - `src/` (verified via `diff -rq` — clean). -- In-tree `src/webware-navigation/composer.json` declares `webware/acl: ^0.1` - and `mezzio/mezzio-authentication: ^1.13`; it does **not** declare - `webware/usermanager` — the monorepo autoload hides that hole. The standalone - split dropped both entries. - -### Runtime dependency surface - -- `Webware\Acl\Acl` (`src/webware-acl/src/Acl.php`): - `final class Acl extends Laminas\Permissions\Acl\Acl implements AclInterface`. - Overrides `isAllowed` with three behaviors navigation depends on: - 1. **Fail-closed** — unregistered resource returns `false` (source comment: - "FAIL CLOSED — intentional, do not change to true"). - 2. **DB rule load** — `load()` pulls rules from `RuleRepository`, role - registry from `RoleRepository`, registers route names as resources from - `RouteCollectorInterface`, adds Developer allow-all. - 3. **Multi-role** — `Webware\Acl\Role\UserRoleIterator` iterates - `UserInterface::getRoles()`, any-match wins. -- `Webware\Acl\AclInterface` — navigation uses it only as a type hint, - request-attribute key, and container key. Its own method - `isAllowedRoute(?UserInterface, ResourceInterface)` is a thin wrapper over the - `isAllowed` override; navigation never calls it — it calls - `$acl->isAllowed($user, $route->getName(), null)` directly. -- `Webware\UserManager\UserInterface` - (`src/webware-usermanager/src/UserInterface.php`) extends - `Laminas\Permissions\Acl\Role\RoleInterface`, `ResourceInterface`, - `ProprietaryInterface`, `WithRowDataPrototypeInterface`. Navigation uses it - only as a role carrier passed to `isAllowed`. - -### App wiring - -- `config/pipeline.php`: `IdentityMiddleware` (line 39) → `NavigationMiddleware` - (line 80) → `AclMiddleware` (line 84). -- Navigation is piped **before** `AclMiddleware`, so the `AclInterface::class` - attribute is not yet set when `NavigationMiddleware` runs; the helper's ACL - comes from the container via `NavigationFactory` and persists across requests - (`resetState()` deliberately does not reset `$acl`). -- Attribute setters: `src/webware-usermanager/src/Middleware/IdentityMiddleware.php` - line 73 (`UserInterface::class`), `src/webware-acl/src/Middleware/AclMiddleware.php` - line 22 (`AclInterface::class`). - -### Mutual entanglement - -- `webware-acl` imports `Webware\UserManager\UserInterface`; `webware-usermanager` - imports acl. The two must publish as a **pair** — the migration plan's linear - order (§10.8: acl → admin → navigation → usermanager) does not capture this. -- Migration plan §12: neither `webware/webware-acl` nor - `webware/webware-usermanager` has a standalone repo; neither is on Packagist. - -### Alternatives considered and rejected - -- **Plain-Laminas decouple** (`Laminas\Permissions\Acl\AclInterface` + - `RoleInterface`): call site is identical, but loses fail-closed, DB rule - loading, and multi-role resolution — security-relevant behavior change. - Rejected. -- **Navigation-local contract + app adapter**: preserves semantics and - unblocks standalone CI, but invents a throwaway contract for a temporary - package. Deferred — per strategy of not reinventing the wheel until - laminas-navigation lands. - -### Consumption plan (final) - -- Package is private to IMS. Never published to Packagist. -- Consumer pulls via a VCS repository entry: - -```json -{ - "repositories": [ - { "type": "vcs", "url": "https://github.com/webinertia/webware-navigation" } - ], - "require": { - "webware/webware-navigation": "0.1.x-dev" - } -} -``` - -- `composer update webware/webware-navigation` after each commit here (lock - pins the commit hash). -- IMS autoloads `Webware\Acl\` + `Webware\UserManager\` itself — symbols - unresolved here are resolved there. -- Later: when laminas-navigation releases, an integration layer fills the gaps - for IMS and this package is retired. - -### Consequence for this repo - -- `composer install` stays green (no undeclared requires). -- `mago analyze` stays red on ≈20 unresolved-symbol errors; `test` / coverage / - mutation stay red until the acl + usermanager pair publishes. Accepted. -- `mago format`, `mago lint`, `mago guard` fixes proceed normally. - -## Work items (after F1 decision) - -1. `composer.json`: F3 changes; run `composer update`; commit `composer.lock` - (the `locked` matrix leg requires it). -2. `phpunit.xml.dist`: rewrite to mailer shape — two suites - (`unit test` → `test/unit`, `integration test` → `test/integration`), - ``. -3. Tool configs: `infection.json5.dist`, `codecov.yml`, `renovate.json`, - `phpbench.json.dist` (copies); `mago.toml` + baselines already created — - baselines stay empty until the fix pass; suppressions only with explicit - approval per issue. -4. Mago pass: `mago format` (isolated commit), then lint/analyze fixes for - the findings listed in Probe results; baseline only the approved remainder. -5. `.github/workflows/continuous-integration.yml` wrapper + - `.github/copilot-instructions.md`. -6. `.gitattributes` / `.gitignore` alignment (F5). -7. Docs cleanup (F8) gated on F1/F3 decisions. - -## Decisions for review - -| # | Decision | Open question | -|---|---|---| -| D1 | F1 dependency strategy | **Resolved — Option 3**: keep `Webware\Acl\*` / `Webware\UserManager\*` coupling; tooling-only alignment; VCS consumption; never Packagist | -| D2 | `run-integration` | **Resolved — `true`** (in-process suites, no services) | -| D3 | `enable-codecov` / `enable-infection` | **Resolved — `true` / `true`**, `min-msi: 95`, `min-covered-msi: 95` | -| D4 | autoload-dev rename | **Resolved — adopted** `WebwareTest\Navigation\` + `WebwareTestIntegration\Navigation\` | -| D5 | `config.platform.php` | **Resolved — `8.4.99`** | -| D6 | `require.php` | **Resolved — `~8.4.1 \|\| ~8.5.0`** | -| D7 | Docs cleanup scope | **Resolved — README + testing.md refreshed**; filter-iterator doc examples kept behind a "blocked until deps publish" note | -| D8 | Guard configuration | **Resolved — do nothing** until webware-tools adds guard rules | - -## Proposed execution order (post-review) - -1. F1 resolved (Option 3); apply `composer.json` (F3); `composer update`; - commit lock. -2. Rewrite `phpunit.xml.dist`; create tool configs (item 3). -3. Mago pass (item 4) with isolated format commit. -4. CI wrapper + copilot-instructions (item 5). -5. `.gitattributes` / `.gitignore` (item 6). -6. Docs cleanup per D7. -7. Local verification: `composer validate --strict`, `mago format --check`, - `mago lint`, `mago analyze`, `mago guard` green; `composer test` / - `test-integration` / `test-coverage` / `mutation-test` expected red until - the test-suite step. -8. Push, open PR against `0.1.x`; `mago` + `codecov` jobs green; `test` + - `mutation-test` green when the suite lands. -9. Repo settings (user): Infection dashboard key, Codecov/Renovate app - access, optional branch protection on `0.1.x` (same as mailer). - -## Execution status (2026-08-17) - -Work items 1–6 executed. Local verification: - -- `composer validate --strict` green. -- `mago format --check` green. -- `mago guard` no-op (expected). -- `composer test` green (14 tests, 32 assertions); `composer test-integration` - green (1 test, 6 assertions). -- `mago lint` — 3 remaining errors: `cyclomatic-complexity`, `kan-defect`, - `too-many-methods`, all on `NavigationContainer` (class-splitting refactor; - deferred). -- `mago analyze` — 25 errors + 4 warnings remaining: - - 24 errors: `non-existent-*` for `Webware\Acl\*` / - `Webware\UserManager\*` (accepted per D1 — unresolved until pair-publish). - - 1 error: `possibly-invalid-argument` on `NavigationFilterIterator`'s - `FilterIterator` constructor (stub-generics limitation). - - 4 warnings: `mixed-assignment` — PSR-7 `getAttribute()` returns `mixed` - (3×) and one `$options['navigation'] ?? null` read (1×). -- `composer mutation-test` / `test-coverage` not run locally (no coverage - driver); exercised by the CI canonical leg. - -Baseline candidates (pending explicit user approval per issue): the 3 lint -complexity errors, the 24 dep-driven analyze errors, the 1 -`possibly-invalid-argument`, and the 4 `mixed-assignment` warnings. Nothing has -been baselined yet. - -## Research: mezzio/laminas interface swap + class_alias (2026-08-18) - -Direction change under review: instead of keeping the `Webware\Acl\*` / -`Webware\UserManager\*` coupling (Option 3), type this package against the -underlying laminas/mezzio interfaces with dev dependencies here, then -`class_alias` in the IMS app. Verified feasibility below. **Implementation -deferred — evening session.** - -### Package reality - -- `mezzio/mezzio-permissions-acl` **does not exist** (Packagist 404). The - actual targets are: - - `laminas/laminas-permissions-acl` — `Laminas\Permissions\Acl\AclInterface` - (`hasResource()`, `isAllowed($role = null, $resource = null, $privilege = - null)`), `Role\RoleInterface::getRoleId()`, - `ProprietaryInterface::getOwnerId()`. - - `mezzio/mezzio-authentication` (stable 1.13.0) — - `Mezzio\Authentication\UserInterface`: `getIdentity(): string`, - `getRoles(): iterable`, `getDetail(string $name, $default = null)`, - `getDetails(): array`. -- Plain Laminas `Acl::isAllowed` on an unregistered resource **throws** - `InvalidArgumentException("Resource ... not found")`; the webware override - returns `false` (fail-closed). Behavioral divergence lives in the - implementation, not the interface. - -### Call-site audit — zero API violations - -- `NavigationFilterIterator::accept()`: - `$acl->isAllowed($user, $route->getName(), null)` — exact - `AclInterface::isAllowed` signature match; string resource IDs supported. -- `Route::getName(): string`, `getPath(): string`, `getOptions(): array` — - all used within contract. -- `RouteResult::getMatchedRouteName(): false|string` — middleware already - narrows via `is_string()` after `isFailure()`. -- Navigation **never calls any user method** — user is an opaque role carrier, - request-attribute key, and `instanceof` marker only. - -### Interface parity (webware UserInterface vs mezzio) - -| Method | webware | mezzio | compatible | -|---|---|---|---| -| `getIdentity` | `?string` | `string` | no | -| `getRoles` | `?array` | `iterable` | no | -| `getDetails` | `?array` | `array` | no | -| `getDetail` | `mixed $default`, `: mixed` | untyped | yes | - -Parity is **not exact** (three return-type mismatches). Irrelevant for -navigation today — it invokes none of them — and PHP does not re-validate -signatures at `class_alias` time, so the alias works as a pure type marker. -Risk only if future code calls mezzio-contract methods on the aliased object. - -### class_alias plan — verified possible, app-side requirements - -Alias registered early in app bootstrap: - -```php -class_alias(\Webware\UserManager\UserInterface::class, \Mezzio\Authentication\UserInterface::class); -``` - -Requirements: - -1. App must **not** install the real `mezzio/mezzio-authentication` (name - collision → fatal). -2. Alias must run before the first navigation type check. -3. `::class` constants do not follow aliases — attribute keys break: - `IdentityMiddleware` sets `Webware\UserManager\UserInterface::class` while - navigation reads `Mezzio\Authentication\UserInterface::class` → one-line app - change (or middleware reads both keys). Same for the `AclMiddleware` - attribute key. -4. `NavigationFactory` fetches `Laminas\Permissions\Acl\AclInterface::class` - from the container → app needs one service alias line (aliases do not affect - `::class` strings). - -ACL side needs **no alias**: `Webware\Acl\Acl extends -Laminas\Permissions\Acl\Acl` and already satisfies the Laminas -`AclInterface`. Fail-closed, multi-role, and DB-rule loading all live in that -instance's `isAllowed` override and remain intact. - -### Repo shape when implemented - -- `require`: `laminas/laminas-permissions-acl` (runtime type hints; app - already installs it). -- `require-dev`: `mezzio/mezzio-authentication: ^1.13` (type checking only). -- Type-hint swaps in 4 files (`NavigationFilterIterator`, - `View\Helper\Navigation`, `NavigationMiddleware`, `NavigationFactory`); - all `Webware\Acl\*` / `Webware\UserManager\*` imports leave `src/`. -- VCS consumption unchanged; the alias lives app-side only.