Skip to content

Using feed "extension" classes

Jump to bottom
lat9 edited this page Feb 26, 2024 · 4 revisions

Google Product Search Feeder II (GPSF2) uses class extensions to enable site-specific additions to a product feed. When a feed is being generated, the feed's main controller loads all .php files present in the /includes/classes/gpsf directory alphabetically. An extension provides a means for a site, for instance, to identify a product's MAP price or site-specific gtin.

Each such file is expected to contain a class that extends the gpsfBase class found in /includes/classes/gpsf/gpsfBase.php and that class' name must be the same as the class' filename. For example, a file named gpsfMySite.php is expected to include the definition of a class named gpsfMySite.

Extension Methods (gpsfBase)

getAdditionalQueryFields

This method is called once at the start of a feed's generation to gather additional database tables and/or fields as well as query clauses for the overall database query-selection for the feed. The base feed always includes the following tables and associated fields:

  • Tables
    • TABLE_PRODUCTS (p)
    • TABLE_PRODUCTS_DESCRIPTION (pd)
    • TABLE_MANUFACTURERS (m)
    • TABLE_PRODUCT_TYPES (pt)
  • Fields
    • p.products_id, p.products_model, , p.products_image, p.products_tax_class_id, p.products_price, p.products_priced_by_attribute, p.products_type, p.master_categories_id, GREATEST(p.products_date_added, IFNULL(p.products_last_modified, 0), IFNULL(p.products_date_available, 0)) AS base_date, p.products_date_available, p.products_quantity, p.products_weight, p.product_is_always_free_shipping
    • pd.products_description, pd.products_name
    • m.manufacturers_name
    • pt.type_handler

Method Definition

public function getAdditionalQueryFields(string $additional_fields_base, string $additional_tables_base): array

Method Inputs

The method is supplied two string inputs that identify any database field or table additions currently in effect:

  • $additional_fields_base. A string containing a comma-separated list of additional database fields to be gathered by the overall feed's selection.
  • $additional_tables_base. A string containing a blank-separated list of additional tables to be JOINed in gathering the overall feed's selection.

Method Output

The method returns a simple array of three elements, in the following order:

        return [
            $additional_fields,
            $additional_tables,
            $additional_where_clause,
        ];
  • $additional_fields. Contains a comma-separated string of additional database fields required by the extension.
  • $additional_tables. Contains a blank-separated string of additional table-joins required by the extension.
  • $additional_where_clause. Contains a string of AND separated clauses used to limit the products included in the feed.

bypassProductInFeed

This method is called once for each product that is a candidate for the feed, giving site-specific customization the opportunity to "not include" the current product in the generated feed.

Method Definition

public function bypassProductInFeed(string $products_id, array $product): string

Method Inputs

The method is supplied two inputs:

  • $products_id. The string representation of the current product's products_id value.
  • $product. An associative array containing all the database fields selected for the current product.

Method Output

The method returns a string value identifying whether ('', an empty string) or not (any other value) the product is to remain in the generated feed.

getProductsFeedId

This method is called once for each product that is a candidate for the feed, giving site-specific customization the opportunity to override the current id (the g:id attribute) for the current product.

Method Definition

public function getProductsFeedId(string $products_id, $id, array $product)

Method Inputs

The method is supplied three inputs:

  • $products_id. The string representation of the current product's products_id value.
  • $id. The value currently determined for the g:id value. This can be either a valid string or (bool)false if no id-value could be determined for the product.
  • $product. An associative array containing all the database fields selected for the current product.

Method Output

The method returns either a string identifying the value to be used for the product's g:id value or (bool)false if no value could be determined. Returning a value of (bool)false will cause the product to not be included in the feed!

modifyProductsDescription

This method is called once for each product that is a candidate for the feed, giving site-specific customization the opportunity to make modifications to the current product's description, possibly appending some additional information.

Method Definition

public function modifyProductsDescription(string $products_id, string $products_description, array $product): string

Method Inputs

The method is supplied three inputs:

  • $products_id. The string representation of the current product's products_id value.
  • $products_description. The value currently determined for the product's descriptive text (g:description).
  • $product. An associative array containing all the database fields selected for the current product.

Method Output

The method returns the string value of the descriptive text for the product. If the value returned is an empty string, the product will not be included in the feed!

getProductsAttributes

This method is called once for each product that is a candidate for the feed, giving site-specific customization the opportunity to include additional feed-related attributes to the product's feed information.

Method Definition

