PHPackages                             brekitomasson/laravel-model-finder - 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. brekitomasson/laravel-model-finder

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

brekitomasson/laravel-model-finder
==================================

A simple trait that makes building your own custom Laravel Model Searches a lot easier.

v1.4.0(1y ago)31.5kMITPHPPHP ^8.2CI passing

Since Sep 9Pushed 1y ago1 watchersCompare

[ Source](https://github.com/BrekiTomasson/laravel-model-finder)[ Packagist](https://packagist.org/packages/brekitomasson/laravel-model-finder)[ RSS](/packages/brekitomasson-laravel-model-finder/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (7)Dependencies (4)Versions (9)Used By (0)

`BrekiTomasson\LaravelModelFinder`
==================================

[](#brekitomassonlaravelmodelfinder)

A simple trait that makes building your own custom Laravel Model Searches a lot easier and safer. It ensures that your search criteria match one, and only one, result in the table being searched, allowing you to comfortably type-hint your methods by ensuring that the result of a query will never be `null` or a `Collection`, but always an instance of the specific Model you're querying. It does this by searching for a row that **uniquely** contains the data you're looking for in one of the named columns. That's the selling point of this package; it will only return a result if that result is the **only** result for your query.

This means that instead of writing `Car::where('license_plate', 'MTU 83779')->firstOrFail()` and then worrying about whether your `license_plate` column is unique or not, you can write `CarFinder::find('MTU 83779')`, and it will return a result only if it is the only row in the entire table that has that particular value. And since you can define multiple columns for it to search through, `CarFinder::find('1HGBH41JXMN109186')` might return a result if you have a `vim_number` column in your `Car` model.

To speed things up, the package also leverages Laravel's Cache implementation, storing all results in the cache for 24 hours, meaning only the first `UserFinder::find('person@domain.com')` call of the day will be hitting your database, with the rest being served from cache.

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

[](#installation)

At the moment, no configuration files are required, although this may be introduced in future versions. To use this library, all you need to do is require the package in the root directory of your Laravel project:

```
composer require brekitomasson/laravel-model-finder
```

Usage
-----

[](#usage)

This package is used by adding one of the two traits that it offers to a class. There are two traits because there are two main ways to use this package; either by (1) building your own custom Finder-classes or by (2) adding unique search-functionality to your Models.

I recommend the first method, as it allows for a cleaner separation of concerns and is more feature-complete, but I will describe both ways below and allow you to decide for yourself. For both examples, I will be showing the functionality by using a hypothetical `Country` model, but the system works for absolutely any Laravel-powered model. For the sake of argument, assume an entry in the `Country` model looks like this:

```
{
  "id": 213,
  "alpha2": "KR",
  "alpha3": "KOR",
  "name": "The Republic of Korea",
  "numeric": 410,
  "short_name": "South Korea"
}
```

### Method 1: Building Your Own Finder-Class

[](#method-1-building-your-own-finder-class)

Let's create a new `CountryFinder` in the `App\Tools` namespace. It doesn't need to extend or implement any other classes, but it needs to `use` the `CanFindModelEntries` trait. Depending on your IDE, this will then inform you that you have a method stub for the static method `find` that needs to be implemented, so let's do that.

Now, since PHP doesn't natively support abstract keywords in their Traits (Seriously, PHP; what's up with that?), we have to implement the next two things manually. They are the `protected static array $queryKeys` and the `protected static Model|string $queryModel`. You populate these with:

- `protected static array $queryKeys`: An array containing the list of attributes to be searched, and
- `protected static Model|string $queryModel`: the FQN (including `::class`) of the Model being searched.

At this point, the file should look something like this:

```