nystudio107 / craft-instantanalytics-ga4

src/services/Commerce.php

<?php
/**
 * Instant Analytics plugin for Craft CMS
 *
 * Instant Analytics brings full Google Analytics support to your Twig templates
 *
 * @link      https://nystudio107.com

The tag in position 1 should be the @copyright tag

 * @copyright Copyright (c) 2017 nystudio107

@copyright tag must contain a year and the name of the copyright holder

 */

PHP version not specified

Missing @category tag in file comment

Missing @package tag in file comment

Missing @author tag in file comment

Missing @license tag in file comment

namespace nystudio107\instantanalyticsGa4\services;

use Br33f\Ga4\MeasurementProtocol\Dto\Event\ItemBaseEvent;
use Br33f\Ga4\MeasurementProtocol\Dto\Event\PurchaseEvent;
use Br33f\Ga4\MeasurementProtocol\Dto\Parameter\ItemParameter;
use craft\base\Component;
use craft\commerce\elements\Order;
use craft\commerce\elements\Product;
use craft\commerce\elements\Variant;
use craft\commerce\models\LineItem;
use craft\commerce\Plugin as CommercePlugin;
use craft\elements\db\CategoryQuery;
use craft\elements\db\EntryQuery;
use craft\elements\db\TagQuery;
use nystudio107\instantanalyticsGa4\InstantAnalytics;
use yii\base\InvalidConfigException;
use function get_class;

/**
 * Commerce Service
 *
 * @author    nystudio107

The tag in position 1 should be the @package tag

Content of the @author tag must be in the form "Display Name <username@example.com>"

Tag value for @author tag indented incorrectly; expected 2 spaces but found 4

 * @package   InstantAnalytics

Tag value for @package tag indented incorrectly; expected 1 spaces but found 3

 * @since     1.0.0

The tag in position 3 should be the @author tag

Tag value for @since tag indented incorrectly; expected 3 spaces but found 5

 */

Missing @category tag in class comment

Missing @license tag in class comment

Missing @link tag in class comment

class Commerce extends Component
{
    // Public Methods
    // =========================================================================

    /**
     * Enqueue analytics information for the completed order
     *
     * @param ?Order $order the Product or Variant
     */

Missing @return tag in function comment

    public function triggerOrderCompleteEvent(Order $order = null)
    {
        if ($order) {
            $event = InstantAnalytics::$plugin->ga4->getAnalytics()->create()->PurchaseEvent();
            $this->addCommerceOrderToEvent($event, $order);

            InstantAnalytics::$plugin->ga4->getAnalytics()->addEvent($event);

            InstantAnalytics::$plugin->logAnalyticsEvent(

The method logAnalyticsEvent() does not exist on null.

                'Adding `Commerce - Order Complete event`: `{reference}` => `{price}`',
                ['reference' => $order->reference, 'price' => $order->totalPrice],
                __METHOD__
            );
        }
    }

    /**
     * Enqueue analytics information for a new checkout flow
     *
     * @param ?Order $order

Missing parameter comment

     */

Missing @return tag in function comment

    public function triggerBeginCheckoutEvent(Order $order = null)
    {
        if ($order) {
            $event = InstantAnalytics::$plugin->ga4->getAnalytics()->create()->BeginCheckoutEvent();
            // First, include the transaction data
            $event->setCurrency($order->getPaymentCurrency())
                ->setValue($order->getTotalPrice());

            // Add each line item in the cart
            $index = 1;
            foreach ($order->lineItems as $lineItem) {
                $this->addProductDataFromLineItem($event, $lineItem, $index);
                $index++;
            }

            InstantAnalytics::$plugin->ga4->getAnalytics()->addEvent($event);

            InstantAnalytics::$plugin->logAnalyticsEvent(
                'Adding `Commerce - Begin Checkout event``',
                [],
                __METHOD__
            );
        }
    }

    /**
     * Send analytics information for the item added to the cart
     *
     * @param LineItem $lineItem the line item that was added
     */

Missing @return tag in function comment

    public function triggerAddToCartEvent(LineItem $lineItem): void
    {
        $event = InstantAnalytics::$plugin->ga4->getAnalytics()->create()->AddToCartEvent();
        $this->addProductDataFromLineItem($event, $lineItem);
        InstantAnalytics::$plugin->ga4->getAnalytics()->addEvent($event);

        InstantAnalytics::$plugin->logAnalyticsEvent(
            'Adding `Commerce - Add to Cart event`: `{title}` => `{quantity}`',
            ['title' => $lineItem->purchasable->title ?? $lineItem->getDescription(), 'quantity' => $lineItem->qty],
            __METHOD__
        );
    }

