nystudio107 / craft-instantanalytics-ga4

src/ga4/Analytics.php

<?php
/**
 * Instant Analytics plugin for Craft CMS
 *
 * @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>"

 * @copyright Copyright (c) 2017 nystudio107

The tag in position 2 should be the @author tag

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

 * @link      http://nystudio107.com

The tag in position 3 should be the @copyright tag

 * @package   InstantAnalytics

The tag in position 4 should be the @link tag

 * @since     1.0.0
 */

PHP version not specified

Missing @category tag in file comment

Missing @license tag in file comment

namespace nystudio107\instantanalyticsGa4\ga4;

use Br33f\Ga4\MeasurementProtocol\Dto\Event\AbstractEvent;
use Br33f\Ga4\MeasurementProtocol\Dto\Request\BaseRequest;
use Br33f\Ga4\MeasurementProtocol\Exception\HydrationException;
use Br33f\Ga4\MeasurementProtocol\Exception\ValidationException;
use Br33f\Ga4\MeasurementProtocol\HttpClient;
use Craft;
use craft\commerce\elements\Order;
use craft\commerce\elements\Product;
use craft\commerce\elements\Variant;
use craft\errors\MissingComponentException;
use craft\helpers\App;
use nystudio107\instantanalyticsGa4\helpers\Analytics as AnalyticsHelper;
use nystudio107\instantanalyticsGa4\InstantAnalytics;
use nystudio107\seomatic\Seomatic;
use yii\base\InvalidConfigException;

/**

Missing short description in doc comment

 * @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.2.0

The tag in position 3 should be the @author tag

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

 *
 * @method Analytics setAllowGoogleSignals(string $value)
 * @method Analytics setAllowAdPersonalizationSignals(string $value)
 * @method Analytics setCampaignContent(string $value)
 * @method Analytics setCampaignId(string $value)
 * @method Analytics setCampaignMedium(string $value)
 * @method Analytics setCampaignName(string $value)
 * @method Analytics setCampaignSource(string $value)
 * @method Analytics setCampaignTerm(string $value)
 * @method Analytics setCampaign(string $value)
 * @method Analytics setClientId(string $value)
 * @method Analytics setContentGroup(string $value)
 * @method Analytics setCookieDomain(string $value)
 * @method Analytics setCookieExpires(string $value)
 * @method Analytics setCookieFlags(string $value)
 * @method Analytics setCookiePath(string $value)
 * @method Analytics setCookiePrefix(string $value)
 * @method Analytics setCookieUpdate(string $value)
 * @method Analytics setLanguage(string $value)
 * @method Analytics setPageLocation(string $value)
 * @method Analytics setPageReferrer(string $value)
 * @method Analytics setPageTitle(string $value)
 * @method Analytics setSendPageView(string $value)
 * @method Analytics setScreenResolution(string $value)
 * @method Analytics setUserId(string $value)
 */

Missing @category tag in class comment

Missing @license tag in class comment

Missing @link tag in class comment

class Analytics
{
    /**

Missing short description in doc comment

     * @var BaseRequest|null
     */
    private ?BaseRequest $_request = null;

    /**

Missing short description in doc comment

     * @var Service|null|false
     */
    private mixed $_service = null;

    /**

Missing short description in doc comment

     * @var string|null
     */
    private ?string $_affiliation = null;

    private ?bool $_shouldSendAnalytics = null;

    private ?string $_sessionString = null;

    private array $eventList = [];

Private member variable "eventList" must be prefixed with an underscore

    /**
     * Component factory for creating events.
     *
     * @return ComponentFactory
     */
    public function create(): ComponentFactory
    {
        return new ComponentFactory();
    }

    /**
     * Add an event to be sent to Google
     *
     * @param AbstractEvent $event

Missing parameter comment

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

     * @return void

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

     */
    public function addEvent(AbstractEvent $event): void
    {
        if ($this->_sessionString === null) {
            $this->_sessionString = AnalyticsHelper::getSessionString();
        }

        if (str_contains($this->_sessionString, '.')) {

It seems like $this->_sessionString can also be of type null; however, parameter $haystack of str_contains() does only seem to accept string, maybe add an additional type check?

            [$sessionId, $sessionNumber] = explode('.', $this->_sessionString);

It seems like $this->_sessionString can also be of type null; however, parameter $string of explode() does only seem to accept string, maybe add an additional type check?

            $event->setParamValue('sessionId', $sessionId);
            $event->setParamValue('sessionNumber', $sessionNumber);
        }

        $this->eventList[] = $event;
    }

