KMP PHP API Reference

NavigationCell extends Cell
in package

Navigation cell

View Cell responsible for building and organizing the complete navigation menu structure for the KMP application. This cell handles the complex logic of organizing navigation items into hierarchical menus with proper active state detection and permission-based filtering.

The cell works with the NavigationRegistry service to collect navigation items from various plugins and core modules, then organizes them into a structured menu hierarchy with parent categories, main links, and sublinks.

Key Features:

  • Dynamic menu generation based on user permissions
  • Hierarchical organization (Parent > Child > Sublink)
  • Active state detection for current page highlighting
  • Plugin-extensible navigation system
  • Responsive menu structure support

Template: templates/cell/Navigation/display.php

Tags
see
NavigationRegistry

Navigation item collection service

Table of Contents

Constants

BADGE_CACHE_TTL_SECONDS  : mixed = 60
FILTERED_NAV_CACHE_VERSION  : mixed = 1

Properties

$_validCellOptions  : array<string, mixed>
List of valid options that can be passed into this cell's constructor.
$badgeStatusMemo  : array<string, int>
Request-local badge lookup memo keyed by badge configuration.

Methods

display()  : void
Default display method for building navigation menu
initialize()  : void
Initialization logic run at the end of object construction.
authorizedMenuItems()  : array<string|int, mixed>
Filter navigation items once per user/session so repeated renders avoid policy/database work.
getBadgeStatus()  : mixed
Get badge status.
hasBadge()  : bool
Check if has badge.
isActive()  : bool
Determine if a navigation link is active based on current request
organizeMenu()  : array<string|int, mixed>
Organize navigation items into hierarchical menu structure
badgeCacheKey()  : string
navigationSourceHash()  : string
Build a stable hash for generated navigation items without request-active state.
readCachedBadgeValue()  : int|null
Read a short-lived session badge value.
restoreCompletionGeneration()  : string
Get the latest restore completion marker for cache invalidation.
writeCachedBadgeValue()  : void
Write a short-lived session badge value.

Constants

BADGE_CACHE_TTL_SECONDS

private mixed BADGE_CACHE_TTL_SECONDS = 60

FILTERED_NAV_CACHE_VERSION

private mixed FILTERED_NAV_CACHE_VERSION = 1

Properties

$_validCellOptions

List of valid options that can be passed into this cell's constructor.

protected array<string, mixed> $_validCellOptions = []

Currently empty as this cell doesn't accept configuration options, but maintained for future extensibility.

$badgeStatusMemo

Request-local badge lookup memo keyed by badge configuration.

protected array<string, int> $badgeStatusMemo = []

Methods

display()

Default display method for building navigation menu

public display() : void

Collects navigation items from the NavigationRegistry based on the current user and request context, then organizes them into a hierarchical menu structure. The resulting menu includes proper active state detection and permission filtering.

Process Flow:

  1. Extract current user and request parameters
  2. Collect navigation items from registry (filtered by permissions)
  3. Organize items into hierarchical structure
  4. Set organized menu for template rendering

The menu structure returned includes:

  • Parent categories with children
  • Main navigation links
  • Sublinks under main categories
  • Active state flags for current page
Tags
see
NavigationRegistry::getNavigationItems()

Item collection

organizeMenu()

Menu hierarchy organization

Return values
void —

Menu data is set via $this->set() for template access

initialize()

Initialization logic run at the end of object construction.

public initialize() : void

Currently no initialization required, but maintained for potential future setup needs.

authorizedMenuItems()

Filter navigation items once per user/session so repeated renders avoid policy/database work.

protected authorizedMenuItems(array<string|int, mixed> $menuItems, Member $user) : array<string|int, mixed>
Parameters
$menuItems : array<string|int, mixed>

Navigation items.

$user : Member

Current user.

Return values
array<string|int, mixed>

getBadgeStatus()

Get badge status.

protected getBadgeStatus(mixed $badgeConfig) : mixed
Parameters
$badgeConfig : mixed

hasBadge()

Check if has badge.

protected hasBadge(mixed $link, mixed $currentRequestString) : bool
Parameters
$link : mixed
$currentRequestString : mixed
Return values
bool

isActive()

Determine if a navigation link is active based on current request

protected isActive(array<string|int, mixed> $link, string $currentRequestString) : bool

Checks if the given navigation link should be marked as active by comparing its URL and active paths against the current request string. Supports both exact matching and wildcard pattern matching for flexible active state detection.

Active State Matching:

  1. Exact URL match: Link URL exactly matches current request
  2. Active paths: Link defines specific paths that should mark it active
  3. Wildcard matching: Paths ending with '*' match URL prefixes
Parameters
$link : array<string|int, mixed>

Navigation link item with 'url' and optional 'activePaths'

$currentRequestString : string

Normalized current request path (controller/action/params)

Tags
example 
// Exact match
$link = ['url' => '/members/index'];
$current = 'members/index';
// Returns: true

// Wildcard match
$link = ['url' => '/members', 'activePaths' => ['members/*']];
$current = 'members/view/123';
// Returns: true (matches wildcard pattern)

// No match
$link = ['url' => '/branches'];
$current = 'members/index';
// Returns: false
see
StaticHelpers::makePathString()

URL normalization helper

Return values
bool —

True if the link should be marked as active

organizeMenu()

Organize navigation items into hierarchical menu structure

protected organizeMenu(array<string|int, mixed> $menuItems) : array<string|int, mixed>

Takes the flat array of navigation items from the registry and organizes them into a hierarchical structure with parents, children, and sublinks. Also handles active state detection based on the current request URL.

Menu Organization:

  • Parent items: Top-level categories (type='parent')
  • Main links: Direct children of parents (mergePath length = 1)
  • Sublinks: Third-level items under main links (mergePath length > 1)

Active State Logic:

  • Marks current page and its parent hierarchy as active
  • Uses exact URL matching and wildcard pattern matching
  • Only one active path is marked to prevent conflicts
Parameters
$menuItems : array<string|int, mixed>

Flat array of navigation items from NavigationRegistry

Tags
example 
// Input: Flat navigation items
[
  ['type' => 'parent', 'label' => 'Members', 'order' => 1],
  ['type' => 'link', 'label' => 'View All', 'mergePath' => ['Members'], 'url' => '/members'],
  ['type' => 'link', 'label' => 'Add Member', 'mergePath' => ['Members', 'View All'], 'url' => '/members/add']
]

// Output: Hierarchical structure
[
  'Members' => [
    'label' => 'Members',
    'active' => true,
    'children' => [
      'View All' => ['label' => 'View All', 'active' => true, 'sublinks' => [...]]
    ]
  ]
]
Return values
array<string|int, mixed> —

Hierarchically organized menu structure with active states

badgeCacheKey()

private badgeCacheKey(string $memoKey) : string
Parameters
$memoKey : string

Badge memo key.

Return values
string

navigationSourceHash()

Build a stable hash for generated navigation items without request-active state.

private navigationSourceHash(array<string|int, mixed> $menuItems) : string
Parameters
$menuItems : array<string|int, mixed>

Navigation items.

Return values
string

readCachedBadgeValue()

Read a short-lived session badge value.

private readCachedBadgeValue(string $memoKey) : int|null
Parameters
$memoKey : string

Badge cache key.

Return values
int|null

restoreCompletionGeneration()

Get the latest restore completion marker for cache invalidation.

private restoreCompletionGeneration() : string
Return values
string

writeCachedBadgeValue()

Write a short-lived session badge value.

private writeCachedBadgeValue(string $memoKey, int $value) : void
Parameters
$memoKey : string

Badge cache key.

$value : int

Badge value.

On this page

Search results