Upload customer lists to Google Ads

Author: loevgaard

.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(find:*)",
+      "Bash(rg:*)"
+    ],
+    "deny": []
+  }
+}

CLAUDE.md

@@ -0,0 +1,113 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a Sylius plugin that integrates Google Ads conversion tracking with Sylius e-commerce stores. The plugin uses the Google Ads API directly (server-side) instead of JavaScript tracking, providing better control over consent, conversion values, and avoiding ad blockers.
+
+## Development Commands
+
+### Testing
+```bash
+# Run all tests
+./vendor/bin/phpunit
+
+# Run specific test
+./vendor/bin/phpunit tests/Resolver/CustomerIdsResolverTest.php
+```
+
+### Code Quality
+```bash
+# Code style checking
+composer check-style
+
+# Fix code style issues
+composer fix-style
+
+# Static analysis
+composer analyse
+```
+
+### Database Operations
+```bash
+# Create migration after model changes
+php bin/console doctrine:migrations:diff
+
+# Run migrations
+php bin/console doctrine:migrations:migrate
+```
+
+### Plugin Console Commands
+```bash
+# Process Google Ads conversions (run regularly, e.g., every 5 minutes)
+php bin/console setono:sylius-google-ads:process-conversions
+
+# Prune old conversions from database (run daily)
+php bin/console setono:sylius-google-ads:prune-conversions
+```
+
+## Architecture
+
+### Core Components
+
+**Models**: Connection, Conversion, CustomerList, ConnectionMapping, MerchantMapping
+- Connection: Stores Google Ads API credentials and configuration
+- Conversion: Represents tracked conversions with state workflow
+- CustomerList: Manages Google Ads customer lists for remarketing
+
+**Processing Flow**:
+1. **Event Capture**: PurchaseListener captures order events
+2. **Conversion Creation**: ConversionFactory creates conversion records
+3. **Qualification**: QualificationVoters determine if conversion should be processed
+4. **Processing**: ConversionProcessor handles API calls to Google Ads
+5. **State Management**: ConversionWorkflow manages conversion states
+
+**Message System**: Uses Symfony Messenger for async processing
+- ProcessConversion: Handles individual conversion processing
+- ProcessCustomerList/UploadCustomerList: Manages customer list operations
+
+### Key Directories
+
+- `src/Model/`: Core domain models and interfaces
+- `src/ConversionProcessor/`: Conversion processing logic with qualification voters
+- `src/Message/`: Symfony Messenger commands and handlers
+- `src/Client/`: Google Ads API client wrapper and resources
+- `src/EventSubscriber/`: Event-driven processing subscribers
+- `src/Factory/`: Object creation factories
+- `src/Repository/`: Data access layer
+- `src/Resources/config/`: Service definitions and configuration
+
+### Google Ads Integration
+
+The plugin integrates with Google Ads through:
+- **OAuth2 Flow**: Managed via Controller/Action classes for setup
+- **API Client**: Wraps Google Ads PHP library with custom resource classes
+- **Conversion Tracking**: Server-side conversion uploads with user identifiers
+- **Customer Lists**: Audience management for remarketing campaigns
+
+### State Management
+
+Conversions follow a workflow with states:
+- Created → Processing → Delivered/Failed
+- Managed by ConversionWorkflow class
+- Supports retry logic for failed conversions
+
+## Configuration
+
+Plugin configuration is in `src/Resources/config/app/config.yaml` and requires:
+- Google Ads API credentials (client ID, secret, developer token)
+- Customer ID mapping for multi-account setups
+- Conversion action mapping for different event types
+
+## Testing
+
+The plugin includes both unit tests and integration tests. Live testing can be enabled by setting `GOOGLE_ADS_LIVE=1` and providing real API credentials in phpunit.xml.
+
+## Important Notes
+
+- Customer Lists feature is marked as experimental
+- Requires gRPC PHP extension for optimal performance
+- Uses Doctrine ORM for persistence
+- Integrates with Sylius workflow and event systems
+- Supports multi-channel and multi-customer configurations

README.md

@@ -97,6 +97,12 @@ Now the plugin is installed. Please read the next section to learn how to use it
 
 To start using the plugin, go to https://your-domain.com/admin/google-ads and follow the instructions.
 
+# Backward compatibility
+
+The plugin adheres to semantic versioning, however, if a feature is `experimental` it is not included in the promise.
+
+Right now the customer lists feature is experimental.
+
 [ico-version]: https://poser.pugx.org/setono/sylius-google-ads-plugin/v/stable
 [ico-license]: https://poser.pugx.org/setono/sylius-google-ads-plugin/license
 [ico-github-actions]: https://github.com/Setono/SyliusGoogleAdsPlugin/workflows/build/badge.svg

