Das Magento buyRequest Objekt – eine Referenz

Wer im Zusammenhang mit Bestellungen schon einmal im Magento-Quelltext oder der Datenbank gestöbert hat, dem ist vermutlich der Parameter $buyRequest in vielen Methoden bzw. die in quote items und order items gespeicherte Option info_buyRequest aufgefallen, deren Sinn nicht direkt offensichtlich ist, da scheinbar redundante Informationen enthalten sind. Es gibt dazu auch keine eigene Model-Klasse, es ist einfach ein Varien_Object bzw. in der Datenbank ein serialisiertes Array.

Beispiel:

mysql> select code,value from sales_flat_quote_item_option where option_id=2359;
+-----------------+------------------------------------------------------------------------------------------------------------+
| code            | value                                                                                                      |
+-----------------+------------------------------------------------------------------------------------------------------------+
| info_buyRequest | a:4:{s:4:"uenc";s:140:"[...],,";s:7:"product";s:4:"5000";s:15:"related_product";s:0:"";s:3:"qty";s:1:"1";} |
+-----------------+------------------------------------------------------------------------------------------------------------+

Kurz gefasst: Das $buyRequest Objekt repräsentiert die Kundenanfrage, die durch Klick auf „In den Warenkorb“ zustandekommt, alle weiteren Daten sind von diesem Objekt ableitbar. Es dient sozusagen als Generator für Quote Items. Die minimal notwendigen Daten sind also die Produkt ID (product) und Menge (qty).

Wozu wird das $buyRequest Objekt benötigt?

Es wird zum Beispiel beim hinzufügen eines Produkts zur Merkliste (Wishlist) angelegt, so dass es von dort mit der selben Konfiguration einfach in den Warenkorb gelegt werden kann. Beim „rekonfigurieren“, also dem Bearbeiten eines Items vom Warenkorb aus wird der buyRequest dem Produkt View übergeben, um alle Optionen vorauszuwählen.

Auch für Wiederkehrende Profile (recurring profile) und Nachbestellen (reorder) werden die $buyRequest Objekte „wiederverwendet“, um eine neue Bestellung zu generieren.

Anwendungsfälle

Einige Beispiele, wann man sich mit dem buyRequest beschäftigen sollte:

• Programmatisches erstellen von Bestellungen. Siehe Mage_Sales_Model_Quote::addProduct()
• Automatisches in den Warenkorb legen von komplexen Produkten. Siehe Mage_Checkout_Model_Cart::addProduct().
• Implementierung eigener Produkttypen. Der buyRequest wird in Mage_Catalog_Model_Product_Type_Abstract::_prepareProduct() verarbeitet.
• Manipulation von Quote oder Wishlist Items. Siehe Mage_Sales_Model_Quote::updateItem() und Mage_Wishlist_Model_Wishlist::updateItem(). In meiner Extension SSE_EditCustomOptions kann man sich ansehen, wie auch Custom Options in Bestellungen nachträglich angepasst werden können, indem das buyRequest-Objekt manipuliert wird. In der Extension C4B_Freeproduct wird das buyRequest-Objekt benutzt, um automatisch in den Warenkorb gelegte Geschenke zu kennzeichnen, um sie beim Nachbestellen nicht erneut in den Warenkorb zu legen. Es gibt nämlich beim Nachbestellen keine Fieldset Conversion von Order Items zu Quote Items – klar, in der Zwischenzeit hätten sich Preise oder ähnliches ändern können und das Quote soll anhand Anfrage und Produktdaten neu generiert werden.
• Flexible Preise durch Konfiguration auf der Produktseite. Eigene Request-Parameter können in die Preisberechnung mit einbezogen werden. Mehr dazu schreibt Andreas von Studnitz im Artikel Umsetzung von flexiblen Preisen.

Welche Daten können in $buyRequest gespeichert sein?

Neben product und qty sind dies Bündeloptionen bei Bündelprodukten, konfigurierbare Attribute bei konfigurierbaren Produkten, ausgewählte Links bei Download-Produkten sowie eigene Optionen (Custom Options).

Alle Produkt-Typen

• product: die Produkt-ID
• qty: Angefragte Menge. Wenn sich die Menge im Quote Item oder Wishlist Item ändert, wird sie auch hier angepasst.
• original_qty: Falls sich der Wert von qty geändert hat, enthält original_qty weiterhin die ursprünglich angefragte Menge
• reset_count: wird für die Aktualisierung von Items im Warenkorb benutzt und sollte besser reset_qty heißen. Wird vor dem Hinzufügen des Produkts zum Quote auf true gesetzt, wenn die Menge (qty) eines eventuell bereits bestehenden Quote Items zurückgesetzt werden soll, bevor die neue Menge hinzugefügt wird, die Mengen also nicht addiert werden. Gesetzt wird es standardmäßig in Mage_Sales_Model_Quote::updateItem(). Abgefragt wird es in Mage_Sales_Model_Quote::addProductAdvanced(). Sobald einmal gesetzt, wird reset_count auch gespeichert, ohne aber weiter von Bedeutung zu sein.
• Weitere beim in den Warenkorb legen Formular übertragene Parameter ohne Bedeutung für die Quote Generierung:
  • related_product
  • uenc
  • form_key

Produkte mit Custom Options

• options: Array der eigenen Optionen (Custom Options) nach dem Schema:
  option_id => value
