README

Hate the WordPress NavWalker? Me too.

Navi is a developer-friendly alternative to the NavWalker. Easily build your WordPress menus using an iterable object inside of a template/view.

Requirements

PHP >= 8.0

Installation

Bedrock (or Sage)

Install via Composer:

$ composer require log1x/navi

Manual

Download the latest release .zip and install into wp-content/plugins.

Usage

Check out the examples folder to see how to use Navi in your project.

Basic Usage

<?php

use Log1x\Navi\Navi;

$navigation = Navi::make()->build('primary_navigation');

if ($navigation->isEmpty()) {
  return;
}

return $navigation->toArray();

When building the navigation menu, Navi retains the menu object and makes it available using the get() method.

By default, get() returns the rawwp_get_nav_menu_object() allowing you to access it directly.

Optionally, you may pass a key and default to call a specific object key with a fallback have it be null, empty, or not set.

$navigation->get()->name;
$navigation->get('name', 'My menu title');

Acorn Usage

If you are using Navi alongside Acorn (e.g. Sage), you may generate a usable view component using Acorn's CLI:

$ acorn make:navi

Once generated, you may use the view component in an existing view like so:

<x-navigation />

Accessing Page Objects

If your menu item is linked to a page object (e.g. not a custom link) – you can retrieve the ID of the page using the objectId attribute.

# Blade
{{ get_post_type($item->objectId) }}

# PHP
<?php echo get_post_type($item->objectId); ?>

Accessing Custom Fields

In a scenario where you need to access a custom field attached directly to your menu item – you can retrieve the ID of the menu item using the id attribute.

Below we'll get a label override field attached to our menu using ACF – falling back to the default menu label if the field is empty.

# Blade
{{ get_field('custom_nav_label', $item->id) ?: $item->label }}

# PHP
<?php echo get_field('custom_nav_label', $item->id) ?: $item->label; ?>

Example Output

When calling build(), Navi will parse the passed navigation menu and return a fluent container containing your menu items. To return an array of objects, simply call ->toArray().

By default, build() calls primary_navigation which is the default menu theme location on Sage.

array [
  5 => {
    +"active": true
    +"activeAncestor": false
    +"activeParent": false
    +"classes": "example"
    +"dbId": 5
    +"description": false
    +"id": 5
    +"label": "Home"
    +"object": "page"
    +"objectId": "99"
    +"parent": false
    +"slug": "home"
    +"target": "_blank"
    +"title": false
    +"type": "post_type"
    +"url": "https://sage.test/"
    +"xfn": false
    +"order": 1
    +"parentObjectId": false
    +"children": false
  }
  6 => {
    +"active": false
    +"activeAncestor": false
    +"activeParent": false
    +"classes": false
    +"dbId": 6
    +"description": false
    +"id": 6
    +"label": "Sample Page"
    +"object": "page"
    +"objectId": "100"
    +"parent": false
    +"slug": "sample-page"
    +"target": false
    +"title": false
    +"type": "post_type"
    +"url": "https://sage.test/sample-page/"
    +"xfn": false
    +"order": 2
    +"parentObjectId": false
    +"children": array [
      7 => {
        +"active": false
        +"activeAncestor": false
        +"activeParent": false
        +"classes": false
        +"dbId": 7
        +"description": false
        +"id": 7
        +"label": "Example"
        +"object": "custom"
        +"objectId": "101"
        +"parent": 6
        +"slug": "example"
        +"target": false
        +"title": false
        +"type": "custom"
        +"url": "#"
        +"xfn": false
        +"order": 3
        +"parentObjectId": 100
        +"children": array [
          ...
        ]
      }
    ]
  }
]

That being said, depending on how deep your menu is– you can ultimately just keep looping over ->children indefinitely.

Bug Reports

If you discover a bug in Navi, please open an issue.

Contributing

Contributing whether it be through PRs, reporting an issue, or suggesting an idea is encouraged and appreciated.

License

Navi is provided under the MIT License.

log1x / navi

Maintainers

Details