README

Hunter Core is a modular architecture foundation for Laravel applications. It provides the base infrastructure for building extensible, tenant-aware applications where functionality is delivered through installable modules.

Features

Fluent Module Configuration - Declarative API for defining modules using method chaining
Navigation System - Unified navigation management across modules with NavItem and NavGroup
Module Registry - Central registry for discovering and managing modules
Tenant-Aware Middleware - Control module access per tenant
PHP 8.4 Property Hooks - Modern PHP features for clean property access
Spatie Package Tools Integration - Built on top of battle-tested spatie/laravel-package-tools

Requirements

PHP 8.4+
Laravel 12+

Installation

Install the package via Composer:

composer require akira/hunter-module

The package auto-registers its service provider via Laravel's package discovery.

Quick Start

Create a module by extending ModuleServiceProvider:

<?php

declare(strict_types=1);

namespace Hunter\Analytics;

use Hunter\Module\Contracts\ModuleServiceProvider;
use Hunter\Module\Module\Module;
use Hunter\Module\Navigation\NavGroup;
use Hunter\Module\Navigation\NavItem;

final class AnalyticsServiceProvider extends ModuleServiceProvider
{
    public function configureModule(Module $module): void
    {
        $module
            ->identifier('hunter/analytics')
            ->name('hunter-analytics')
            ->description('Analytics and reporting for Hunter')
            ->version('1.0.0')
            ->hasConfig()
            ->hasViews()
            ->hasMigrations([
                'create_analytics_events_table',
                'create_analytics_reports_table',
            ])
            ->navigation([
                new NavGroup(
                    title: 'Analytics',
                    icon: 'chart-bar',
                    order: 50,
                    items: [
                        new NavItem('Dashboard', '/analytics', 'layout-dashboard', order: 1),
                        new NavItem('Reports', '/analytics/reports', 'file-text', order: 2),
                    ],
                ),
            ])
            ->author('Hunter Team', 'team@hunter.io')
            ->requiredPlatformVersion('1.0.0')
            ->dependencies(['hunter/core' => '^1.0']);
    }
}

Module Configuration API

Method	Description
`identifier(string)`	Unique module identifier (vendor/name format)
`name(string)`	Package name for config, views, routes
`description(string)`	Human-readable description
`version(string)`	Semantic version
`hasConfig()`	Register config file
`hasViews()`	Register views directory
`hasRoutes()`	Register routes file
`hasTranslations()`	Register translations
`hasMigration(string)`	Register single migration
`hasMigrations(array)`	Register multiple migrations
`hasCommand(string)`	Register single command
`hasCommands(array)`	Register multiple commands
`navigation(array)`	Register navigation items
`author(string, ?string, ?string)`	Set author info
`requiredPlatformVersion(string)`	Minimum platform version
`dependencies(array)`	Module dependencies

Module Registry

Access registered modules via the registry:

$registry = app('hunter.modules');

// Check if module exists
$registry->has('hunter/analytics');

// Get module provider
$provider = $registry->get('hunter/analytics');
$provider->identifier();  // 'hunter/analytics'
$provider->version();     // '1.0.0'

// Get all modules
$registry->all();
$registry->identifiers();
$registry->count();

// Get combined navigation
$registry->navigation();       // All items sorted by order
$registry->navigationItems();  // Only NavItem objects
$registry->navigationGroups(); // Only NavGroup objects

Navigation

Create navigation items and groups:

use Hunter\Module\Navigation\NavItem;
use Hunter\Module\Navigation\NavGroup;

// Simple item
$item = new NavItem(
    title: 'Dashboard',
    href: '/dashboard',
    icon: 'home',
    order: 10,
    badge: '3',        // Optional badge
    external: false,   // Opens in new tab
);

// Group with items
$group = new NavGroup(
    title: 'Settings',
    icon: 'settings',
    order: 100,
    collapsible: true,
    collapsed: false,
);

// Add items fluently (immutable)
$group = $group
    ->withItem(new NavItem('General', '/settings/general', order: 1))
    ->withItem(new NavItem('Security', '/settings/security', order: 2));

// Convert to array for frontend
$item->toArray();
$group->toArray();

Middleware

Protect routes based on tenant module activation:

use Hunter\Module\Http\Middleware\EnsureModuleActive;

// In routes
Route::get('/analytics', AnalyticsController::class)
    ->middleware(EnsureModuleActive::class . ':hunter/analytics');

// With alias (register in bootstrap/app.php)
Route::get('/analytics', AnalyticsController::class)
    ->middleware('module:hunter/analytics');

The middleware checks:

User is authenticated
User has a tenant (via tenant(), tenant property, or currentTenant())
Tenant has the module active (via hasModule() or modules() relationship)

Documentation

Full documentation is available in the docs directory:

Index - Overview and architecture
Installation - Getting started
Creating Modules - Complete module guide
Navigation - NavItem and NavGroup
Middleware - Route protection
Registry - Module registry API

Testing

composer test

Run with coverage:

composer test-coverage

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

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

akira / hunter-module

Maintainers

Details