    /**
     * Send analytics information for the item removed from the cart
     *
     * @param LineItem $lineItem

Missing parameter comment

     */

Missing @return tag in function comment

    public function triggerRemoveFromCartEvent(LineItem $lineItem)
    {
        $event = InstantAnalytics::$plugin->ga4->getAnalytics()->create()->RemoveFromCartEvent();
        $this->addProductDataFromLineItem($event, $lineItem);
        InstantAnalytics::$plugin->ga4->getAnalytics()->addEvent($event);

        InstantAnalytics::$plugin->logAnalyticsEvent(
            'Adding `Commerce - Remove from Cart event`: `{title}` => `{quantity}`',
            ['title' => $lineItem->purchasable->title ?? $lineItem->getDescription(), 'quantity' => $lineItem->qty],
            __METHOD__
        );
    }

    /**
     * Add a product impression from a Craft Commerce Product or Variant
     *
     * @param Product|Variant|null $productVariant the Product or Variant

Tag value for @param tag indented incorrectly; expected 2 spaces but found 1

     * @throws InvalidConfigException

Tag @throws cannot be grouped with parameter tags in a doc comment

     */

Missing @return tag in function comment

    public function addCommerceProductImpression(Variant|Product|null $productVariant): void
    {
        if ($productVariant) {
            $event = InstantAnalytics::$plugin->ga4->getAnalytics()->create()->ViewItemEvent();
            $this->addProductDataFromProductOrVariant($event, $productVariant);

            InstantAnalytics::$plugin->ga4->getAnalytics()->addEvent($event);

            $sku = $productVariant instanceof Product ? $productVariant->getDefaultVariant()->sku : $productVariant->sku;
            $name = $productVariant instanceof Product ? $productVariant->getName() : $productVariant->getProduct()->getName();

The method getProduct() does not exist on null.

The function craft\commerce\elements\Variant::getProduct() has been deprecated: in 5.0.0. Use [[getOwner()]] instead.

            InstantAnalytics::$plugin->logAnalyticsEvent(
                'Adding view item event for `{sku}` - `{name}` - `{name}` - `{index}`',
                ['sku' => $sku, 'name' => $name],
                __METHOD__
            );
        }
    }

    /**
     * Add a product list impression from a Craft Commerce Product or Variant list
     *
     * @param Product[]|Variant[] $products

Missing parameter comment

     * @param string $listName

Missing parameter comment

Expected 14 spaces after parameter type; 1 found

     */

Missing @return tag in function comment

    public function addCommerceProductListImpression(array $products, string $listName = 'default'): void
    {
        if (!empty($products)) {
            $event = InstantAnalytics::$plugin->ga4->getAnalytics()->create()->ViewItemListEvent();
            foreach ($products as $index => $productVariant) {
                $this->addProductDataFromProductOrVariant($event, $productVariant, $index, $listName);
            }

            InstantAnalytics::$plugin->ga4->getAnalytics()->addEvent($event);

            InstantAnalytics::$plugin->logAnalyticsEvent(
                'Adding view item list event. Listing {number} of items from the `{listName}` list.',
                ['number' => count($products), 'listName' => $listName],
                __METHOD__
            );
        }
    }

    /**
     * Add a Craft Commerce OrderModel to a Purchase Event
     *
     * @param PurchaseEvent $event The PurchaseEvent
     * @param Order $order

Missing parameter comment

Expected 9 spaces after parameter type; 1 found

     */

Missing @return tag in function comment

    protected function addCommerceOrderToEvent(PurchaseEvent $event, Order $order)
    {
        // First, include the transaction data
        $event->setCurrency($order->getPaymentCurrency())
            ->setTransactionId($order->reference)
            ->setValue($order->getTotalPrice())
            ->setTax($order->getTotalTax())
            ->setShipping($order->getTotalShippingCost());

        // Coupon code
        if ($order->couponCode) {
            $event->setCoupon($order->couponCode);
        }

        // Add each line item in the transaction
        // Two cases - variant and non variant products
        $index = 1;

        foreach ($order->lineItems as $lineItem) {
            $this->addProductDataFromLineItem($event, $lineItem, $index);
            $index++;
        }
    }

