KMP PHP API Reference

NavigationRegistry
in package
uses StaticConfigTrait

Centralized registry for application navigation items from core and plugins.

Uses static registration pattern instead of events. Plugins register navigation during bootstrap. Items are session-cached and filtered via Member::canAccessUrl().

Tags
see
NavigationService

Business logic service layer

see
AppNavCell

View cell that renders navigation

Table of Contents

Constants

NAVIGATION_CACHE_VERSION  = 2

Properties

$initialized  : bool
$navigationItems  : array<string|int, mixed>

Methods

clear()  : void
Clear all registered navigation items (useful for testing)
getDebugInfo()  : array<string|int, mixed>
Get debug information about registered navigation
getNavigationItems()  : array<string|int, mixed>
Get all registered navigation items for a user
getNavigationItemsFromSource()  : array<string|int, mixed>
Get navigation items from a specific source
getRegisteredSources()  : array<string|int, mixed>
Get all registered sources
isRegistered()  : bool
Check if a source is registered
register()  : void
Register navigation items from a source.
unregister()  : void
Remove navigation items from a specific source
ensureInitialized()  : void
Ensure the registry is initialized This can be used to set up default configurations if needed
getLatestRestoreCompletionTimestamp()  : int|null
Get latest restore completion timestamp.
isCachedNavigationStaleForRestore()  : bool

Constants

Properties

$navigationItems

private static array<string|int, mixed> $navigationItems = []

[source => ['items' => [...], 'callback' => callable|null]]

Methods

clear()

Clear all registered navigation items (useful for testing)

public static clear() : void

getDebugInfo()

Get debug information about registered navigation

public static getDebugInfo() : array<string|int, mixed>
Return values
array<string|int, mixed> —

Debug information

getNavigationItems()

Get all registered navigation items for a user

public static getNavigationItems(Member $user[, array<string|int, mixed> $params = [] ][, Session|null $session = null ]) : array<string|int, mixed>

Retrieves navigation items from all registered sources, processes dynamic callbacks, and applies session caching for performance. Items are returned in registration order but can be sorted by the view layer using the 'order' property.

The session caching mechanism stores computed navigation items to avoid regenerating them on every request. This cache is cleared when the session is destroyed or when navigation registration changes.

Dynamic callbacks receive the current user and request parameters, allowing them to:

  • Generate user-specific navigation items
  • Include data-driven badges (e.g., pending count indicators)
  • Modify items based on user permissions or roles
  • Respond to current application context
Parameters
$user : Member

The current authenticated user

$params : array<string|int, mixed> = []

Request parameters for context (controller, action, etc.)

$session : Session|null = null
Tags
example 
$navigationService = new NavigationService();
$items = NavigationRegistry::getNavigationItems($currentUser, [
    'controller' => 'Members',
    'action' => 'index'
]);

// Items structure:
// [
//     ['type' => 'parent', 'label' => 'Members', 'icon' => 'bi-people'],
//     ['type' => 'item', 'label' => 'View All', 'parent' => 'members'],
//     ['type' => 'item', 'label' => 'Add New', 'parent' => 'members']
// ]
Return values
array<string|int, mixed> —

All navigation items from registered sources

getNavigationItemsFromSource()

Get navigation items from a specific source

public static getNavigationItemsFromSource(string $source, Member $user[, array<string|int, mixed> $params = [] ]) : array<string|int, mixed>

Retrieves navigation items from a single registered source, including any dynamic items generated by the source's callback. Useful for debugging, testing, or building specialized navigation displays.

Parameters
$source : string

Source identifier to retrieve

$user : Member

The current authenticated user

$params : array<string|int, mixed> = []

Request parameters for callback context

Tags
example 
// Get only core navigation items
$coreItems = NavigationRegistry::getNavigationItemsFromSource('core', $user);

// Get plugin-specific items with context
$awardItems = NavigationRegistry::getNavigationItemsFromSource('Awards', $user, [
    'current_branch' => $branchId
]);
Return values
array<string|int, mixed> —

Navigation items from the specified source, or empty array if not found

getRegisteredSources()

Get all registered sources

public static getRegisteredSources() : array<string|int, mixed>
Return values
array<string|int, mixed> —

List of registered source identifiers

isRegistered()

Check if a source is registered

public static isRegistered(string $source) : bool
Parameters
$source : string

Source identifier

Return values
bool —

True if registered

register()

Register navigation items from a source.

public static register(string $source, array<string|int, mixed> $items[, callable|null $callback = null ]) : void
Parameters
$source : string

Unique source identifier (e.g., 'core', 'Awards')

$items : array<string|int, mixed>

Static navigation items

$callback : callable|null = null

Optional dynamic item generator: fn(Member, array): array

Return values
void — 
return [];

});

unregister()

Remove navigation items from a specific source

public static unregister(string $source) : void

Unregisters all navigation items and callbacks from the specified source. Useful for plugin cleanup or dynamic navigation management. This operation will clear the session cache to ensure stale items are not displayed.

Parameters
$source : string

Source identifier to remove

Tags
example 
// Remove plugin navigation during plugin unload
NavigationRegistry::unregister('Awards');

// Clear core navigation (typically not recommended)
NavigationRegistry::unregister('core');

ensureInitialized()

Ensure the registry is initialized This can be used to set up default configurations if needed

private static ensureInitialized() : void

getLatestRestoreCompletionTimestamp()

Get latest restore completion timestamp.

private static getLatestRestoreCompletionTimestamp() : int|null
Return values
int|null

isCachedNavigationStaleForRestore()

private static isCachedNavigationStaleForRestore(array<string, mixed> $cached, int|null $latestRestoreCompletion) : bool
Parameters
$cached : array<string, mixed>
$latestRestoreCompletion : int|null
Return values
bool 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results