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:
|
1 2 3 |
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.
|
1 2 3 4 5 |
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.
|
1 |
interface Product {} |
Bagisto Contracts act as the abstraction that repositories and services depend on.
2. Model
Provides the actual Eloquent implementation.
|
1 2 3 4 |
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.
|
1 2 3 4 |
<?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:
|
1 2 3 4 |
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.
Be the first to comment.