Understanding Contracts in Bagisto: The Foundation Behind Model Overrides

ashif.322

14 July 2026

Introduction

Bagisto Contracts are one of the core concepts behind Bagisto’s extensible architecture.

If you’ve explored the Bagisto source code, you’ve probably noticed that every major entity, such as Product, Category, or Customer, contains three files:

Contracts/Product.php 
Models/Product.php 
Models/ProductProxy.php

Contracts/Product.php

Models/Product.php

Models/ProductProxy.php

Most developers immediately understand the Model, but the purpose of the Contract and Proxy is often less obvious.

We’ve already covered the Proxy Pattern in detail in our previous article:

Bagisto Proxy Pattern for Model Override
https://bagisto.com/en/bagisto-proxy-pattern-model-override/

In this article, we’ll focus on the missing piece of the puzzle.

The Contract—and see how Bagisto combines Laravel Contracts, Concord, and Proxies to create an upgrade-safe architecture.

Laravel’s Approach to Bagisto Contracts

Laravel encourages developers to depend on abstractions rather than concrete implementations.

Instead of tightly coupling your application to a specific class.

Laravel allows you to depend on an interface that can later be resolved into the appropriate implementation.

Bagisto follows the same principle for its core models.

Instead of directly depending on the Product model, repository depend on the Product Contract.

use Webkul\Product\Contracts\Product;
public function model(): string
{
    return Product::class;
}

use Webkul\Product\Contracts\Product;

public function model(): string

{

return Product::class;

}

The repository doesn’t know which Product model it will receive. It only knows it needs something that satisfies the Product contract.

Bagisto Contracts vs Laravel model resolution architecture

The Three Components of Bagisto Contracts

Each Bagisto model consists of three independent components.

1. Contract

Defines what the model represents.

interface Product {}

1	interface Product {}

Bagisto Contracts act as the abstraction that repositories and services depend on.

2. Model

Provides the actual Eloquent implementation.

class Product extends Model implements ProductContract
{
    //
}

class Product extends Model implements ProductContract

{

}

This class contains relationships, scopes, business logic, and database interaction.

3. Proxy

The Proxy is mainly used by Eloquent relationships where Laravel expects a model class instead of an interface.

<?php
namespace Webkul\Product\Models;
use Konekt\Concord\Proxies\ModelProxy;
class ProductProxy extends ModelProxy {}

<?php

namespace Webkul\Product\Models;

use Konekt\Concord\Proxies\ModelProxy;

class ProductProxy extends ModelProxy {}

Since we’ve already covered the Proxy Pattern in detail, we won’t dive deeper here. You can read the complete explanation in our previous blog.

How Bagisto Resolves the Contract

Bagisto Contracts cannot interact with the database directly.

Instead, Konekt Concord maintains the mapping between a Contract and its registered model.

The resolution flow looks like this:

Bagisto Contracts resolved by Concord

Whenever a repository requests the Product Contract, Concord returns the currently registered Product model.

Why Doesn’t the Repository Use ProductProxy?

This is one of the most common questions.

Repositories work with Contracts, not Proxies.

The reason is simple:

Contracts provide an abstraction that Concord can resolve.
Proxies exist primarily because Eloquent relationships require a model class.

For example:

public function product()
{
    return $this->belongsTo(ProductProxy::class);
}

public function product()

{

return $this->belongsTo(ProductProxy::class);

}

Bagisto Contracts and Proxies working together

The repository and the relationship solve two different problems, which is why they use different components.

Why Bagisto Contracts Matter

This separation is one of the biggest advantages of Contracts.

If you create your own Product model and register it with Concord.

Every repository automatically begins using your implementation without requiring changes to the framework.

Similarly, relationships continue to work because they resolve the registered model through the Proxy.

The result is a flexible, upgrade-safe architecture that allows developers to customize core models without editing vendor files.

Conclusion

Bagisto’s architecture is built around three simple ideas:

Contracts define the abstraction.
Models provide the implementation.
Proxies support Eloquent relationships and model resolution.

Together with Concord, Bagisto Contracts allow developers to customize core models without modifying vendor files.