What is `withDefault()` and how to use it?

Table Of Contents

• The Null Reference Problem
• Laravel withDefault() Implementation
• Advanced withDefault() Patterns

The Null Reference Problem

Your app crashes with "Trying to get property of non-object" when a user has no profile or a post has no category. The withDefault() method eliminates these errors:

// CRASHES when user has no profile
$user = User::find(1);
echo $user->profile->bio; // Error: Trying to get property 'bio' of null

// SAFE - Returns default profile object
class User extends Model
{
    public function profile()
    {
        return $this->hasOne(Profile::class)->withDefault([
            'bio' => 'No bio available',
            'avatar' => '/images/default-avatar.png',
            'location' => 'Unknown'
        ]);
    }
}

$user = User::find(1);
echo $user->profile->bio; // "No bio available" instead of error

Laravel withDefault() Implementation

Configure default values for different relationship scenarios:

// Simple default with static values
class Post extends Model
{
    public function category()
    {
        return $this->belongsTo(Category::class)->withDefault([
            'name' => 'Uncategorized',
            'slug' => 'uncategorized',
            'color' => '#gray'
        ]);
    }
}

// Dynamic defaults using closure
class Order extends Model
{
    public function customer()
    {
        return $this->belongsTo(User::class, 'user_id')->withDefault(function ($user, $order) {
            return [
                'name' => 'Guest Customer',
                'email' => 'guest@example.com',
                'id' => 0,
                'created_at' => $order->created_at ?? now()
            ];
        });
    }
}

// Default object from existing model
class Product extends Model
{
    public function category()
    {
        return $this->belongsTo(Category::class)->withDefault(
            Category::where('slug', 'general')->first() ?? [
                'name' => 'General',
                'slug' => 'general'
            ]
        );
    }
}

// HasOne relationship with defaults
class User extends Model
{
    public function settings()
    {
        return $this->hasOne(UserSettings::class)->withDefault([
            'theme' => 'light',
            'notifications' => true,
            'timezone' => 'UTC',
            'language' => 'en'
        ]);
    }
}

Advanced withDefault() Patterns

Handle complex default scenarios and business logic:

// E-commerce: Default shipping address
class User extends Model
{
    public function primaryAddress()
    {
        return $this->hasOne(Address::class)
            ->where('is_primary', true)
            ->withDefault(function ($address, $user) {
                return [
                    'street' => '',
                    'city' => '',
                    'state' => '',
                    'country' => config('app.default_country', 'US'),
                    'postal_code' => '',
                    'is_primary' => true,
                    'user_id' => $user->id ?? 0
                ];
            });
    }
}

// Blog: Author with default guest author
class Post extends Model
{
    public function author()
    {
        return $this->belongsTo(User::class, 'user_id')->withDefault([
            'name' => 'Guest Author',
            'email' => 'guest@blog.com',
            'avatar' => '/images/guest-avatar.png',
            'bio' => 'This post was written by a guest author.'
        ]);
    }
    
    // Use in Blade templates safely
    // {{ $post->author->name }} - Never null
}

// Company hierarchy with default manager
class Employee extends Model
{
    public function manager()
    {
        return $this->belongsTo(Employee::class, 'manager_id')->withDefault(function ($manager, $employee) {
            // Create virtual CEO object for top-level employees
            return [
                'id' => 0,
                'name' => 'CEO',
                'email' => 'ceo@company.com',
                'department' => 'Executive',
                'title' => 'Chief Executive Officer'
            ];
        });
    }
}

// Configuration with environment-based defaults
class Application extends Model
{
    public function theme()
    {
        return $this->belongsTo(Theme::class)->withDefault([
            'name' => config('app.default_theme', 'Default'),
            'primary_color' => config('app.primary_color', '#3490dc'),
            'secondary_color' => config('app.secondary_color', '#6cb2eb'),
            'dark_mode' => false
        ]);
    }
}

// Conditional defaults based on model state
class Invoice extends Model
{
    public function paymentMethod()
    {
        return $this->belongsTo(PaymentMethod::class)->withDefault(function ($method, $invoice) {
            // Different defaults based on invoice amount
            if ($invoice->total > 1000) {
                return [
                    'name' => 'Bank Transfer',
                    'type' => 'bank_transfer',
                    'fee_percentage' => 0
                ];
            }
            
            return [
                'name' => 'Credit Card',
                'type' => 'credit_card', 
                'fee_percentage' => 2.9
            ];
        });
    }
}

// Performance consideration: Avoid N+1 with defaults
$posts = Post::with('category')->get(); // Eager load even for defaults

// Blade template usage
@foreach($posts as $post)
    <div class="post">
        <h2>{{ $post->title }}</h2>
        <span class="category" style="color: {{ $post->category->color }}">
            {{ $post->category->name }}
        </span>
    </div>
@endforeach

// API response with guaranteed structure
public function show(Post $post)
{
    return response()->json([
        'id' => $post->id,
        'title' => $post->title,
        'category' => [
            'name' => $post->category->name,     // Never null
            'slug' => $post->category->slug,     // Never null
            'color' => $post->category->color    // Never null
        ],
        'author' => [
            'name' => $post->author->name,       // Never null
            'avatar' => $post->author->avatar    // Never null
        ]
    ]);
}

Use withDefault() on belongsTo and hasOne relationships to prevent null reference errors in templates and APIs. The default object isn't saved to the database - it's just a virtual object that prevents crashes. This is especially useful for optional relationships that might not exist for all records.

Related: Laravel Collections: Beyond Basic Array Operations | Laravel Events and Listeners: Building Decoupled Applications | Building Multi-tenant Applications with Laravel: A Comprehensive Guide