PHPackages                             weblogin/laravel-lookup - 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. [Database & ORM](/categories/database)
4. /
5. weblogin/laravel-lookup

ActiveLibrary[Database & ORM](/categories/database)

weblogin/laravel-lookup
=======================

Laravel lookup objects and Eloquent casts for static data.

v1.1.7(2y ago)7407↓100%1MITPHPPHP ^7.3|^8.0

Since Apr 7Pushed 2y ago2 watchersCompare

[ Source](https://github.com/WebLogin/laravel-lookup)[ Packagist](https://packagist.org/packages/weblogin/laravel-lookup)[ Docs](https://github.com/weblogin/laravel-lookup)[ RSS](/packages/weblogin-laravel-lookup/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (4)Versions (11)Used By (0)

> ⚠️ This Package was originally created on Laravel 7 because it didn't offer this kind of feature. Since Laravel 9 we can use [Enum Eloquent attribute casting](https://laravel.com/docs/9.x/releases#enum-casting), in most cases they can do the same as Laravel-Lookup so we recommend giving them a try instead of our package.

Laravel Lookup
==============

[](#laravel-lookup)

Laravel Lookup helps to have a place to store static data of your Laravel application with little sugar added to it and Eloquent casts to easily use them in your Laravel models. Useful when you don't want to create database tables for every little things, **think of it as static model**.

 [![Collision logo](docs/banner.jpg)](docs/banner.jpg)

Imagine you have a `Car` model with an attribute `engine` that can have the value `gasoline`, `electric` or `hybrid`. Creating a model and a database table can be overkill for this simple key/value data.

In the past we used language files to store this but would end up having to deal with a simple array when calling `Lang::get('car.engines')`. It felt weird and not realy DRY when needing to add some reusable logic for these data. The main goal was having one stable source to get this data and be able to have some flexibility in it.

With a lookup object (other call it Value object) you'll be able to have a collection containing real objects. It lets you use the power of Laravel collection to easily populate a dropdown select, add form validation, populate factories, etc and with Laravel custom cast we can access them like a real model relation for a nice code readability.

- [Installation](#installation)
- [Usage of Lookup](#usage-of-lookup)
- [Usage of Casts](#usage-of-casts)
- [Configuration](#configuration)

Installation
------------

[](#installation)

You can install the package via composer :

```
composer require weblogin/laravel-lookup
```

Usage of Lookup
---------------

[](#usage-of-lookup)

With our `Car` model example that have a `engine` attribute we could create a `CarEngineLookup` in `App/Models/Lookups`. It should look like bellow, with a `getItems()` method returning an array, each item of the array should contain the same keys and they need to be declared as public in the class :

```
namespace App\Models\Lookups;

use WebLogin\LaravelLookup\Lookup;

class CarEngineLookup extends Lookup
{

    public $key;
    public $name;

    protected static function getItems()
    {
        return [
            ['key' => 'gas',    'name' => "Gasoline"],
            ['key' => 'elec',   'name' => "Electric"],
            ['key' => 'hyb',    'name' => "Hybrid"],
        ];
    }

}
```

Because `getItems()` have to return a simple array you can use this package with translation as you like, for example :

```
// resources/lang/en/car.php
return [
    'engines' => [
        'gas'   => "Gasoline",
        'elec'  => "Electric",
        'hyb'   => "Hybrid",
    ],
];

// resources/lang/fr/car.php
return [
    'engines' => [
        'gas'   => "Essence",
        'elec'  => "Electrique",
        'hyb'   => "Hybride",
    ],
];

// app/Models/Lookups/CarEngineLookup.php
protected static function getItems()
{
    $items = [];
    foreach (Lang::get('car.engines') as $key => $value) {
        array_push($items, ['key' => $key, 'name' => $value]);
    }
    return $items;
}
```

A `Lookup` object can be used as a collection by calling any static method on it, so you can do :

```
// Get all the CarEngineLookup objects in a collection
CarEngineLookup::collection();

// Filter on the collection (both are equals)
CarEngineLookup::where('key', '!=', 'gas');
CarEngineLookup::collection()->where('key', '!=', 'gas');
```

The `find()` method should be used to find one or multiple lookups in the collection (return null if nothing found) :

```
// Find one
$engine = CarEngineLookup::find('elec');
$engine->key;     // 'elec'
$engine->name;    // 'Electric'

// Find multiples
$engine = CarEngineLookup::find(['elec', 'hyb']);
```

Populating random values inside model factories

```
$factory->define(Car::class, function (Faker $faker) {
    return [
        'name'     => $faker->words(3, true),
        'engine'   => CarEngineLookup::random(),
        ...
    ];
});
```

Populating select input and Validation :

```

    @foreach (\App\Models\Lookups\CarEngineLookup::collection() as $engine)
        {{ $engine->name }}
    @endforeach

```

```
Validator::make($data, [
    'engine' => ['required', Rule::in(CarEngineLookup::pluck('key'))],
]);
```

Because a `Lookup` is an object you can add attributes (they need to be declared in the class and in the `getItems()` method) and helper methods on the class :

```
class CarEngineLookup extends Lookup
{

    public $key;
    public $name;
    public $sub;

    protected static function getItems()
    {
        return [
            ['key' => 'gas',    'name' => "Gasoline",    'sub' => 'Lorem ipsum'],
            ['key' => 'elec',   'name' => "Electric",    'sub' => 'Dolor amet'],
            ['key' => 'hyb',    'name' => "Hybrid",      'sub' => 'Consectetur adipiscing'],
        ];
    }

    public function icon()
    {
        return URL::asset("images/engines-" . $this->key . ".svg");
    }

    public function fullname()
    {
        return $this->name . ' - ' . $this->sub;
    }

    public static function onlyGreen()
    {
        return static::collection()->where('key', '!=', 'gas');
    }

}

$engine = CarEngineLookup::find('gas');
$engine->icon();                // 'yourdomaine.com/images/engines-gas.svg'
$engine->fullname();            // 'Gasoline - Lorem ipsum'
CarEngineLookup::onlyGreen();   // Collection without gas item
```

Usage of Casts
--------------

[](#usage-of-casts)

There are 2 casts in this package, both of them uses the primary key of the lookup object to get and set values from the database (go to the Configuration section to read more about the primary key) :

- `LookupCast` to store one lookup key in the database
- `LookupCollectionCast` to store multiple lookup keys in the database

### LookupCast

[](#lookupcast)

Still with our `Car` model that have an `engine` attribute, the model would look like this to use the `CarEngineLookup` stored in `App/Models/Lookups`:

```
...
use WebLogin\LaravelLookup\LookupCast;

class Car extends Model
{

    protected $casts = [
        'engine' => LookupCast::class.':'. Lookups\CarEngineLookup::class,
    ];

}
```

In your code you can now access the `engine` attribute object :

```
$car = new Car();
$car->engine = 'elec';
$car->engine->name;     // 'Electric'
$car->engine->key;      // 'elec'
$car->engine->icon();   // 'yourdomaine.com/images/engines-elec.svg'
```

*Note: If the key is not in the collection the attribute equals to NULL.*

### LookupCollectionCast

[](#lookupcollectioncast)

Now our `Car` model needs a `options` attribute that should store multiple options coming from a lookup `CarOptionLookup` :

```
use WebLogin\LaravelLookup\Lookup;

class CarOptionLookup extends Lookup
{

    public $key;
    public $name;

    protected static function getItems()
    {
        return [
            ['key' => 'airbag',    'name' => "Airbag"],
            ['key' => 'abs',       'name' => "Antilock braking system"],
            ['key' => 'rear-cam',  'name' => "Rear camera"],
            ['key' => 'front-cam', 'name' => "Font camera"],
        ];
    }

}
```

```
use WebLogin\LaravelLookup\LookupCollectionCast;

class Car extends Model
{

    protected $casts = [
        ...
        'options' => LookupCollectionCast::class.':'. Lookups\CarOptionLookup::class,
    ];

}
```

In your code you can now access the `options` attribute that return a collection :

```
$car = new Car();

// Set multiple keys
$car->options = ['airbag', 'abs'];
$car->options;                 // Collection
$car->options->first()->name;  // 'Airbag'

// Set one key (both are equals)
$car->options = ['airbag'];
$car->options = 'airbag';

// You can also use Lookup objects
$car->options = CarOptionLookup::find('airbag');
```

*Note: If the keys are not in the collection the attribute equals to NULL.*

### Search in database

[](#search-in-database)

For `LookupCast` you can do a simple `where()` query, nothing special :

```
Car::where('engine', 'elec')->get();
```

For `LookupCollectionCast`, the values are stored in the database as JSON so you can use `whereJsonContains()` but if you pass multiple keys this method search for the presence of each key. To search the presence of at least one key the package include a new database query method `whereInLookupCollection($column, $values)` :

```
Car::whereInLookupCollection('options', 'airbag')->get();
Car::whereInLookupCollection('options', ['rear-cam', 'abs'])->get();

// You can also pass Lookup object
$foo = CarOptionLookup::find('airbag');
Car::whereInLookupCollection('options', $foo)->get();
```

Configuration
-------------

[](#configuration)

### Database column type

[](#database-column-type)

Set database column that will store the value according to your `Lookup` usage, `VARCHAR` for single value and `JSON` for multiple values.

### Primary key

[](#primary-key)

By default a `Lookup` needs to have `key` attribute defined for each item and it needs to be unique (it can by a `string` or `int`). It's used to retrieve the object from the collection. But you can override this primary key by adding a `$primaryKeyName` attribute to the class :

```
class CountryLookup extends Lookup
{

    public $code;
    public $name;
    protected static $primaryKeyName = 'code';

    protected static function getItems()
    {
        return [
            ['code' => 'fra',   'name' => "France"],
            ['code' => 'usa',   'name' => "United States of America"],
            ...
        ];
    }

}
```

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

32

—

LowBetter than 72% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity20

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity63

Established project with proven stability

 Bus Factor1

Top contributor holds 66.7% 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 ~92 days

Recently: every ~72 days

Total

10

Last Release

1030d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/ca2f5a6794385617414f1891c265b5bffe39ab8920995afd6c028d7c16f474b3?d=identicon)[WebLogin](/maintainers/WebLogin)

---

Top Contributors

[![Mushr0000m](https://avatars.githubusercontent.com/u/5532323?v=4)](https://github.com/Mushr0000m "Mushr0000m (10 commits)")[![peterpan666](https://avatars.githubusercontent.com/u/4153168?v=4)](https://github.com/peterpan666 "peterpan666 (5 commits)")

---

Tags

casteloquentlaravellookupstatic-datalaraveleloquentlookupcastwebloginlaravel-lookup

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/weblogin-laravel-lookup/health.svg)

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

###  Alternatives

[watson/validating

Eloquent model validating trait.

9723.3M47](/packages/watson-validating)[silber/bouncer

Eloquent roles and abilities.

3.6k4.4M25](/packages/silber-bouncer)[dyrynda/laravel-model-uuid

This package allows you to easily work with UUIDs in your Laravel models.

4802.8M8](/packages/dyrynda-laravel-model-uuid)[tucker-eric/eloquentfilter

An Eloquent way to filter Eloquent Models

1.8k4.8M26](/packages/tucker-eric-eloquentfilter)[reedware/laravel-relation-joins

Adds the ability to join on a relationship by name.

2121.2M13](/packages/reedware-laravel-relation-joins)[io238/laravel-iso-countries

Ready-to-use Laravel models and relations for country (ISO 3166), language (ISO 639-1), and currency (ISO 4217) information with multi-language support.

5462.3k](/packages/io238-laravel-iso-countries)

PHPackages © 2026

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