The `whenLoaded()` method in Laravel is specifically designed to work with Eloquent model relationships. It conditionally includes relationship data in API resource responses only if the relationship has been eager loaded on the Eloquent model. This method helps avoid unnecessary database queries and keeps API responses lean by only including related data when it is actually loaded.
Usage Context of `whenLoaded()`
- Eloquent Models and Relationships: `whenLoaded()` checks if a relationship on an Eloquent model has been loaded using methods like `with()` or `load()`. If the relationship is loaded, it returns the related data; otherwise, it returns nothing or a default value. This behavior is tightly coupled with Eloquent's internal method `relationLoaded()` which determines if the relationship data is available on the model instance[1][7][8].
- API Resources: It is commonly used inside Laravel API resource classes to conditionally include related resources or collections based on whether the relationships were eager loaded, improving performance and avoiding the N+1 query problem[1][8].
Can `whenLoaded()` Be Used with Third-Party Libraries?
- No Direct Support Outside Eloquent Models: Since `whenLoaded()` relies on the Eloquent model's internal state to check if a relationship is loaded (`relationLoaded()` method), it is inherently designed for Eloquent models and their relationships. Third-party libraries that do not extend or mimic Eloquent models and their relationship loading mechanisms cannot directly use `whenLoaded()`.
- Workarounds: If a third-party library returns objects or collections that are not Eloquent models, you cannot use `whenLoaded()` as-is. You would need to implement similar conditional logic manually or wrap those objects in a custom resource that mimics the behavior. Alternatively, you could manually check if the related data is present before including it in the response.
Summary
- `whenLoaded()` is built to work exclusively with Eloquent models and their loaded relationships.
- It depends on Eloquent's internal relationship loading state, so it cannot be used directly with third-party libraries that do not use Eloquent models.
- To conditionally include related data from third-party sources, you must implement your own conditional checks or resource wrappers.
This makes `whenLoaded()` a powerful tool for optimizing Laravel API responses but limited to the Eloquent ORM context[1][7][8].
Citations:
[1] https://henestrosa.dev/blog/how-to-use-whenloaded-in-laravel-api-resources
[2] https://laracasts.com/discuss/channels/laravel/api-resource-using-count-with-whenloaded
[3] https://laravel.com/docs/12.x/eloquent-resources
[4] https://stackoverflow.com/questions/76828050/how-to-get-a-single-field-from-a-laravel-whenloaded-resource
[5] https://www.youtube.com/watch?v=Ls7m14eCaSU
[6] https://stackoverflow.com/questions/66675594/can-i-use-with-instead-load-laravel-eloquent
[7] https://laraveldaily.com/post/laravel-api-resources-relations-when-methods
[8] https://laravel-news.com/whenloaded