Creating Order Items By Definition - axiom82/PHP-Contract GitHub Wiki

In e-commerce applications, when customers begin selecting items for their purchase, it is necessary to create orderItem records in the database. An orderItem is a relational database record where an item is associated with an order. For each order, there many be one or more orderItem records, reflecting the user’s purchase items for an order.

When creating orderItem records from within the modeling of the application, you will typically find an order model class with a createOrderItem class method. The parameters for creating the orderItem should be the ID of the order for which the orderItem is being created $orderId, the ID of the item for which the orderItem is being created, and any additional data relevant to the order item $orderItemData.

There are a few data types and values at play here, and it is important to ensure the data coming through accurately describes the scenario for a working order item. Here is a Contract that ensures that the data is a reflection of the developer’s intent for the method’s operation.

<?php

class Order_Model {
	
	public function createOrderItem($orderId, $itemId, $orderItemData = array('quantity' => 1)){
	
		$contract = new Contract();
		$contract->term('orderId')->id();
		$contract->term('itemId')->id();
		$contract->term('itemData')->arraylist()->element('quantity')->required()->natural();
		$contract->metOrThrow();
		
		$order = $this->getOrder($orderId);
		$contract->term('order', $order)->row()->metOrThrow();
		
		$item = $this->getItem($itemId);
		$contract->term('item', $item)->row()->metOrThrow();
		
		$orderItemData = $contract->data('orderItemData');
		
		$affected = $this->_db->insert('order_item', array_merge($orderItemData, array(
			'order_id'		=> $orderId,
			'item_id'		=> $itemId,
			'price'			=> $item['price']
		)));
		
		$orderItemId = ($affected) ? $this->_db->lastInsertId() : null;
		
		return $orderItemId;
	
	}
	
}

?>

The code above begins by starting a Contract object. The Contract defines terms for the arguments including defining that the $orderId and $itemId must be ID types, as well as defining that the $orderItemData is an array containing a quantity element that is a natural number (1, 2, 3, …). What’s more is the requirement that the $orderId and $itemId values reflect existing rows in the order and item tables. The Contract also defines custom terms for $order and $item to ensure that these rows exist prior to working on their behalf.

Once all of the Contract Terms are defined and the Contract is met, the filtered $orderItemData is then gotten, and the database query is executed.

This is a fail-safe operation. Because the Contract ensures that all data is present and valid at each step of the preliminary process, the room for failure is null. If failure occurs, meaning that the Contract throws an exception, the exception must be caught in order to resume the application. Once caught, the exception can be used to perform error routines, such as error logging or printing messages to the user.