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. v2.2.0(2mo ago)12911MITPHPPHP >8.0 Since Sep 21Pushed 2mo 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 1mo ago READMEChangelogDependencies (1)Versions (28)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 lightweight, framework-friendly **Laravel** package for dynamic **model lookups**, **enum discovery**, and \* *translation-aware enum lists*\*. --- 🚀 Features ---------- [](#-features) ### Model Lookup Features [](#model-lookup-features) - Fetch dynamic lookup lists from **Eloquent models** with `Lookup::getModels()`. - **Get all models metadata** with translated names using `Lookup::getModels([])` or when no tables are specified. - Apply **Eloquent scopes** with optional parameters. - Include **extra fields** beyond `id` and default name fields. - Automatic **name mapping** using prioritized fields: ``` display_name → title → label → name → first_name + last_name ``` - **Custom name field override** via `$helpModelName` property on any model: ``` class Country extends Model { public $helpModelName = 'code'; // 'name' in lookups will use 'code' field } ``` - Supports **searching/filtering**: - Accepts a **string** or an **array** with `'term'` and optional `'fields'`. - Defaults to name fields if `'fields'` not provided. - Supports **pagination** with `per_page` and `page`. - Works with **module-based models**: `Modules\{Module}\App\Models\{Model}`. - Special handling for `User` and `Role` models (`excludeRoot()` applied automatically). - Graceful error handling and logging for missing models, invalid scopes, or runtime errors. - Transforms results into **standardized arrays**: ``` [ 'id' => 1, 'name' => 'EG', // from $helpModelName = 'code' 'code' => 'EG', // extra field 'iso' => 'EGY', // extra field ] ``` --- ### Enum Lookup Features [](#enum-lookup-features) - Automatically discovers enums in `app/Enum/**` or `Modules/*/App/Enum/**`. - Fetch specific enums using **dot notation**: `'user.status'` → `App\Enum\User\StatusEnum`. - Supports **module-based enums**: `Modules\Blog\App\Enum\BarEnum`. - Call **default `getList()`** or any **custom static method** using `Lookup::getEnums()`. - Returns fully structured arrays including: `key`, `value`, `label`, `snake_key`, `icon`, `extra`. - **Get all enums metadata** with translated labels using `Lookup::getEnums([])` or when no enums are specified. - Logs errors if the enum class or method is missing. Example return: ``` [ ['key' => 'ACTIVE', 'value' => 1, 'label' => 'Active', 'snake_key' => 'active', 'icon' => 'check', 'extra' => null], ['key' => 'INACTIVE', 'value' => 0, 'label' => 'Inactive', 'snake_key' => 'inactive', 'icon' => 'close', 'extra' => null], ] ``` --- ### Enum Helper Methods (`EnumMethods` Trait) [](#enum-helper-methods-enummethods-trait) For any Enum using the `EnumMethods` trait: ``` use App\Enum\User\StatusEnum; // Get full translated list StatusEnum::getList(); // Resolve a single value StatusEnum::resolve(1); // returns 'Active' // Get all enum values StatusEnum::values(); // [1, 0] // Generate comment-friendly format StatusEnum::commentFormat(); // "1 => Active, 0 => Inactive" ``` --- 📦 Installation -------------- [](#-installation) ``` composer require hasanhawary/lookup-manager ``` - Auto-discovers the service provider. - **Facade alias**: `Lookup` → `HasanHawary\LookupManager\Facades\Lookup`. --- ⚡ Quick Start ------------- [](#-quick-start) ### Fetch Model Lookups [](#fetch-model-lookups) ``` use HasanHawary\LookupManager\Facades\Lookup; $models = Lookup::getModels([ [ 'name' => 'countries', 'scopes' => ['active'], // model scopes only 'extra' => ['code', 'iso'], // additional fields 'paginate' => true, 'per_page' => 15, 'page' => 1, 'search' => [ 'term' => 'Eg', 'fields' => ['name', 'code'] // optional, defaults to name fields ] ], [ 'name' => 'roles', // simple lookup ], ]); // Or fetch all models metadata with translated names: $allModels = Lookup::getModels([]); // Returns: [ // ['name' => 'Users', 'model' => 'User', 'table' => 'users'], // ['name' => 'Posts', 'model' => 'Post', 'table' => 'posts'], // ... // ] ``` --- ### Custom Name Fields with `$helpModelName` [](#custom-name-fields-with-helpmodelname) If your model defines a `$helpModelName` property, Lookup Manager will **prefer this field for the `name` key**: ``` class Country extends Model { public $helpModelName = 'code'; } ``` Output: ``` [ 'id' => 1, 'name' => 'EG', // from helpModelName 'code' => 'EG', ] ``` **Fallback behavior:** If `$helpModelName` is not defined, Lookup Manager will use the prioritized default name fields ( `display_name`, `title`, `label`, `name`, `first_name + last_name`). --- ### Fetch Enum Lookups [](#fetch-enum-lookups) ``` use HasanHawary\LookupManager\Facades\Lookup; $enums = Lookup::getEnums([ ['name' => 'user.status'], // App\Enum\User\StatusEnum::getList() ['name' => 'user.roles', 'method' => 'getOptions'], // custom method ['name' => 'bar', 'module' => 'blog'], // Modules\Blog\App\Enum\BarEnum::getList() ]); // Or fetch all enums metadata with translated labels: $allEnums = Lookup::getEnums([]); // Returns: [ // ['label' => 'Status', 'key' => 'user.status'], // ['label' => 'User Roles', 'key' => 'user.role'], // ... // ] ``` --- 🌐 HTTP API Usage ---------------- [](#-http-api-usage) - **Routes (`api.php`)**: ``` Route::prefix('help')->name('help.')->group(function () { Route::post('models', [HelpController::class, 'models']); Route::post('enums', [HelpController::class, 'enums']); Route::post('configs', [HelpController::class, 'configs']); }); ``` - **Controller example**: ``` use HasanHawary\LookupManager\Facades\Lookup; class HelpController extends Controller { public function models(HelpModelRequest $request) { return response()->json(Lookup::getModels($request->all())); } public function enums(HelpEnumRequest $request) { return response()->json(Lookup::getEnums($request->all())); } public function configs(HelpEnumRequest $request) { return response()->json(Lookup::getConfigs($request->all())); } } ``` - **Example request payloads**: Models: ``` { "tables": [ { "name": "users", "scopes": [ "active" ], "extra": [ "email" ], "paginate": true, "per_page": 15, "page": 1, "search": { "term": "John", "fields": [ "name", "email" ] } }, { "name": "roles" } ] } ``` Enums: ``` { "enums": [ { "name": "user.status" }, { "name": "bar", "module": "blog" } ] } ``` Configs: **Response Example**: ``` { "data": { "notifications": { "channels": { "push": { "enabled": true, "driver": "fcm", "timeout": 30, "retry": 3, "required_data": [ "title", "body" ] } } } } } ``` --- 🌐 Localization Support ---------------------- [](#-localization-support) The package supports **translation** for both **models** and **enums** through Laravel's localization system. ### Setup Translation Files [](#setup-translation-files) Create a `lookup.php` file in your `lang` directory (e.g., `lang/en/lookup.php` or `lang/ar/lookup.php`): ```