Feature: Affiliate Link Management

The Affiliate Link Management feature in PriceBuddy automatically appends affiliate tracking codes to product URLs for specific online retailers. This system is designed to support the development of the project by generating revenue through affiliate partnerships. It is enabled by default but can be disabled by users who prefer not to use affiliate links.

The core functionality involves parsing a product URL, checking it against a predefined list of affiliate sites, and if a match is found, appending the configured affiliate query parameters to the URL. This process is handled transparently when a user accesses a product's "buy" link.

Sources: README.md:80-84, app/Services/Helpers/AffiliateHelper.php

Configuration

The behavior of the affiliate link system is controlled through a configuration file and an environment variable.

Sources: config/affiliates.php, README.md:80-84, tests/Feature/Models/UrlTest.php:121-131

Enabling/Disabling the Feature

The entire feature can be enabled or disabled globally.

This environment variable controls the enabled key within the affiliates.php configuration file.

Sources: README.md:82-84, app/Services/Helpers/AffiliateHelper.php:16-18

Site-Specific Configuration

The config/affiliates.php file contains an array of site-specific configurations. Each entry in the sites array defines the rules for a particular set of domains.

A test case in UrlTest.php demonstrates how this configuration is structured and used. For example, configurations for eBay and Amazon are present by default.

Sources: config/affiliates.php, tests/Feature/Models/UrlTest.php:133-142

Configuration Structure

Example Configuration

The following snippet, reconstructed from test cases, shows how sites like eBay and Amazon are configured.

// config/affiliates.php
return [
    'enabled' => env('AFFILIATE_ENABLED', true),
    'sites' => [
        [
            'domains' => ['ebay.com.au'],
            'query_params' => [
                'mkrid' => '705-53470-19255-0',
                'mkcid' => '1',
                'campid' => '5339100273',
                'siteid' => '15',
                'toolid' => '10001',
                'mkevt' => '1',
            ],
        ],
        [
            'domains' => ['amazon.com.au'],
            'query_params' => ['tag' => 'pricebuddy-22'],
        ],
        [
            'domains' => ['amazon.com'],
            'query_params' => ['tag' => 'pricebuddy07-20'],
        ],
    ],
];

Sources: tests/Feature/Models/UrlTest.php:133-142, config/affiliates.php

Core Logic

The affiliate link generation is primarily handled by the AffiliateHelper service and triggered via an accessor on the Url model.

AffiliateHelper Service

This service contains the logic for parsing a URL and applying the correct affiliate parameters based on the configuration.

Sources: app/Services/Helpers/AffiliateHelper.php

The diagram below shows the structure of the AffiliateHelper class.

Key Methods:

• parseUrl(string $url): This is the main public method. It takes a raw URL string, parses it, and returns a new URL string with affiliate parameters if applicable.
• getSettingsFromUrl(Uri $uri): This private method checks if the feature is enabled and then attempts to find a matching site configuration for the given URL's host. It handles stripping www. from the host for broader matching.
• getConfig(string $key, mixed $default): A utility to retrieve values from the loaded affiliate configuration.

Sources: app/Services/Helpers/AffiliateHelper.php:9-43

URL Modification Flow

The process is initiated when the buy_url attribute of a Url model instance is accessed. This triggers an accessor which, in turn, calls the AffiliateHelper.

The following sequence diagram illustrates the flow:

The logic within the parseUrl method can be visualized as follows:

Testing

The functionality is validated through feature tests in tests/Feature/Models/UrlTest.php. These tests ensure that affiliate codes are added correctly under various conditions.

Sources: tests/Feature/Models/UrlTest.php:121-142

A sample test demonstrates how a mocked configuration is used to verify the URL modification:

// tests/Feature/Models/UrlTest.php

public function test_affiliate_code_gets_added_to_url()
{
    $url = Url::factory()->create(['url' => 'https://example.com/product?foo=bar#baz']);

    config([
        'affiliates.enabled' => true,
        'affiliates.sites' => [
            [
                'domains' => ['example.com'],
                'query_params' => ['ref' => '123'],
            ],
        ],
    ]);

    $this->assertEquals('https://example.com/product?foo=bar&ref=123#baz', $url->buy_url);
}

Sources: tests/Feature/Models/UrlTest.php:121-131