    /**
     * Send the events collected so far.
     *
     * @return ?array
     * @throws HydrationException
     * @throws ValidationException
     */
    public function sendCollectedEvents(): ?array
    {
        if ($this->_shouldSendAnalytics === null) {
            $this->_shouldSendAnalytics = AnalyticsHelper::shouldSendAnalytics();
        }

        if (!$this->_shouldSendAnalytics) {

The expression $this->_shouldSendAnalytics of type boolean|null is loosely compared to false; this is ambiguous if the boolean can be false. You might want to explicitly use !== null instead.

            return null;
        }

        $service = $this->service();

        if (!$service) {
            return null;
        }

        $request = $this->request();
        $eventCount = count($this->eventList);

        if (!InstantAnalytics::$settings->sendAnalyticsData) {
            InstantAnalytics::$plugin->logAnalyticsEvent(

The method logAnalyticsEvent() does not exist on null.

                'Analytics not enabled - skipped sending {count} events',
                ['count' => $eventCount],
                __METHOD__
            );

            return null;
        }

        if ($eventCount === 0) {
            InstantAnalytics::$plugin->logAnalyticsEvent(
                'No events collected to send',
                [],
                __METHOD__
            );

            return null;
        }

        InstantAnalytics::$plugin->logAnalyticsEvent(
            'Sending {count} analytics events',
            ['count' => $eventCount],
            __METHOD__
        );

        // Batch into groups of 25
        $responses = [];

        foreach (array_chunk($this->eventList, 25) as $chunk) {
            $request->getEvents()->setEventList([]);

            /** @var AbstractEvent $event */

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

            foreach ($chunk as $event) {
                $request->addEvent($event);
            }

            $responses[] = $service->send($request);
        }


        return $responses;
    }

    public function getAffiliation(): ?string

Missing doc comment for function getAffiliation()

    {
        return $this->_affiliation;
    }

    /**
     * Set affiliation for all the events that incorporate Commerce Product info for the remaining duration of request.
     *
     * @param string $affiliation

Missing parameter comment

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

     * @return $this

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

     */
    public function setAffiliation(string $affiliation): self
    {
        $this->_affiliation = $affiliation;
        return $this;
    }

    /**
     * Add a commerce item list impression.
     *
     * @param Product|Variant $productVariant

Missing parameter comment

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

     * @param int $index

Missing parameter comment

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

Expected 13 spaces after parameter type; 1 found

     * @param string $listName

Missing parameter comment

Expected 10 spaces after parameter type; 1 found

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(Product|Variant $productVariant, int $index = 0, string $listName = 'default')
    {
        InstantAnalytics::$plugin->commerce->addCommerceProductImpression($productVariant);
    }

    /**
     * Begin checkout.
     *
     * @param Order $cart

Missing parameter comment

     */

Missing @return tag in function comment

    public function beginCheckout(Order $cart)
    {
        InstantAnalytics::$plugin->commerce->triggerBeginCheckoutEvent($cart);
    }

    /**
     * Add a commerce item list impression.
     *
     * @param Product|Variant $productVariant

Missing parameter comment

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

     * @param int $index

Missing parameter comment

Expected 13 spaces after parameter type; 1 found

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

     * @param string $listName

Missing parameter comment

Expected 10 spaces after parameter type; 1 found

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

     * @throws InvalidConfigException

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

Tag value for @throws tag indented incorrectly; expected 5 spaces but found 1

     * @deprecated `Analytics::addCommerceProductDetailView()` is deprecated. Use `Analytics::addCommerceProductImpression()` instead.

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

     */

Missing @return tag in function comment

    public function addCommerceProductDetailView(Product|Variant $productVariant, int $index = 0, string $listName = 'default')
    {
        Craft::$app->getDeprecator()->log('Analytics::addCommerceProductDetailView()', '`Analytics::addCommerceProductDetailView()` is deprecated. Use `Analytics::addCommerceProductImpression()` instead.');
        $this->addCommerceProductImpression($productVariant);
    }

    /**
     * Add a commerce product list impression.
     *
     * @param array $products

Missing parameter comment

     * @param $listName

Missing parameter comment

     */

Missing @return tag in function comment

    public function addCommerceProductListImpression(array $products, string $listName = 'default')
    {
        InstantAnalytics::$plugin->commerce->addCommerceProductListImpression($products, $listName);
    }

    /**
     * Set the measurement id.
     *
     * @param string $measurementId

Missing parameter comment

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

     * @return $this

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

     */
    public function setMeasurementId(string $measurementId): self
    {
        $this->service()?->setMeasurementId($measurementId);
        return $this;
    }