    /**
     * Add a Craft Commerce LineItem to an Analytics object
     *
     * @param ItemBaseEvent $event

Missing parameter comment

     * @param LineItem $lineItem

Missing parameter comment

Expected 6 spaces after parameter type; 1 found

     * @param int $index

Missing parameter comment

Expected 11 spaces after parameter type; 1 found

     * @param string $listName

Missing parameter comment

Expected 8 spaces after parameter type; 1 found

     *
     * @return string the title of the product
     * @throws InvalidConfigException
     */
    protected function addProductDataFromLineItem(ItemBaseEvent $event, LineItem $lineItem, int $index = 0, string $listName = ''): string
    {
        $eventItem = $this->getNewItemParameter();

        $product = null;
        $purchasable = $lineItem->purchasable;

        /** @phpstan-ignore-next-line */

The open comment tag must be the only content on the line

Missing short description in doc comment

The close comment tag must be the only content on the line

        if ($purchasable === null) {
            $eventItem->setItemName($lineItem->getDescription());
            $eventItem->setItemId($lineItem->getSku());
        } else {
            $eventItem->setItemName($purchasable->title ?? $lineItem->getDescription());
            $eventItem->setItemId($purchasable->getSku());
        }
        $eventItem->setPrice($lineItem->salePrice);
        $eventItem->setQuantity($lineItem->qty);

        // Handle this purchasable being a Variant
        if (is_a($purchasable, Variant::class)) {
            /** @var Variant $purchasable */

The open comment tag must be the only content on the line

Missing short description in doc comment

The close comment tag must be the only content on the line

            $product = $purchasable->getProduct();

The function craft\commerce\elements\Variant::getProduct() has been deprecated: in 5.0.0. Use [[getOwner()]] instead.

            $variant = $purchasable;
            // Product with variants
            $eventItem->setItemName($product->title);
            $eventItem->setItemVariant($variant->title);
            $eventItem->setItemCategory($product->getType());
        }

        // Handle this purchasable being a Product
        if (is_a($purchasable, Product::class)) {
            /** @var Product $purchasable */

The open comment tag must be the only content on the line

Missing short description in doc comment

The close comment tag must be the only content on the line

            $product = $purchasable;
            $eventItem->setItemName($product->title);
            $eventItem->setItemVariant($product->title);
            $eventItem->setItemCategory($product->getType());
        }

        // Handle product lists
        if ($index) {
            $eventItem->setIndex($index);
        }

        if ($listName) {
            $eventItem->setItemListName($listName);
        }

        // Add in any custom categories/brands that might be set
        if (InstantAnalytics::$settings && $product) {
            if (isset(InstantAnalytics::$settings['productCategoryField'])
                && !empty(InstantAnalytics::$settings['productCategoryField'])) {

Closing parenthesis of a multi-line IF statement must be on a new line

                $category = $this->pullDataFromField(
                    $product,
                    InstantAnalytics::$settings['productCategoryField']
                );
                $eventItem->setItemCategory($category);
            }
            if (isset(InstantAnalytics::$settings['productBrandField'])
                && !empty(InstantAnalytics::$settings['productBrandField'])) {

Closing parenthesis of a multi-line IF statement must be on a new line

                $brand = $this->pullDataFromField(
                    $product,
                    InstantAnalytics::$settings['productBrandField']
                );

                $eventItem->setItemBrand($brand);
            }
        }

        //Add each product to the hit to be sent
        $event->addItem($eventItem);

        return $eventItem->getItemName();

The expression return $eventItem->getItemName() could return the type null which is incompatible with the type-hinted return string. Consider adding an additional type-check to rule them out.

    }

    /**

Parameter $event should have a doc-comment as per coding-style.

Parameter $index should have a doc-comment as per coding-style.

Parameter $listName should have a doc-comment as per coding-style.

     * Extract product data from a Craft Commerce Product or Variant
     *
     * @param Product|Variant|null $productVariant the Product or Variant

Doc comment for parameter $productVariant does not match actual variable name $event

     *
     * @throws InvalidConfigException
     */

Missing @return tag in function comment

