Reference Field Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require baks-dev/reference-field
   

   Publish the package assets (if needed) via:

   php artisan vendor:publish --provider="BaksDev\ReferenceField\ReferenceFieldServiceProvider" --tag="public"
   

2. First Use Case: Basic Reference Field Register a reference field in a Laravel Form Request or Form class:

   use BaksDev\ReferenceField\ReferenceField;
   
   public function rules()
   {
       return [
           'user_id' => [
               new ReferenceField('users', 'id', 'name', 'User ID'),
               'required',
           ],
       ];
   }
   

   • Parameters:
     • model (string): Eloquent model name (e.g., 'users').
     • id_column (string): Primary key column (default: 'id').
     • display_column (string): Column for display (e.g., 'name').
     • label (string): Human-readable label (optional).

3. Blade Integration Use the @referenceField directive in your Blade template:

   @referenceField('user_id', 'users', 'id', 'name', 'Select User')
   

   • Attributes:
     • name: Input field name.
     • model: Eloquent model.
     • id_column: Primary key (optional).
     • display_column: Display column (optional).
     • label: Label text (optional).

4. Configuration Check config/reference-field.php for default settings (e.g., query scopes, placeholder text).

Implementation Patterns

Common Workflows

1. Dynamic Reference Fields in Forms

• Use Case: Forms with conditional reference fields (e.g., role-based access).
• Pattern:

  public function buildForm(array $data, Form $form)
  {
      if (auth()->user()->isAdmin()) {
          $form->add('department_id', ReferenceField::make('departments', 'id', 'name'));
      }
  }
  

2. Custom Query Scopes

• Use Case: Filter reference field options (e.g., active users only).
• Pattern:

  // In config/reference-field.php
  'scopes' => [
      'users' => ['active' => true],
  ],
  

  Or dynamically:

  $field = new ReferenceField('users', 'id', 'name');
  $field->setScope('active', true);
  

3. Integration with Laravel Nova

• Use Case: Extend Nova toolbars or detail views.
• Pattern:

  use BaksDev\ReferenceField\Nova\ReferenceField;
  
  public function fields(Request $request)
  {
      return [
          new ReferenceField($request, 'user_id', 'users', 'id', 'name', 'User'),
      ];
  }
  

4. Validation + Reference Field

• Use Case: Ensure referenced records exist.
• Pattern:

  $validator = Validator::make($data, [
      'user_id' => [
          new ReferenceField('users', 'id', 'name'),
          'exists:users,id',
      ],
  ]);
  

5. API Responses

• Use Case: Return formatted reference data in APIs.
• Pattern:

  use BaksDev\ReferenceField\ReferenceField;
  
  $field = new ReferenceField('roles', 'id', 'name');
  return response()->json(['roles' => $field->getOptions()]);
  

Integration Tips

1. Laravel Livewire

   • Use the @referenceField directive in Livewire components:

     <livewire:user-form>
         @referenceField('user_id', 'users', 'id', 'name', 'User')
     </livewire:user-form>
     

2. Inertia.js

   • Pass reference field data via props:

     return Inertia::render('Users/Edit', [
         'user' => $user,
         'referenceFields' => [
             'user_id' => (new ReferenceField('users', 'id', 'name'))->getOptions(),
         ],
     ]);
     

3. Custom Display Logic

   • Extend the ReferenceField class to modify display behavior:

     class CustomReferenceField extends ReferenceField
     {
         public function getDisplayValue($value)
         {
             return "Custom: " . parent::getDisplayValue($value);
         }
     }
     

4. Localization

   • Override labels/placeholders in language files:

     // resources/lang/en/reference-field.php
     return [
         'placeholders' => [
             'users' => 'Select a user...',
         ],
     ];
     

Gotchas and Tips

Pitfalls

1. Model Not Found

   • Issue: Class 'App\Models\Users' not found (Laravel's auto-naming).
   • Fix: Use fully qualified model names:

     new ReferenceField('App\Models\User', 'id', 'name')
     

2. Query Performance

   • Issue: Slow loading due to large datasets.
   • Fix: Add scopes or limit results:

     $field = new ReferenceField('posts', 'id', 'title');
     $field->setLimit(100);
     

3. Caching Stale Data

   • Issue: Reference field options not updating after model changes.
   • Fix: Clear cache or use ->fresh():

     $field->setModel(Model::query()->fresh());
     

4. Blade Directive Conflicts

   • Issue: @referenceField not working due to namespace collisions.
   • Fix: Register the directive manually in AppServiceProvider:

     Blade::directive('referenceField', function ($expression) {
         return "<?php echo BaksDev\ReferenceField\Blade::referenceField($expression); ?>";
     });
     

Debugging

1. Log Query Enable SQL logging to debug queries:

   $field = new ReferenceField('orders', 'id', 'customer_name');
   \DB::enableQueryLog();
   $options = $field->getOptions();
   \Log::info(collect(\DB::getQueryLog())->pluck('query'));
   

2. Validate Model Binding Ensure the model is properly bound:

   $field = new ReferenceField('App\Models\User', 'id', 'email');
   if (!$field->isValid($request->user_id)) {
       // Handle invalid reference
   }
   

Configuration Quirks

1. Default Placeholder

   • Override globally in config/reference-field.php:

     'placeholders' => [
         'default' => 'Select an option...',
     ],
     

2. Empty State Handling

   • Customize empty state behavior:

     $field = new ReferenceField('products', 'id', 'name');
     $field->setEmptyOption('All Products', null);
     

3. Dynamic Model Binding

   • Bind models dynamically (e.g., based on user role):

     $model = auth()->user()->canAccess('admin') ? 'AdminUser' : 'User';
     $field = new ReferenceField($model, 'id', 'name');
     

Extension Points

1. Custom Option Formatter

   • Extend the ReferenceField class to modify option formatting:

     class FormattedReferenceField extends ReferenceField
     {
         public function getOptions()
         {
             $options = parent::getOptions();
             return collect($options)->mapWithKeys(function ($value, $key) {
                 return [$key => "<strong>{$value}</strong>"];
             });
         }
     }
     

2. Add Search Functionality

   • Implement AJAX search via JavaScript:

     document.querySelectorAll('[data-reference-field]').forEach(el => {
         el.addEventListener('input', (e) => {
             fetch(`/api/search?field=${el.dataset.field}&query=${e.target.value}`)
                 .then(response => response.json())
                 .then(data => {
                     // Update dropdown options
                 });
         });
     });
     

3. Hooks for Pre/Post Processing

   • Use events to intercept field logic:

     // In AppServiceProvider@boot()
     event(new \BaksDev\ReferenceField\Events\BuildingReferenceField(
         $field, $model, $idColumn, $displayColumn
     ));
     

4. Custom Storage Logic

   • Override how values are stored/retrieved:

     $field = new ReferenceField('tags', 'id', 'name');
     $field->setStoreFormat(fn ($value) => strtolower($value));
     $field->setRetrieveFormat(fn ($value) => ucfirst($value));