Drop-in model references.
Switch branches/tags
Nothing to show
Clone or download
Latest commit c938e95 Oct 6, 2017
Failed to load latest commit information.
config Work in progress Oct 5, 2017
database/migrations Work in progress Oct 6, 2017
src Work in progress Oct 6, 2017
tests Work in progress Oct 6, 2017
.gitignore Initial commit Oct 3, 2017
.travis.yml Shorten statement Oct 6, 2017
LICENSE Create LICENSE Oct 6, 2017
README.md Work in progress Oct 6, 2017
composer.json Work in progress Oct 6, 2017
composer.lock Work in progress Oct 6, 2017
phpunit.xml.dist More things Oct 4, 2017


Drop-in Model References

Build Status

This Laravel >=5.5 package provides a quick and simple way to add unique references to models that can be resolved via route model binding. You usually don't want to expose your primary keys to the client, and without a unique reference such as a username or slug, you can't quickly build a RESTful API. With this package you can give your models a unique reference and instantly start using it in your routes.

Here are a few short examples of what you can do:

// Simply add the binding to your route
Route::get('/api/customers/{ref}', function (Customer $customer) {

// Then just use the model's reference in your request
GET /api/customers/cus_tKCulsB67hty


You can install this package via composer using this command:

composer require jameslkingsley/laravel-references

If you're using Laravel 5.5 or greater this package will be auto-discovered, however if you're using anything lower than 5.5 you will need to register it the old way:

Next, you must install the service provider in config/app.php:

'providers' => [

Now publish the config:

php artisan vendor:publish --provider="Kingsley\References\ReferencesServiceProvider"

This is the contents of the published config file:

return [
     * Name of the database table that
     * will store model references.
    'table_name' => 'references',

     * Name of the route model binding.
     * Eg. /api/customers/{ref}
    'binding_name' => 'ref',

     * Whether the reference hash should
     * prefix the shortened model type.
     * Eg. App\Customer -> cus_tKCulsB67hty
    'prefix' => false,

Now just run the migrations!

php artisan migrate


Choose the model that you want to make referenceable. In this example I'll choose Customer. We'll import the trait and use it in the class.

namespace App;

use Kingsley\References\Referenceable;
use Illuminate\Database\Eloquent\Model;

class Customer extends Model
    use Referenceable;

Now setup your routes to use the binding. Whether you're using a controller or an anonymous function, just type-hint the model class in the arguments to resolve the reference.

Route::get('/api/customer/{ref}', function (Customer $customer) {
    return $customer;

When submitting AJAX requests from the client, you can use the ref attribute that is appended to the model.



If you want to prefix references, just set the prefix option to true in the config. By default it will use the first three characters of the class' basename.

App\Customer -> cus_tKCulsB67hty

Alternatively you can explicitly set the prefix for the model by setting the following. Note that if you set it to null it won't have a prefix, even if your prefix config option is set to true.

class Customer extends Model
    use Referenceable;

    protected $referencePrefix = 'customer';