composer.json

@@ -14,19 +14,20 @@
         "doctrine/dbal": "^2.13 || ^3.8",
         "doctrine/orm": "^2.7",
         "doctrine/persistence": "^1.3 || ^2.2 || ^3.2",
-        "google/auth": "^1.26",
-        "google/gax": "^1.19",
+        "google/auth": "^1.44",
+        "google/gax": "^1.35.1",
         "googleads/google-ads-php": "^27.2",
         "knplabs/knp-menu": "^3.1",
-        "ocramius/doctrine-batch-utils": "^2.4",
+        "ocramius/doctrine-batch-utils": "^2.6",
         "psr/event-dispatcher": "^1.0",
         "psr/log": "^1.0 || ^2.0 || ^3.0",
-        "setono/composite-compiler-pass": "^1.1",
-        "setono/doctrine-orm-trait": "^1.0",
+        "setono/composite-compiler-pass": "^1.2",
+        "setono/doctrine-orm-trait": "^1.2",
         "sylius/channel": "^1.0",
         "sylius/channel-bundle": "^1.0",
         "sylius/core": "^1.0",
         "sylius/core-bundle": "^1.0",
+        "sylius/customer": "^1.0",
         "sylius/order": "^1.0",
         "sylius/resource-bundle": "^1.6",
         "sylius/ui-bundle": "^1.0",

psalm.xml

@@ -3,17 +3,18 @@
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xmlns="https://getpsalm.org/schema/config"
     xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"
-    phpVersion="8.1"
-    errorLevel="1"
     findUnusedBaselineEntry="false"
     findUnusedPsalmSuppress="false"
     findUnusedCode="false"
     findUnusedVariablesAndParams="false"
+    phpVersion="8.1"
+    errorLevel="1"
 >
     <projectFiles>
         <directory name="src"/>
         <directory name="tests"/>
         <ignoreFiles>
+            <file name="src/Message/Handler/UploadCustomersHandler.php"/>
             <directory name="tests/Application"/>
             <directory name="vendor"/>
         </ignoreFiles>
@@ -24,7 +25,6 @@
     </plugins>
     <issueHandlers>
         <PluginIssue name="QueryBuilderSetParameter" errorLevel="info"/>
-        <UnnecessaryVarAnnotation errorLevel="suppress"/> <!-- We use unnecessary var annotations to aid the IDE -->
         <TooManyTemplateParams>
             <errorLevel type="suppress">
                 <directory name="src/Factory"/> <!-- Sylius added @template annotations in later editions -->
@@ -33,4 +33,12 @@
         </TooManyTemplateParams>
         <RedundantConditionGivenDocblockType errorLevel="suppress"/>
     </issueHandlers>
+    <forbiddenFunctions>
+        <function name="dd"/>
+        <function name="dump"/>
+        <function name="echo"/>
+        <function name="exit"/>
+        <function name="var_dump"/>
+        <function name="print_r"/>
+    </forbiddenFunctions>
 </psalm>

src/Client/Client.php

@@ -0,0 +1,83 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Setono\SyliusGoogleAdsPlugin\Client;
+
+use Google\Ads\GoogleAds\Lib\V19\GoogleAdsClient;
+use Google\Ads\GoogleAds\V19\Services\GetGoogleAdsFieldRequest;
+use Google\Ads\GoogleAds\V19\Services\SearchGoogleAdsStreamRequest;
+use Setono\SyliusGoogleAdsPlugin\Client\Resource\OfflineUserDataJobsResource;
+use Setono\SyliusGoogleAdsPlugin\Client\Resource\OfflineUserDataJobsResourceInterface;
+use Setono\SyliusGoogleAdsPlugin\Client\Resource\ResourceMetadata;
+use Setono\SyliusGoogleAdsPlugin\Client\Resource\UserListCustomerTypesResource;
+use Setono\SyliusGoogleAdsPlugin\Client\Resource\UserListCustomerTypesResourceInterface;
+use Setono\SyliusGoogleAdsPlugin\Client\Resource\UserListsResource;
+use Setono\SyliusGoogleAdsPlugin\Client\Resource\UserListsResourceInterface;
+
+final class Client implements ClientInterface
+{
+    private ?OfflineUserDataJobsResourceInterface $offlineUserDataJobsResource = null;
+
+    private ?UserListsResourceInterface $userListsResource = null;
+
+    private ?UserListCustomerTypesResourceInterface $userListCustomerTypesResource = null;
+
+    public function __construct(
+        private readonly GoogleAdsClient $googleAdsClient,
+        private readonly string $customerId,
+    ) {
+    }
+
+    public function offlineUserDataJob(): OfflineUserDataJobsResourceInterface
+    {
+        if (null === $this->offlineUserDataJobsResource) {
+            $this->offlineUserDataJobsResource = new OfflineUserDataJobsResource($this, $this->googleAdsClient);
+        }
+
+        return $this->offlineUserDataJobsResource;
+    }
+
+    public function userLists(): UserListsResourceInterface
+    {
+        if (null === $this->userListsResource) {
+            $this->userListsResource = new UserListsResource($this, $this->googleAdsClient);
+        }
+
+        return $this->userListsResource;
+    }
+
+    public function userListCustomerTypes(): UserListCustomerTypesResourceInterface
+    {
+        if (null === $this->userListCustomerTypesResource) {
+            $this->userListCustomerTypesResource = new UserListCustomerTypesResource($this, $this->googleAdsClient);
+        }
+
+        return $this->userListCustomerTypesResource;
+    }
+
+    public function search(string $query): SearchResponse
+    {
+        return SearchResponse::fromServerStream($this->googleAdsClient->getGoogleAdsServiceClient()->searchStream(
+            SearchGoogleAdsStreamRequest::build($this->customerId, $query),
+        ));
+    }
+
+    public function getResourceMetadata(string $resourceName): ResourceMetadata
+    {
+        if (!str_contains($resourceName, '/')) {
+            $resourceName = 'googleAdsFields/' . $resourceName;
+        }
+
+        $field = $this->googleAdsClient->getGoogleAdsFieldServiceClient()->getGoogleAdsField(
+            GetGoogleAdsFieldRequest::build($resourceName),
+        );
+
+        return ResourceMetadata::fromGoogleAdsField($field);
+    }
+
+    public function getCustomerId(): string
+    {
+        return $this->customerId;
+    }
+}

