Sylius Google Ads Plugin Development

Expert guidance for working with the Setono/SyliusGoogleAdsPlugin codebase - a Sylius plugin that integrates Google Ads conversion tracking using server-side API calls instead of JavaScript tracking.

What This Skill Does

This skill provides comprehensive guidance for developing, testing, and maintaining the Sylius Google Ads Plugin. It covers the plugin's architecture, development workflows, testing practices, and integration patterns with both Sylius and the Google Ads API.

Project Context

The plugin enables Sylius e-commerce stores to track conversions and manage customer lists in Google Ads through server-side API integration. This approach provides better control over consent management, conversion values, and avoids ad blocker limitations compared to client-side JavaScript tracking.

Development Workflow

1. Running Tests

When testing code changes:

```bash

Run all tests

./vendor/bin/phpunit

Run specific test file

./vendor/bin/phpunit tests/Resolver/CustomerIdsResolverTest.php

Run with live Google Ads API (requires credentials in phpunit.xml)

GOOGLE_ADS_LIVE=1 ./vendor/bin/phpunit

```

**Testing guidelines:**

2. Code Quality Checks

Before committing changes, run:

```bash

Check code style compliance

composer check-style

Auto-fix code style issues

composer fix-style

Run static analysis

composer analyse

```

Always ensure all three commands pass before submitting changes.

3. Understanding the Architecture

**Core Models** (located in `src/Model/`):

**Processing Flow**:

1. **Event Capture**: `PurchaseListener` captures Sylius order completion events

2. **Conversion Creation**: `ConversionFactory` creates conversion records in the database

3. **Qualification**: `QualificationVoters` determine if conversion should be sent to Google Ads

4. **Async Processing**: Symfony Messenger dispatches `ProcessConversion` message

5. **API Upload**: `ConversionProcessor` sends conversion data to Google Ads API

6. **State Management**: `ConversionWorkflow` transitions conversion through states (Created → Processing → Delivered/Failed)

**Message System** (located in `src/Message/`):

4. Working with Google Ads Integration

**Key integration components:**

**OAuth2 Setup** (`src/Controller/Action/`):

**API Client** (`src/Client/`):

**Conversion Tracking**:

**Customer Lists** (marked as experimental):

5. Configuration Management

Plugin configuration is stored in `src/Resources/config/app/config.yaml` and includes:

Service definitions are in `src/Resources/config/services.yaml`.

6. State Management and Workflow

Conversions use Symfony Workflow with these states:

The `ConversionWorkflow` class manages state transitions and business rules.

Key Directories

Important Technical Notes

Common Tasks

Adding a New Conversion Type

1. Define conversion action in Google Ads

2. Update ConversionFactory to handle new event type

3. Add mapping configuration in config.yaml

4. Create qualification voter if special logic needed

5. Add tests for new conversion type

Debugging API Issues

1. Check conversion state in database

2. Review Messenger failed queue: `bin/console messenger:failed:show`

3. Enable debug logging for Google Ads client

4. Use live testing mode to reproduce with real API

Extending Qualification Logic

1. Create new voter class implementing `QualificationVoterInterface`

2. Register voter in services.yaml with priority tag

3. Add unit tests for voter logic

4. Document voter purpose and behavior

Examples

Running Tests for a Specific Component

```bash

Test the customer IDs resolver

./vendor/bin/phpunit tests/Resolver/CustomerIdsResolverTest.php

Test conversion processing with code coverage

./vendor/bin/phpunit --coverage-html coverage/ tests/ConversionProcessor/

```

Code Quality Workflow

```bash

Complete pre-commit check

composer check-style && composer analyse && ./vendor/bin/phpunit

Fix style issues automatically

composer fix-style

```

Constraints