Upload customer lists to Google Ads

Author: loevgaard

CLAUDE.md

@@ -0,0 +1,106 @@
+# 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
+```
+
+### 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.
+
+- Use prophecy for mocks
+
+## 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

@@ -9,24 +9,25 @@
     ],
     "require": {
         "php": ">=8.1",
-        "brick/phonenumber": "^0.5.0",
+        "brick/phonenumber": "^0.7.0",
         "doctrine/collections": "^1.6",
         "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",
@@ -55,6 +56,7 @@
         "jms/serializer-bundle": "^4.2",
         "lexik/jwt-authentication-bundle": "^2.17",
         "matthiasnoback/symfony-config-test": "^4.3 || ^5.1",
+        "phpspec/prophecy-phpunit": "^2.4",
         "setono/client-bundle": "^1.1",
         "setono/sylius-plugin-pack": "^1.14",
         "sylius-labs/polyfill-symfony-security": "^1.1.2",

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,68 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Setono\SyliusGoogleAdsPlugin\Client;
+
+use Google\Ads\GoogleAds\Lib\V19\GoogleAdsClient;
+use Google\Ads\GoogleAds\V19\Services\SearchGoogleAdsStreamRequest;
+use Setono\SyliusGoogleAdsPlugin\Client\Resource\OfflineUserDataJobsResource;
+use Setono\SyliusGoogleAdsPlugin\Client\Resource\OfflineUserDataJobsResourceInterface;
+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 offlineUserDataJobs(): 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 getCustomerId(): string
+    {
+        return $this->customerId;
+    }
+}

src/Client/ClientInterface.php

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