public function getProductsAttributes(string $products_id, array $product, array $categories_list, array $cPath, array $custom_fields): array

Method Inputs

The method is supplied five inputs:

  • $products_id. The string representation of the current product's products_id value.
  • $product. An associative array containing all the database fields selected for the current product.
  • $categories_list. A numerically-indexed array containing the product's category and sub-category names. Element 0 contains the product's top-most category name.
  • $cPath. A numerically-indexed array containing the product's category and sub-category categories_id values. Element 0 contains the product's top-most categories_id.
  • $custom_fields. An associative array (keyed on the feed attribute's name minus the leading g:) containing all currently recorded feed attributes for the product.

Method Output

The method returns an associative array of feed attribute (and possibly sub-attribute) values to be added to or replaced in the product's feed information. That array's keys are the feed attribute or sub-attribute names, minus the leading g:.

For example, an extension could add or replace the product's g:gtin attribute by returning

[
    'gtin' => '0123456789',
]

Notes:

  1. It is the extension's responsibility to properly format any non-string attribute type. For example, the 'adult' attribute should be set to (string)'true'/'false' values, not (bool)true/false. Any URL-type attributes returned should be have spaces (' ') converted to %20.
  2. Starting with v1.0.1, this method can also be used to replace the base feed's value for a product's g:link, g:product_type and g:brand attributes. If the g:link attribute is supplied, it is the extension's responsibility to properly sanitize any ampersands and spaces in that link!

getProductsShippingRate

This method is called once for each product that is a candidate for the feed, giving site-specific customization the opportunity to override the product's shipping rate.

Method Definition

public function getProductsShippingRate(string $products_id, $products_weight, $products_price, string $product_is_always_free_shipping): float

Method Inputs

The method is supplied four inputs:

  • $products_id. The string representation of the current product's products_id value.
  • $products_weight. The string or float value identifying the product's weight.
  • $products_price. The string or float value identifying the product's price.
  • $product_is_always_free_shipping. The string identifier that indicates whether ('1') or not ('0') the product is always free-shipping.

Method Output

The method returns an floating-point ((float)) value identifying the product's shipping rate/pricing. If the extension doesn't wish to override the 'base' feed-generated shipping price, it returns (float)-1.0. A value >= 0 returned is recorded in the product's g:shipping attribute's g:price sub-attribute.

Note: If multiple extensions are loaded, the first extension that returns a value >= 0.0 "wins".

getProductPricing

This method is called once for each product that is a candidate for the feed, giving site-specific customization the opportunity to override the product's price and/or sale-price.

Method Definition

public function getProductPricing(string $products_id, array $product, $price, $sale_price): array

Method Inputs

The method is supplied four inputs:

  • $products_id. The string representation of the current product's products_id value.
  • $product. An associative array containing all the database fields selected for the current product.
  • $price. The string or float value identifying the product's currently-calculated 'base' price, as returned by zen_get_products_base_price.
  • $sale_price. The string or float value identifying the product's currently-calculated sale-price, as returned by zen_get_products_special_price.

Method Output

The method returns a numerically-indexed array containing any update to the product's $price and/or $sale_price. If no update is to be made, the extension returns the values input.

return [
    $price,
    $sale_price
];

getProductsImageUrl

This method is called once for each product that is a candidate for the feed, giving site-specific customization the opportunity to override the product's primary-image URL, the g:image attribute for the product.

Method Definition

public function getProductsImageUrl(string $products_image)

Method Inputs

The method is supplied a single input:

  • $products_image. The string representation of the current product's products_image value, as defined in the product's database record.

Method Output

The method returns one of three possible values:

  1. (bool)false. No override is necessary, the base feed will format the product's image-link.
  2. null. The product's image, and thus the product, is not to be included in the feed.
  3. (string)$products_url. The value to be used for the product's g:image feed attribute.

getProductsTitle

This method is called once for each product that is a candidate for the feed, giving site-specific customization the opportunity to override the value to be set for the product's g:title attribute, defaulting to the products::products_name.

Method Definition

public function getProductsTitle(string $products_id, string $products_title, array $product): string

Method Inputs

The method is supplied three inputs:

  • $products_id. The string representation of the current product's products_id value.
  • $products_title. The string current value to be used as the product's g:title feed attribute.
  • $product. An associative array containing all the database fields selected for the current product.

Method Output

The method returns a string output identifying the value to be used as the product's feed-title. Note that returning an empty string will result in the product being excluded from the feed, since each product in the feed must have a non-empty g:title!

Clone this wiki locally