    /**
     * Set the API secret.
     *
     * @param string $apiSecret

Missing parameter comment

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

     * @return $this

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

     */
    public function setApiSecret(string $apiSecret): self
    {
        $this->service()?->setApiSecret($apiSecret);
        return $this;
    }

    public function __call(string $methodName, array $arguments): ?self

Missing doc comment for function __call()

    {
        $knownProperties = [
            'allowGoogleSignals' => 'allow_google_signals',
            'allowAdPersonalizationSignals' => 'allow_ad_personalization_signals',
            'campaignContent' => 'campaign_content',
            'campaignId' => 'campaign_id',
            'campaignMedium' => 'campaign_medium',
            'campaignName' => 'campaign_name',
            'campaignSource' => 'campaign_source',
            'campaignTerm' => 'campaign_term',
            'campaign' => 'campaign',
            'clientId' => 'client_id',
            'contentGroup' => 'content_group',
            'cookieDomain' => 'cookie_domain',
            'cookieExpires' => 'cookie_expires',
            'cookieFlags' => 'cookie_flags',
            'cookiePath' => 'cookie_path',
            'cookiePrefix' => 'cookie_prefix',
            'cookieUpdate' => 'cookie_update',
            'language' => 'language',
            'pageLocation' => 'page_location',
            'pageReferrer' => 'page_referrer',
            'pageTitle' => 'page_title',
            'sendPageView' => 'send_page_view',
            'screenResolution' => 'screen_resolution',
            'userId' => 'user_id',
        ];

        if (str_starts_with($methodName, 'set')) {
            $methodName = lcfirst(substr($methodName, 3));

            $service = $this->service();
            if ($service && !empty($knownProperties[$methodName])) {
                $service->setAdditionalQueryParam($knownProperties[$methodName], $arguments[0]);

                return $this;
            }
        }

        return null;
    }

    public function request(): BaseRequest

Missing doc comment for function request()

    {
        if ($this->_request === null) {
            $this->_request = new BaseRequest();

            $this->_request->setClientId(AnalyticsHelper::getClientId());

The method setClientId() does not exist on null.

            if (InstantAnalytics::$settings->sendUserId) {
                $userId = AnalyticsHelper::getUserId();

                if ($userId) {
                    $this->request()->setUserId($userId);
                }
            }
        }


        return $this->_request;

The expression return $this->_request could return the type null which is incompatible with the type-hinted return Br33f\Ga4\MeasurementProtocol\Dto\Request\BaseRequest. Consider adding an additional type-check to rule them out.

    }

    /**
     * Init the service used to send events
     */

Missing @return tag in function comment

    public function init(): void
    {
        $this->service();
        $this->request();
    }

    protected function service(): ?Service

Missing doc comment for function service()

    {
        if ($this->_service === null) {
            $settings = InstantAnalytics::$settings;
            $apiSecret = App::parseEnv($settings->googleAnalyticsMeasurementApiSecret);
            $measurementId = App::parseEnv($settings->googleAnalyticsMeasurementId);

            if (empty($apiSecret) || empty($measurementId)) {
                InstantAnalytics::$plugin->logAnalyticsEvent(
                    'API secret or measurement ID not set up for Instant Analytics',
                    [],
                    __METHOD__
                );
                $this->_service = false;

                return null;
            }
            $this->_service = new Service($apiSecret, $measurementId);

            $ga4Client = new HttpClient();
            $ga4Client->setClient(Craft::createGuzzleClient());
            $this->_service->setHttpClient($ga4Client);

            $request = Craft::$app->getRequest();
            try {
                $session = Craft::$app->getSession();
            } catch (MissingComponentException $exception) {
                $session = null;
            }

            $this->setPageReferrer($request->getReferrer());

            // Load any campaign values from session or request
            $campaignParams = [
                'utm_source' => 'CampaignSource',
                'utm_medium' => 'CampaignMedium',
                'utm_campaign' => 'CampaignName',
                'utm_content' => 'CampaignContent',
                'utm_term' => 'CampaignTerm',
            ];

            // Load them up for GA4
            foreach ($campaignParams as $key => $method) {
                $value = $request->getParam($key) ?? $session->get($key) ?? null;
                $method = 'set' . $method;

                $this->$method($value);

                if ($session && $value) {
                    $session->set($key, $value);
                }
            }

            // If SEOmatic is installed, set the affiliation as well
            if (InstantAnalytics::$seomaticPlugin && Seomatic::$settings->renderEnabled && Seomatic::$plugin->metaContainers->metaSiteVars !== null) {
                $siteName = Seomatic::$plugin->metaContainers->metaSiteVars->siteName;
                $this->setAffiliation($siteName);
            }
        }

        if ($this->_service === false) {
            return null;
        }

        return $this->_service;
    }
}