README

⭐ Found this useful? Install from Packagist · Give it a star on GitHub so more developers can find it.

Nowo Dashboard Menu Bundle — Configurable dashboard menus with i18n (JSON translations), tree structure (parent + position), permissions, Twig rendering and JSON API. No external ORM extensions (Gedmo/Stof). For Symfony 6.4, 7 and 8 · PHP 8.2+.

Table of contents

• Features
• Installation
• Configuration
• Usage
• Documentation
• Requirements
• Demo
• Development
• License & author

Features

• Menu & MenuItem entities: Tree (parent/children, ordered by position), labels with optional JSON translations per locale, optional icon per item (e.g. Symfony UX Icons)
• Context resolution: Same code can have multiple menus with different JSON context (e.g. partnerId, operatorId); pass an ordered list of context sets and the first match is used; empty context = fallback
• Config: Doctrine connection and table prefix; cache (TTL + pool) for the menu tree; icon_library_prefix_map (e.g. bootstrap-icons → bi); locales; per-menu options (classes, permission checker, depth limit, icons, collapsible) in the database
• Permissions: MenuPermissionCheckerInterface — implement and tag to filter items per user/context
• Twig: dashboard_menu_tree(menuCode, permissionContext?, contextSets?), dashboard_menu_href(item), dashboard_menu_config(menuCode, contextSets?); include @NowoDashboardMenuBundle/menu.html.twig
• JSON API: GET /api/menu/{code} for SPA consumption (optional _locale, _context_sets query params)
• Dashboard: CRUD at /admin/menus (list, create, edit, copy menu, manage items); export/import menus as JSON; optional drag-and-drop tree reorder (SortableJS) on a dedicated route; forms split into definition (pencil) and configuration (gear); redirect to referer after successful actions; import available in a modal
• Performance: Two SQL queries per menu (menu + items), optional PSR-6 cache (configurable TTL); labels by locale from JSON; tree built in PHP
• Dev: Web Profiler panel “Dashboard menus” (menus on page, query count, configuration tab: connection, cache, locales, icon map, permission checkers)

Installation

composer require nowo-tech/dashboard-menu-bundle

With Symfony Flex, the recipe (if available) registers the bundle and adds config/routes. Without Flex, see docs/INSTALLATION.md for manual steps.

Configuration

Menus are defined in the database (dashboard at /admin/menus or fixtures): code, name, context (optional JSON), CSS classes. In YAML you only need defaults (and optional project, locales). See docs/CONFIGURATION.md.

# config/packages/nowo_dashboard_menu.yaml
nowo_dashboard_menu:
  project: my_app
  doctrine:
    connection: default
    table_prefix: ''
  cache:
    ttl: 60
    pool: cache.app
  icon_library_prefix_map:
    bootstrap-icons: bi
  locales: ['es', 'en']
  api:
    enabled: true
    path_prefix: /api/menu

Usage

Twig:

{% set tree = dashboard_menu_tree('sidebar') %}
{% set config = dashboard_menu_config('sidebar') %}
{% include '@NowoDashboardMenuBundle/menu.html.twig' with { menuTree: tree, menuCode: 'sidebar', menuConfig: config } %}

With context sets (resolve which menu variant to show):

{% set contextSets = [{ 'partnerId': 1, 'operatorId': 1 }, { 'partnerId': 1 }, {}] %}
{% set tree = dashboard_menu_tree('sidebar', null, contextSets) %}

API: GET /api/menu/sidebar returns JSON tree with label, href, routeName, children. Optional query: _context_sets (JSON array of context objects).

Full details: docs/USAGE.md.

Documentation

• Installation
• Configuration
• Usage
• Contributing
• Changelog
• Upgrading
• Release
• Security
• Engram
• Spec-driven development

Additional documentation

• Demo with FrankenPHP (development and production)
• Demo
• Development

Requirements

• PHP >= 8.2, < 8.6
• Symfony 6.4 (LTS), 7.x or 8.x (^6.4 || ^7.0 || ^8.0)
• Doctrine ORM ^2.13 || ^3.0 (no Gedmo/Stof required)
• Symfony UX Autocomplete & Live Component (installed with the bundle): 2.x (from 2.32 / 2.33) or 3.x

See docs/INSTALLATION.md and docs/UPGRADING.md for compatibility notes.

Demo

Demos (Symfony 7 and 8 only in this repo; the bundle also supports Symfony 6.4 via Composer) are in demo/symfony7 and demo/symfony8. Each uses FrankenPHP with Caddy (HTTP on port 80 in the container). docker-compose defaults to APP_ENV=dev, so the entrypoint uses Caddyfile.dev (no PHP worker) so Twig/PHP changes show on refresh. Worker mode applies to a production-style Caddyfile — docs/DEMO-FRANKENPHP.md. Quick start: docs/DEMO.md.

Default host ports: 8010 (symfony7), 8011 (symfony8) via PORT in each demo’s .env.

From bundle root:

make -C demo/symfony8 up
make -C demo/symfony8 install
# Open http://localhost:8011 (symfony8) or http://localhost:8010 (symfony7), unless PORT is overridden

Development

Run tests and QA with Docker: make up && make install && make test (or make test-coverage, make qa). Without Docker: composer install && composer test. Full details: docs/DEVELOPMENT.md.

Dashboard assets (TS → JS): Built with Vite (as in IconSelectorBundle). Sources under src/Resources/assets/src/ (dashboard.ts, stimulus-live.ts, logger.ts). Output: src/Resources/public/js/dashboard.js (IIFE) and js/stimulus-live.js (ESM), installed by Symfony to public/bundles/nowodashboardmenu/js/.

pnpm install
pnpm run build    # production build (dashboard.js + stimulus-live.js)
pnpm run dev     # watch dashboard.js
pnpm run build:dashboard    # only dashboard.js
pnpm run build:stimulus-live  # only stimulus-live.js

Then run php bin/console assets:install in the app so public/bundles/nowodashboardmenu/js/ is updated.

Tests and coverage

• Tests: PHPUnit (unit and integration suites)
• PHP (Lines): 91.04% (full src/ per PHPUnit summary; main gaps: dashboard controller branches, repository persistence helpers). Run composer test-coverage for the current Summary.
• TS/JS: N/A (bundle ships built assets; optional local pnpm run build or make assets for contributors)
• Python: N/A

License

The MIT License (MIT). Please see LICENSE for more information.

Author

Created by Héctor Franco Aceituno at Nowo.tech