Many models allow you to request additional information from relational models by using the
with method. This parameter is available on all models and applies to the response of that model only. Model relations can be expanded in two ways.
In many cases, an object contains the ID of a related object in its response properties. For example, a price has an associated product ID. Those models can be queried together in one call. ID fields that can be expanded into models are noted in this documentation with the "expandable" label. Here's an example:
$prices = \SureCart\Models\Price::with([ 'product' ])->paginate(['page'=> 1]);
$promo = \SureCart\Models\Promotion::with([ 'coupon' ])->find('8ba8d60f-5277-4e6b-807c-dee8166446d5');
In some cases, such as a list of all prices for a product, there are available fields that are not included in responses by default. You can request these fields as an expanded response by using the
with method. Fields that can be included in an expanded response are noted in this documentation with the "expandable" label.
$products = \SureCart\Models\Product::with([ 'prices' ])->paginate(['page'=> 1]);
You can expand recursively by specifying nested fields after a dot (.). For example, requesting
customer.billing_address on an order will expand the customer and the customer's billing address.
$orders = \SureCart\Models\Order::with([ 'customer.billing_address' ])->paginate(['page'=> 1]);
You can use the
with method on any endpoint that returns expandable fields, including list, create, and update endpoints.
Expanding list requests are plural, but expanding objects within a list is singular. For example, if you wanted to retrieve an order's line items and each line item's price, you would pass
line_item.price as expand parameters.
$orders = \SureCart\Models\Order::with( [ 'line_items', 'line_item.price', 'price.product' ] )->paginate( [ 'page' => 1 ] );
$charges = \SureCart\Models\Charge::where([ 'customer_ids' => [ $customer_id ], ])->with( [ 'order', 'order.line_items', 'line_item.price', 'price.product', 'subscription', 'subscription.subscription_items', 'subscription_item.price' ] )->get();
You can expand multiple objects at once by identifying multiple items in the
with array. Expansions have a maximum depth of two levels, and you can expand up to 10 objects.
This is not only limited to
paginate. You can use this on
update requests as well. This will allow you to create or update a model and fetch its relations all in one request.
\SureCart\Models\Price::create([ 'name' => 'New Price', 'amount' => 5000, // $50.00 'currency' => 'usd', 'product' => '8ba8d60f-5277-4e6b-807c-dee8166446d5', ])->with([ 'product' ])->save();
Updated 2 months ago