• options_{$optionId}_file_action: Kann den Wert „save_old“ enthalten, wenn ein vorhandener Datei-Upload aus bestehender Konfiguration verwendet wird (nach Rekonfiguration von Item in Warenkorb)
• _processing_params: Einmal-Parameter, die normalerweise nicht gespeichert werden sondern nur temporär benötigt werden. Array mit zusätzlichen Informationen für Custom Options mit Dateianhang. Es kann folgenden Inhalt haben:
  • current_config: Aktuelles buyRequest-Objekt. siehe Mage_Catalog_Helper_Product::addParamsToBuyRequest() und Mage_Catalog_Model_Product_Option_Type_File::_getCurrentConfigFileInfo()
  • files_prefix: Präfix für Namen von Datei-Inputs

Grouped Products

• super_group: (in buyRequest für das Gruppenprodukt) Array der ausgewählten Gruppen-Produkte in der Form
  sub_product_id => qty
• super_product_config: (in buyRequest, der für die Einzelprodukte generiert wird) Array der Form
  product_type => 'grouped'
product_id => group_product_id

Configurable Products

• super_attribute: Array der konfigurierten Attribute in der Form
  attribute_id => value_id

Downloadable Products

• links: Array aller Link-Ids, die zum Kauf ausgewählt wurden. Falls Links nicht einzeln erwerbbar sind, wird es automatisch mit allen Links des Produkts befüllt.

Bundle Products

• options: Array der ausgewählten Optionen nach dem Schema:
  option_id => selection_id[]
• bundle_option_qty: Array der Anzahl für ausgewählte Optionen nach dem Schema:
  option_id => qty

Erweiterungsmöglichkeiten: eigene Daten

Manchmal kann es sinnvoll sein, eigene Daten im $buyRequest Objekt unterzubringen. Prinzipiell gibt es zwei Fälle, wie das möglich ist:

1. Programmatisch hinzugefügte Produkte: der buyRequest wird als zweiter Parameter an Mage_Sales_Model_Quote::addProduct() übergeben. Interessant: Der Parameter kann genauso gut ein float sein, für die Anzahl, wenn es keine Custom Options oder sonstige Daten gibt. Der Standardwert ist „1“.
2. Normal in den Warenkorb gelegte Produkte: alle Inputs im Formular zum in den Warenkorb legen werden in den buyRequest übernommen. Das Formular auf der Produktseite kann also beliebig erweitert werden, die Daten werden automatisch mitgespeichert.

Sollen sich die eigenen Daten im buyRequest auf Produkt-Attribute oder -Optionen auswirken, bietet sich ein Observer auf das Event catalog_product_type_prepare_{$processMode}_options an, wobei $processMode der Validierungs-Modus ist und entweder „full“ oder „lite“ sein kann. Der „full“-Modus wird beispielsweise beim normalen in den Warenkorb legen genutzt und prüft, ob alle benötigten Optionen gesetzt sind und die gesamte Konfiguration gültig ist. Im „lite“-Modus werden nur die im Request enthaltenen Optionen validiert, was zum Beispiel beim hinzufügen zur Merkliste der Fall ist, aber auch beim erstellen einer Bestellung aus dem Backend möglich ist. Um die Daten in jedem Fall zu verarbeiten, kann der selbe Observer für beide Events registriert werden. Sollen die Daten an dieser Stelle auch validiert werden, sollte natürlich differenziert werden.

Getriggert werden die Events in Mage_Catalog_Model_Product_Type_Abstract::_prepareOptions() und folgende Parameter sind verfügbar:

• transport: Transport-Objekt für alle Custom Options (aber keine anderen, z.B. Bündeloptionen), die darüber im Observer geändert werden können. transport->options ist ein Array in der Form option_id => option_value. Achtung, transport selbst ist ein stdClass Objekt, keine Instanz von Varien_Object, wie man erwarten würde. Es gibt also keine getter und setter Methoden für transport->options.
• buy_request: Das buyRequest Objekt, es kann an dieser Stelle auch selbst noch manipuliert werden
• product: Das Produkt, das im weiteren Verlauf zum Quote Item konvertiert wird. Hier können Attribute manipuliert oder dynamisch hinzugefügt werden, diese müssen anschließend allerdings noch beim Konvertierungsprozess berücksichtigt werden. Das Event, das dazu genutzt wird, sales_quote_product_add_after, wird erst im Anschluss getriggert.

Das untenstehende Diagramm zeigt, welche Methoden das buyRequest Objekt beim in den Warenkorb legen verarbeiten. Neben den hier gezeigten Events gibt es noch viele andere Möglichkeiten, in eigenen Erweiterungen auf es zuzugreifen, denn wie gesagt, ist es wie eine Custom Option am Quote Item gespeichert. Der oben genannte Artikel Umsetzung von flexiblen Preisen nutzt zum Beispiel das Event catalog_product_get_final_price um die Preisberechnung zu manipulieren und greift dort über das Produkt auf die buyRequest Option zu.

Eine Anmerkung zum Event sales_quote_product_add_after: Der Parameter items ist ein 0-indiziertes Array von allen einzelnen Quote Items, die diesem Request generiert wurden. Bei Simple Products ist das nur ein einzelnes Item, bei Bündeln und konfigurierbaren Produkten das Item zum Hauptprodukt und seine Kinder, wobei das Eltern-Item immer an erster Stelle steht.