README

To populate drowdowns (or other ways of reference) in an SPA form a separate endpoint can be used to create the array of name/value pairs. This package allows you to automatically create routes for your Models and Enums to make them referable in your Laravel backed SPA frontend.

Installation

You can install the package via composer:

composer require perfect-drive/referable

You can publish the config file with:

php artisan vendor:publish --tag="referable-config"

This is the contents of the published config file:

return [
    /*
     * The directories to search for Referable classes.
     */
    'directories' => [
        app_path('Enums'),
        app_path('Models'),
    ],

    /*
     * The middleware array to use for the Referable routes.
     */
    'middleware' => ['api', 'auth:sanctum'],

    /*
     * The key name to use for the referable key in the json response.
     */
    'key_name' => 'value',

    /*
     * The value name to use for the referable value in the json response.
     */
    'value_name' => 'title',

    /*
     * The base url for the referable routes.
     */
    'base_url' => 'spa/referable/',
];

Usage

On a Model:

<?php

declare(strict_types=1);

namespace App\Models;

use App\Interfaces\ReferableInterface;
use App\Traits\ReferableModel;
use Illuminate\Database\Eloquent\Model;

class ProjectType extends Model implements ReferableInterface
{
    use ReferableModel;

This will register the following route:

GET /spa/referable/project_type

On an Enum:

<?php

declare(strict_types=1);

namespace App\Enums\User;

use App\Interfaces\ReferableInterface;
use App\Traits\ReferableEnum;

enum UserStatus: string implements ReferableInterface
{
    use ReferableEnum;

This will register the following route:

GET /spa/referable/user_status

Model Scopes

The 'ReferableScope' attribute can be used to mark a custom scope (on a Model) to filter the referable items and create an additional route for it.

Both the legacy scopeActive naming convention and Laravel's native #[Scope] attribute are supported.

use PerfectDrive\Referable\Attributes\ReferableScope;

// Legacy naming convention
#[ReferableScope]
public function scopeActive(Builder $query): Builder
{
    return $query->where('active', true);
}

use Illuminate\Database\Eloquent\Attributes\Scope;
use PerfectDrive\Referable\Attributes\ReferableScope;

// Laravel's #[Scope] attribute (Laravel 12+)
#[Scope]
#[ReferableScope]
public function active(Builder $query): Builder
{
    return $query->where('active', true);
}

Either of these will register the following route:

GET /spa/referable/project_type/active

Enum Scopes

You can use the 'ReferableScope' attribute to define a custom scope method (on an Enum) to filter the referable items and create an additional route for it.

#[ReferableScope]
public function active(): bool
{
    return in_array($this, [
        self::FIRST,
        self::SECOND,
    ], true);
}

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Security Vulnerabilities

If you discover any security related issues, please email carl.klein@perfect-drive.nl.

Credits

• Carl Klein

License

The MIT License (MIT). Please see License File for more information.