Default Records Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require neuecommerce/default-records
   

   Publish the config (optional):

   php artisan vendor:publish --provider="Neuecommerce\DefaultRecords\DefaultRecordsServiceProvider"
   

2. Basic Usage Define a default record for a model (e.g., User):

   use Neuecommerce\DefaultRecords\HasDefaultRecords;
   
   class User extends Model
   {
       use HasDefaultRecords;
   }
   

   Add a default record via migration or seeder:

   User::setDefaultRecord(['name' => 'Guest', 'email' => 'default@example.com']);
   

3. First Use Case Fetch the default record when no other matches exist:

   $defaultUser = User::findOrDefault(999); // Returns default if ID 999 doesn't exist
   

Implementation Patterns

Core Workflows

1. Default Record Resolution

   • Use findOrDefault() to fall back to defaults:

     $user = User::findOrDefault($id);
     

   • Chain with other query methods:

     $activeDefault = User::whereActive(true)->findOrDefault($id);
     

2. Dynamic Defaults

   • Override defaults per scope (e.g., for API vs. web):

     User::setDefaultRecord(['name' => 'API Guest'], 'api');
     $default = User::findOrDefault($id, 'api');
     

3. Model Events

   • Hook into retrieved events to log default usage:

     User::retrieved(function ($user) {
         if ($user->isDefault()) {
             Log::info("Default record used for ID: {$user->id}");
         }
     });
     

Integration Tips

• Soft Deletes: Works seamlessly with SoftDeletes trait.
• Scopes: Combine with custom scopes:

  class User extends Model
  {
      public function scopeVerified($query) {
          return $query->where('verified', true);
      }
  }
  // Usage:
  $user = User::verified()->findOrDefault($id);
  

• APIs: Useful for "guest" or "anonymous" user placeholders in endpoints.

Gotchas and Tips

Pitfalls

1. Overwriting Defaults

   • Default records are not automatically synced if the underlying model changes. Manually update them via:

     User::setDefaultRecord($newAttributes);
     

   • Tip: Use a seeder to initialize defaults during deployment.

2. Performance

   • findOrDefault() triggers two queries (find + default fetch). Cache defaults if used frequently:

     $default = cache()->remember("user.default", now()->addHours(1), fn() => User::default());
     

3. Multiple Defaults

   • Only one default per model is active at a time (configurable via default_records.default_scope). Use named scopes ('api', 'web') to manage multiple defaults.

Debugging

• Check for Defaults:

  User::default(); // Returns the active default record.
  

• Verify Scope:

  User::getDefaultScope(); // Returns the current scope (e.g., 'default').
  

Extension Points

1. Custom Default Logic Override the getDefaultRecord() method in your model:

   public function getDefaultRecord()
   {
       return $this->where('is_system', true)->first();
   }
   

2. Event Hooks Listen for default.record.retrieved to customize behavior:

   event(new DefaultRecordRetrieved(User::class, $defaultUser));
   

3. Config Overrides Modify config/default-records.php to:

   • Change the default scope name.
   • Disable automatic default checks.