PHPackages                             hasanhawary/lookup-manager - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. hasanhawary/lookup-manager

ActiveLibrary[Utility & Helpers](/categories/utility)

hasanhawary/lookup-manager
==========================

Clean Laravel lookup manager: fetch model lookups and enum lists (app and modules) with no app-coupling.

2.5.5(5d ago)25221MITPHPPHP >=8.1 <8.6CI failing

Since Sep 21Pushed 1w agoCompare

[ Source](https://github.com/hasanhawary/lookup-manager)[ Packagist](https://packagist.org/packages/hasanhawary/lookup-manager)[ Docs](https://github.com/hasanhawary/lookup-manager)[ RSS](/packages/hasanhawary-lookup-manager/feed)WikiDiscussions main Synced 2d ago

READMEChangelogDependencies (5)Versions (37)Used By (1)

🔍 Lookup Manager
================

[](#-lookup-manager)

[![Latest Stable Version](https://camo.githubusercontent.com/b3cf642b18571b1938266c43e6c5601167297bcc1dbb2d2a0f11a6c1cb3607f9/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f686173616e6861776172792f6c6f6f6b75702d6d616e616765722e737667)](https://packagist.org/packages/hasanhawary/lookup-manager)[![Total Downloads](https://camo.githubusercontent.com/3fac307ee2165814146e01a56278a477767b929ea62cac8a2ac36132ad193b07/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646d2f686173616e6861776172792f6c6f6f6b75702d6d616e616765722e737667)](https://packagist.org/packages/hasanhawary/lookup-manager)[![PHP Version](https://camo.githubusercontent.com/7bd0a3c65695edcc6053fd296b9d1e58482458cb47556ab9ea4d695308349659/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f686173616e6861776172792f6c6f6f6b75702d6d616e616765722e737667)](https://packagist.org/packages/hasanhawary/lookup-manager)[![License](https://camo.githubusercontent.com/7013272bd27ece47364536a221edb554cd69683b68a46fc0ee96881174c4214c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e737667)](LICENSE)

A powerful, lightweight, and framework-friendly **Laravel** package for unified lookup management. Handle **dynamic model lookups**, **automatic enum discovery**, and **secure config exposure** with ease. Perfect for building dynamic frontend filters, dropdowns, and admin panels.

---

✨ Features
----------

[](#-features)

### 🏗️ Model Lookup

[](#️-model-lookup)

- **Dynamic Fetching**: Get Eloquent model data using just table names or class names.
- **Auto-Mapping**: Smart name resolution (`display_name` → `title` → `label` → `name` → `first_name + last_name`).
- **Custom Name Fields**: Use `$helpModelName` in your models to define custom display fields.
- **Advanced Filtering**: Apply Eloquent scopes with parameters and custom search terms.
- **Metadata API**: Get a list of all available models with translated names for dynamic UI building.
- **Module Support**: Works out of the box with Laravel Modules.
- **Pagination**: Built-in support for paginated results.

### 🔢 Enum Management

[](#-enum-management)

- **Auto-Discovery**: Automatically finds enums in `app/Enum` and `Modules/*/App/Enum`.
- **Standardized Format**: Returns consistent `key`, `value`, `label`, `snake_key`, `icon`, and `extra` data.
- **Trait-Powered**: `EnumMethods` trait adds powerful helpers like `resolve()`, `getList()`, and `values()`.
- **Custom Methods**: Allow specific enum static methods through `lookup.enums.allowed_methods`.

### 🔒 Secure Configuration

[](#-secure-configuration)

- **Whitelist Approach**: Only expose what you explicitly allow in `config/lookup.php`.
- **Dot Notation**: Fetch nested config keys securely.
- **Safety First**: Prevents accidental exposure of sensitive environment variables.

### 🌍 Localization

[](#-localization)

- **Translation-Aware**: Full support for translating model names and enum labels.
- **Fallback Logic**: Gracefully falls back to class names if translations are missing.

---

📦 Installation
--------------

[](#-installation)

```
composer require hasanhawary/lookup-manager
```

The service provider and facade are automatically registered.

---

⚡ Quick Start
-------------

[](#-quick-start)

### 1. Model Lookups

[](#1-model-lookups)

Fetch specific model data with advanced options:

```
use HasanHawary\LookupManager\Facades\Lookup;

$result = Lookup::getModels([
    'tables' => [
        [
            'name'      => 'users',
            'scopes'    => ['active'],              // Applies scopeActive()
            'extra'     => ['email', 'created_at'], // Additional fields
            'paginate'  => true,
            'per_page'  => 10,
            'search'    => 'John'                   // Search in default name fields
        ],
        [
            'name' => 'roles' // Simple lookup
        ]
    ]
]);
```

#### 🏷️ Customizing the Display Name (`$helpModelName`)

[](#️-customizing-the-display-name-helpmodelname)

By default, the package looks for common name fields (`name`, `title`, etc.). You can explicitly define which field(s) should be used as the `name` in the result by adding a `$helpModelName` property to your model:

```
namespace Vendor\Product\Models;

use Illuminate\Database\Eloquent\Model;

class Product extends Model
{
    // Single field
    public static $helpModelName = 'sku';

    // Or multiple fields (concatenated)
    // public static $helpModelName = ['brand', 'model_number'];
}
```

#### 🔗 Automatic Relation Handling (`with`)

[](#-automatic-relation-handling-with)

When you request relations using the `with` key, the package automatically detects and includes the required foreign keys in the database query. This ensures that Laravel can lazy-load or eager-load the relations correctly without you having to manually add the foreign key to the `extra` fields.

```
$result = Lookup::getModels([
    'tables' => [
        [
            'name' => 'posts',
            'with' => ['author', 'category'] // Foreign keys like 'author_id' are handled automatically
        ]
    ]
]);
```

### 2. Enum Discovery

[](#2-enum-discovery)

Fetch enums from anywhere in your app or modules:

```
$enums = Lookup::getEnums([
    'enums' => [
        ['name' => 'user.status'],               // Uses your configured enum namespace
        ['name' => 'Vendor\\Product\\Enum\\StatusEnum'] // Fully qualified enum class names also work
    ]
]);
```

### 3. Config Exposure

[](#3-config-exposure)

Safely expose frontend-required configs:

```
// Define whitelist in config/lookup.php
'allowed_configs' => [
    'settings' => ['theme', 'logo_url'],
],

// Fetch via API/Facade
$config = Lookup::getConfigs([
    'configs' => [
        ['name' => 'settings']
    ]
]);
```

---

🛠️ The `EnumMethods` Trait
--------------------------

[](#️-the-enummethods-trait)

Unlock the full power of Enums by adding the trait to your Enum classes:

```
namespace Vendor\Product\Enum;

use HasanHawary\LookupManager\Trait\EnumMethods;

enum StatusEnum: int
{
    use EnumMethods;

    case ACTIVE = 1;
    case INACTIVE = 0;

    public static function icons(): array {
        return [self::ACTIVE->value => 'check-circle'];
    }
}
```

**What you get:**

- `StatusEnum::getList()`: Structured array for dropdowns.
- `StatusEnum::resolve($value)`: Get the human-readable label for a value.
- `StatusEnum::values()`: Get all raw values.
- `StatusEnum::commentFormat()`: Quick string for DB migrations.

---

🌐 HTTP API
----------

[](#-http-api)

The package registers these routes automatically by default:

MethodDefault pathDefault route nameController action`GET``/api/help-models``models``HelpController@models``GET``/api/help-enums``enums``HelpController@enums``GET``/api/help-configs``config``HelpController@config`You do not need to define these routes in the host application. Configure route enablement, prefix, middleware, names, and paths in `config/lookup.php`.

By default the routes use the `api` prefix and `['api']` middleware. Add your own auth middleware if these endpoints should require authentication.

If the host project already has a route with the same HTTP method and path, or the same route name, Lookup Manager skips only that package route. This prevents the package from taking over an existing project route. You can avoid collisions explicitly by setting a prefix, custom paths, or a route name prefix:

```
// config/lookup.php
'routes' => [
    'enabled' => true,
    'prefix' => 'lookup',
    'middleware' => ['api'],
    'name_prefix' => 'lookup.',

    'paths' => [
        'models' => 'help-models',
        'enums' => 'help-enums',
        'config' => 'help-configs',
    ],
],
```

With that config the prepared routes become:

MethodPathRoute name`GET``/lookup/help-models``lookup.models``GET``/lookup/help-enums``lookup.enums``GET``/lookup/help-configs``lookup.config`### Upgrade Note: Route Prefix

[](#upgrade-note-route-prefix)

The prepared package routes now use the `api` prefix by default:

- `/api/help-models`
- `/api/help-enums`
- `/api/help-configs`

If your project still needs the older unprefixed URLs, publish the config and set `lookup.routes.prefix` to an empty string:

```
'routes' => [
    'prefix' => '',
],
```

---

⚙️ Configuration
----------------

[](#️-configuration)

Publish the config file to define whitelists and root-excluded models:

```
php artisan vendor:publish --tag="lookup-manager-config"
```

### Root Excluded Models

[](#root-excluded-models)

Automatically apply `scopeExcludeRoot` to specific models (like Admin/Role) to prevent exposing "root" system records:

```
// config/lookup.php
'root_excluded_models' => [
    Vendor\Product\Models\User::class,
],
```

### Application and Module Namespaces

[](#application-and-module-namespaces)

Laravel projects can usually leave `models.namespaces`, `models.paths`, `enums.namespaces`, and `enums.paths` empty; the package will infer the application namespace and standard Laravel paths when available.

For custom app structures or modules, configure namespaces explicitly:

```
'models' => [
    'namespaces' => ['Vendor\\Product\\Models'],
    'paths' => [base_path('src/Models')],
],

'enums' => [
    'namespaces' => ['Vendor\\Product\\Enum'],
    'paths' => [base_path('src/Enum')],
],

'modules' => [
    'enabled' => true,
    'path' => 'Modules',
    'namespace' => 'Modules',
    'model_namespace' => 'Domain\\Models',
    'enum_namespace' => 'Domain\\Enum',
],
```

### Plain PHP Usage

[](#plain-php-usage)

The HTTP routes, FormRequests, Eloquent model lookup, and Laravel config lookup are Laravel features. Core enum helpers and config lookup can be used outside a Laravel application when dependencies are provided explicitly. Laravel-only features return empty results or throw validation exceptions instead of relying on host-project helpers.

---

✅ Compatibility
---------------

[](#-compatibility)

- **PHP:** 8.0+
- **Laravel:** 10, 11, 12, 13

---

📜 License
---------

[](#-license)

MIT © [Hasan Hawary](https://github.com/hasanhawary)

---

###  Health Score

52

—

FairBetter than 96% of packages

Maintenance99

Actively maintained with recent releases

Popularity20

Limited adoption so far

Community13

Small or concentrated contributor base

Maturity65

Established project with proven stability

 Bus Factor1

Top contributor holds 69.2% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~8 days

Total

34

Last Release

5d ago

Major Versions

v1.9.0 → v2.0.02026-02-12

PHP version history (3 changes)v1.0.0PHP ^8.0

v1.0.2PHP >8.0

2.5.2PHP >=8.1 <8.6

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/33836947?v=4)[Hassan Elhawary](/maintainers/hasanhawary)[@hasanhawary](https://github.com/hasanhawary)

---

Top Contributors

[![anabiiil](https://avatars.githubusercontent.com/u/37551156?v=4)](https://github.com/anabiiil "anabiiil (9 commits)")[![hassanmuhammd](https://avatars.githubusercontent.com/u/126090873?v=4)](https://github.com/hassanmuhammd "hassanmuhammd (3 commits)")[![hasanhawary](https://avatars.githubusercontent.com/u/33836947?v=4)](https://github.com/hasanhawary "hasanhawary (1 commits)")

---

Tags

laravelhelpersmodelslookupenums

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/hasanhawary-lookup-manager/health.svg)

```
[![Health](https://phpackages.com/badges/hasanhawary-lookup-manager/health.svg)](https://phpackages.com/packages/hasanhawary-lookup-manager)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3355.3M346](/packages/psalm-plugin-laravel)[renatomarinho/laravel-page-speed

Laravel Page Speed

2.5k1.7M11](/packages/renatomarinho-laravel-page-speed)[vinkius-labs/laravel-page-speed

Laravel Page Speed

2.5k12.5k1](/packages/vinkius-labs-laravel-page-speed)[emargareten/inertia-modal

Inertia Modal is a Laravel package that lets you implement backend-driven modal dialogs for Inertia apps.

90142.9k](/packages/emargareten-inertia-modal)[wearepixel/laravel-cart

A cart implementation for Laravel

1374.8k](/packages/wearepixel-laravel-cart)[tomshaw/electricgrid

A feature-rich Livewire package designed for projects that require dynamic, interactive data tables.

119.4k](/packages/tomshaw-electricgrid)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)