LemonStand - Shop

Shop_Product

The Shop_Product class represents a product in the online store. The class has methods for accessing a product name, description and other parameters. You may need to access product parameters when you building the Product page of your store, or when you display a list of products.

Parent class: Db_ActiveRecord

Class fields

$allow_pre_order - indicates whether the product inventory tracking settings allow pre-ordering. You can use this field value for detecting whether the Add to Cart button should be visible on the product details page. Example:
```
<? if (!$product->is_out_of_stock() || $product->allow_pre_order): ?>
   ... Add to Cart button ...      
<? endif ?>
```
$depth – product depth (dimension)
$name – the product name
$description – product description in HTML format
$enabled - determines whether the product is enabled
$disable_completely - determines whether the product and all its grouped products are disabled (overrides the $enabled property)
$short_description – product description as plain text. Please use the h function to output the short description
$category_list – a list of categories the product belongs to. An object of Db_DataCollection class. Each element in the collection is an object of Shop_Category class.
$grouped_menu_label – a label for the grouped products option list. A value of this field is specified in the Attribute Name field of the product form, on the Grouped tab.
$grouped_products – a list of grouped products associated with the product. Use this list for displaying a list of grouped products on the product page.
$grouped_option_desc – a description of the product in the list of grouped products
$height – height of the product (dimension)
$weight – product weight
$width – product width (dimension)
$files – a list of files associated with the product. Files can be associated only with downloadable files. An object of the Db_DataCollection class. Each element of the collection is an object of the Shop_ProductFile class.
$id – product identifier in the database
$in_stock - indicates how many units of the products are available in stock. See also the in_stock_grouped() method below.

$expected_availability_date - the date of the product expected availability. You can display this field on the website using the following simple code:

<? if ($product->is_out_of_stock()): ?>
    <p>
        <strong>This product is temporarily unavailable</strong>
        <? if ($product->expected_availability_date): ?>  
            <br/>The expected availability date is <?= $product->displayField('expected_availability_date') ?>
        <? endif ?>
    </p>
<? endif ?>

$images - a collection of the product images. Each element in the collection is an object of the Db_File class.
$meta_description – a description to output on the product page in the HTML META element
$meta_keywords – keywords to list on the product page in the HTML META element
$related_products – a list of related products, an object of the Db_DataCollection class. Each element of the collection is an object of Shop_Product class. The collection contains all enabled and available related products, but does not take into account product visibility filters (customer group filter, etc). If you want to obtain a list of related products with visibility filters applied, please use the list_related_products() method described in the Methods section below.
$sku – the product SKU
$url_name - a product URL name. The shop:product action uses this field to load a product by an URL parameter. Usually you don't need to access the field directly. Use the page_url method for creating links to product pages.
$manufacturer - the product manufacturer. An object of the Shop_Manufacturer class. This field can be NULL if a manufacturer was not selected in the product configuration form.
$rating_approved - returns a rating based on approved reviews. This and the $rating_all fields return a value in the 0 - 5 range. Value 0 means that there is no rating information available for the product. Values have increment of 0.5 i.e.: 1, 1.5, 2, 2.5, 3, 3.5, 4. 4,5, 5. There is no 0.5 value, because the minimal rating a visitor can set is 1.
$rating_all - returns a rating based on all reviews, included non-approved.
$rating_review_num - number of approved reviews with specified rating. You can use this filed for displaying the "Based on 8 reviews" text near the product rating value.
$rating_all_review_num - number of all reviews with specified rating. You can use this filed for displaying the "Based on 8 reviews" text near the product rating value.
$extra_options - a collection of the product extra options. An object of the Db_DataCollection class. Each element in the collection is Shop_ExtraOption object.
$created_at - date and time when the product has been added to the database. An instance of the Phpr_DateTime class.
$product_id - identifier of a parent product for a grouped product.
$options - contains a list of product options. Please read the Displaying Product Options article for details and code examples.
$tax_class - an object of Shop_TaxClass class.
$visibility_search - determines whether product should be visible in search results. Boolean value. This field affects the find_products field behavior.
$visibility_catalog - determines whether product should be visible in the catalog. Boolean value. This field affects the Shop_Category::list_products() and Shop_CustomGroup::list_products() methods.