    protected function addProductDataFromProductOrVariant(ItemBaseEvent $event, $productVariant = null, $index = null, $listName = ''): void
    {
        if ($productVariant === null) {
            return;
        }

        $eventItem = $this->getNewItemParameter();

        $isVariant = $productVariant instanceof Variant;
        $variant = $isVariant ? $productVariant : $productVariant->getDefaultVariant();

        if (!$variant) {
            return;
        }

        $eventItem->setItemId($variant->sku);
        $eventItem->setItemName($variant->title);
        $eventItem->setPrice((float)number_format($variant->price, 2, '.', ''));

        $category = ($isVariant ? $variant->getProduct() : $productVariant)->getType()['name'];

The method getType() does not exist on null.

The function craft\commerce\elements\Variant::getProduct() has been deprecated: in 5.0.0. Use [[getOwner()]] instead.

        if (InstantAnalytics::$settings) {
            if (isset(InstantAnalytics::$settings['productCategoryField'])
                && !empty(InstantAnalytics::$settings['productCategoryField'])) {

Closing parenthesis of a multi-line IF statement must be on a new line

                $category = $this->pullDataFromField(
                    $productVariant,
                    InstantAnalytics::$settings['productCategoryField']
                );
                /* @TODO not sure what this even does
                 * if (empty($productData['category']) && $isVariant) {
                 * $category = $this->pullDataFromField(
                 * $productVariant->product,
                 * InstantAnalytics::$settings['productCategoryField']
                 * );
                 * }
                 */
            }
            $eventItem->setItemCategory($category);

            if (isset(InstantAnalytics::$settings['productBrandField'])
                && !empty(InstantAnalytics::$settings['productBrandField'])) {

Closing parenthesis of a multi-line IF statement must be on a new line

                $brand = $this->pullDataFromField(
                    $productVariant,
                    InstantAnalytics::$settings['productBrandField'],
                    true
                );
                /* @TODO not sure what this even does
                 * if (empty($productData['brand']) && $isVariant) {
                 * $brand = $this->pullDataFromField(
                 * $productVariant,
                 * InstantAnalytics::$settings['productBrandField'],
                 * true
                 * );
                 * }
                 */
                $eventItem->setItemBrand($brand);
            }
        }

        if ($index !== null) {
            $eventItem->setIndex($index);
        }

        if (!empty($listName)) {
            $eventItem->setItemListName($listName);
        }

        // Add item info to the event
        $event->addItem($eventItem);
    }

    /**

Missing short description in doc comment

     * @param Product|Variant|null $productVariant

Missing parameter comment

     * @param string $fieldHandle

Missing parameter comment

Expected 15 spaces after parameter type; 1 found

     * @param bool $isBrand

Missing parameter comment

Expected 17 spaces after parameter type; 1 found

     *
     * @return string
     */
    protected function pullDataFromField($productVariant, $fieldHandle, $isBrand = false): string
    {
        $result = '';
        if ($productVariant && $fieldHandle) {
            $srcField = $productVariant[$fieldHandle] ?? $productVariant->product[$fieldHandle] ?? null;
            // Handle eager loaded elements
            if (is_array($srcField)) {
                return $this->getDataFromElements($isBrand, $srcField);
            }
            // If the source field isn't an object, return nothing
            if (!is_object($srcField)) {
                return $result;
            }
            switch (get_class($srcField)) {
                case TagQuery::class:

Line indented incorrectly; expected 12 spaces, found 16

                    break;
                case CategoryQuery::class:

Line indented incorrectly; expected 12 spaces, found 16

                case EntryQuery::class:

Line indented incorrectly; expected 12 spaces, found 16

                    $result = $this->getDataFromElements($isBrand, $srcField->all());
                    break;

                default:

Line indented incorrectly; expected 12 spaces, found 16

                    $result = strip_tags($srcField->__toString());
                    break;
            }
        }

        return $result;
    }

    /**

Missing short description in doc comment

     * @param bool $isBrand

Missing parameter comment

Expected 2 spaces after parameter type; 1 found

Tag value for @param tag indented incorrectly; expected 2 spaces but found 1

     * @param array $elements

Missing parameter comment

Tag value for @param tag indented incorrectly; expected 2 spaces but found 1

     * @return string

Tag @return cannot be grouped with parameter tags in a doc comment

     */
    protected function getDataFromElements(bool $isBrand, array $elements): string
    {
        $cats = [];

        if ($isBrand) {
            // Because we can only have one brand, we'll get
            // the very last category. This means if our
            // brand is a sub-category, we'll get the child
            // not the parent.
            foreach ($elements as $cat) {
                $cats = [$cat->title];
            }
        } else {
            // For every category, show its ancestors
            // delimited by a slash.
            foreach ($elements as $cat) {
                $name = $cat->title;

                while ($cat = $cat->parent) {
                    $name = $cat->title . '/' . $name;
                }

                $cats[] = $name;
            }
        }

        // Join separate categories with a pipe.
        return implode('|', $cats);
    }

    /**
     * Create an item parameter and set affiliation on it, if any exists.
     *
     * @return ItemParameter
     */
    protected function getNewItemParameter(): ItemParameter
    {
        $parameter = new ItemParameter();
        $parameter->setAffiliation(InstantAnalytics::$plugin->ga4->getAnalytics()->getAffiliation());
        $parameter->setCurrency(CommercePlugin::getInstance()->getPaymentCurrencies()->getPrimaryPaymentCurrencyIso());

        return $parameter;
    }
}