src/Client/ClientInterface.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Setono\SyliusGoogleAdsPlugin\Client;
+
+use Setono\SyliusGoogleAdsPlugin\Client\Resource\UserListCustomerTypesResourceInterface;
+use Setono\SyliusGoogleAdsPlugin\Client\Resource\UserListsResourceInterface;
+
+interface ClientInterface
+{
+    public function userLists(): UserListsResourceInterface;
+
+    public function userListCustomerTypes(): UserListCustomerTypesResourceInterface;
+
+    public function search(string $query): SearchResponse;
+
+    public function getCustomerId(): string;
+}

src/Client/Resource/AbstractResource.php

@@ -0,0 +1,85 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Setono\SyliusGoogleAdsPlugin\Client\Resource;
+
+use Google\Ads\GoogleAds\Lib\V19\GoogleAdsClient;
+use Google\Protobuf\Internal\Message;
+use Setono\SyliusGoogleAdsPlugin\Client\ClientInterface;
+use Webmozart\Assert\Assert;
+
+/**
+ * @template T of Message
+ */
+abstract class AbstractResource
+{
+    public function __construct(
+        protected readonly ClientInterface $client,
+        protected readonly GoogleAdsClient $googleAdsClient,
+    ) {
+    }
+
+    public function createOrUpdate(?string $resourceName, callable $update, callable $create): string
+    {
+        if (!$this instanceof ReadableResourceInterface) {
+            throw new \RuntimeException(sprintf('The resource must implement %s', ReadableResourceInterface::class));
+        }
+
+        if (!$this instanceof UpdatableResourceInterface) {
+            throw new \RuntimeException(sprintf('The resource must implement %s', UpdatableResourceInterface::class));
+        }
+
+        $obj = null;
+
+        if (null !== $resourceName) {
+            $obj = $this->get($resourceName);
+        }
+
+        if (null === $obj) {
+            /** @psalm-suppress UnsafeInstantiation */
+            $obj = new (self::getResourceClass());
+
+            $create($obj);
+            $update($obj);
+
+            $resourceName = $this->create($obj);
+        } else {
+            $update($obj);
+            $resourceName = $this->update($obj);
+        }
+
+        return $resourceName;
+    }
+
+    /**
+     * @return class-string<T>
+     */
+    abstract protected static function getResourceClass(): string;
+
+    protected function handleMutateResponse(object $response): string
+    {
+        if (!method_exists($response, 'getResults')) {
+            throw new \RuntimeException('The response does not have a results method');
+        }
+
+        /** @var mixed $results */
+        $results = $response->getResults();
+        Assert::isInstanceOf($results, \Traversable::class);
+
+        $results = iterator_to_array($results, false);
+        Assert::count($results, 1);
+
+        $result = $results[0];
+        Assert::object($result);
+        if (!method_exists($result, 'getResourceName')) {
+            throw new \RuntimeException('The result does not have a resource name method');
+        }
+
+        /** @var mixed $resourceName */
+        $resourceName = $result->getResourceName();
+        Assert::string($resourceName);
+
+        return $resourceName;
+    }
+}