Class methods

is_out_of_stock() - returns TRUE if the product is out of stock
in_stock_grouped() returns the total number of items of stock of the product and all its grouped products.
is_discounted() - returns TRUE if there are catalog price rules, which affect the product price
price($quantity = 1, $customer_group_id = null) - returns a current product price. The price could depend on price tiers. The two non-required parameters can be used for evaluating the price for specific quantity (depending on the product tier price) and a customer group. If the $customer_group_id parameter is not specified, the identifier of a currently logged in customer will be used.
get_discounted_price($quantity, $customer_group_id = null) - Returns the product discounted price for the specified cart item quantity. If there are no price rules defined for the product, returns the product original price. You can use this method for displaying the product Sale Price in the catalog. Example:
```
Price: <strong><?= format_currency($product->price()) ?></strong><br/>
Sale Price: <strong><?= format_currency($product->get_discounted_price(1)) ?></strong>
```
page_url($base_url) – returns a product page URL, based on the URL passed in the parameter. Use this method to create links to products. If there is no custom page assigned to a product, the method just adds the product URL name to the base URL. So, if you pass the product string to the method, it will return strings like product/red_mug or product/apple_keyboard. For products which have a custom page assigned and no URL Name assigned, the function will return the custom page URL. For products with both a custom page and URL Name specified, the function will return the URL of the custom page plus the value of the URL Name parameter: custom_page/url_name. See the Displaying a list of products article for the usage example.
image_url($index, $width, $height, $as_jpeg = true, $params = array()) – returns a relative URL of a product image thumbnail, or NULL if an image with specified index is not found. Use this method for displaying product images. The first parameter specifies a zero-based image index. The second and third parameters are thumbnail width and height correspondingly. You can use exact integer values, or word 'auto' for automatic image resizing. The $as_jpeg parameter allows you to generate PNG images with transparency support. By default the parameter value is TRUE and the method generates a JPEG image. Pass the FALSE value to the parameter to generate a PNG image. The $params array allows to pass parameters to image processing modules (which handle the core:onProcessImage event). The following line of code outputs a thumbnail of the first product image. The thumbnail width is 100 pixels, and thumbnail height is calculated by LemonStand to keep the original aspect ratio.
```
<img src="<?= $product->image_url(0, 100, 'auto') ?>"/>
```
paginate($page_index, $records_per_page) - allows you to split a product list to pages. Returns the Phpr_Pagination class object. See the Db_ActiveRecord class for details.
get_rss($feed_name, $feed_description, $default_product_url, $record_number = 20), static. Returns a content of RSS feed representing a list of recently added products. The $default_product_url should contain an URL of a default product page (see the page_url method description above).
list_grouped_products() - returns the full list of grouped products, including this product, regardless of the products stock availability. Returns an array. Each element of the array is an object of the Shop_Product class.
list_related_products() - returns a list of enabled, visible and available products. The method returns the configured Shop_Product class. Call the find_all() method on the result object in order to obtain a collection of related products. Usage example:
```
<?
  $related_products = $product->list_related_products()->find_all();
  if ($related_products->count):
?>
  <h3>Related products</h3>
  <? $this->render_partial('shop:product_list', array('products'=>$related_products)); ?>
<? endif ?>
```
get_attribute($name) - returns an attribute value by its name. You can manage product attributes on the Attributes tab of the Create/Edit Product page.
apply_filters() - applies visibility (including catalog visibility), availability and customer group filters to a product list. Call this method before calling the find() or find_all() method. Using with method you can fetch custom product lists from the database, safely that disabled and hidden product will not be show. The example code below fetches all active products from the database:
```
<?
  $products = Shop_Product::create()->apply_filters();

  $this->render_partial('shop:product_list', array(
  'products'=>$products,
  'paginate'=>false
  ));
?>
```

order_by_price($order = 'asc') - simplifies ordering products by their current price. The following code example outputs all products sorted by price in reverse order:

<?
  $products = Shop_Product::create()->apply_filters()->order_by_price('desc');

  $this->render_partial('shop:product_list', array(
  'products'=>$products,
  'paginate'=>false
  ));
?>

list_reviews() - returns a list of approved approved reviews. Returns a collection (Db_DataCollection) of Shop_ProductReview objects.
list_all_reviews() - returns a list of all reviews, including non-approved. Returns a collection (Db_DataCollection) of Shop_ProductReview objects.
list_discounted($options = array()), static. Returns a list of discounted products, i.e. products with any catalog price rules applied on. The method returns an instance of the Shop_Product class. You can pass this value to the product list partial. To obtain a collection of products call the find_all() method on the result object. The $options array allows to specify the sort mode with the sorting key. This key should contain an array of column names. Supported sorting columns are: name, price, sku, weight, width, height, depth, created_at, rand(). You can add the 'desc' suffix to the column name to sort products in reverse order. Example:
```
$products = Shop_Product::list_discounted(array('sorting'=>array('price desc')))->limit(10)->find_all();
```
You can find more examples of the list_discounted() method usage in the Displaying products on sale article.
list_uploaded_files() - returns a list of files uploaded by a customer. Returns a collection (Db_DataCollection) of Db_File objects.
list_extra_option_groups() - returns a list of the product extra options grouped by matching group names. Returns a nested array. Each index in the result array is a group name. The array values represent extra options (Shop_ExtraOption) belonging to the group. Result example: array('Group name 1'=>array(Shop_ExtraOption, Shop_ExtraOption), 'Group name 2'=>array(Shop_ExtraOption, Shop_ExtraOption)). You can use this array for displaying extra options in groups on the product page.
find_products($query, $pagination, $page=1, $options = array()) - finds products. Parameters: $query - the search query string, $pagination - the pagination object, $page - the current page index, $options - an array containing a list of extra search options. The $options array can have the following keys:
- category_ids - an array of category identifiers to limit the result with specific categories.
- manufacturer_ids - an array of manufacturer identifiers to limit the result with specific manufacturers.
- options - an array of product options as a name-value list. Example: array('color'=>'black')
- attributes - an array of product attributes as a name-value list. Example: array('paper format'=>'A4'). If your products can have multiple attributes with a same name and you want to search by multiple attribute values, you can specify the attribute value as array: array('paper format'=>array('A4', 'A5')) - the function will find products with the paper format attribute having value of A4 or A5.
- min_price - minimum product price
- max_price - maximum product price
- sorting - the product sorting expression, string. The following values are supported: relevance, name, price, created_at, product_rating, product_rating_all. The relevance value is the default sorting option. The product_rating value corresponds to the approved product rating, and the product_rating_all value corresponds to the full product rating (approved and not approved). All options (except the relevance) support the sorting direction expression - asc and desc, so you can use values like "price desc".
Usage example:
```
// Create the pagination object, 10 records per page
$pagination = new Phpr_Pagination(10); 

// Load the current page index from the URL
$current_page = $this->request_param(0, 1);

$query = 'laptop';
$options = array();
$options['attributes'] = array('CPU'=>'2.33');
$options['options'] = array('color'=>'black');

$products = Shop_Product::find_products($query, $pagination, $current_page, $options);
```
Function returns a collection (Db_DataCollection) of Shop_Product objects. You can also learn about creating a search page.
By default the find_products() method uses soft comparison in the options and attributes search. This means that if you specify an option or attribute value "large" and there is products which have the option value "large frame", this product will be returned by the method. You can enable strict search by adding the exclamation sign before the option or attribute value:
```
$options['attributes'] = array('CPU'=>'!2.33');
$options['options'] = array('color'=>'!black');
```
. Please note that the strict attribute search is more efficient and reliable than the strict option search. The strict option search could work incorrectly if a product option value contains commas.
list_applied_catalog_rules($customer_group_id = null) - returns a list of catalog price rules applied to the product. Returns an array of Shop_CatalogPriceRule objects. Usage example:
```
<ul>
  <? foreach ($product->list_applied_catalog_rules() as $rule): ?>
    <li>
      <?= h($rule->name) ?>
      <?= h($rule->description) ?>
    </li>
  <? endforeach ?>
</ul>
```

LemonStand Documentation

Shop_Product

Class fields

Class methods

See also:

Comments

Add your comment