Custom Providers

A provider represents one social media platform, and gives Social Share a brand colour and icon for its buttons. A provider can also opt in to share buttons, follower counts and share counts. Social Share includes over 100 providers, and a custom provider adds a platform it doesn’t cover, or changes how an existing one works by extending its class.

Create the Provider Class

Extend verbb\socialshare\base\Provider. This example adds a share button for Lobsters. Create it at modules/sitemodule/LobstersProvider.php in a module autoloaded as modules\sitemodule.

<?php
namespace modules\sitemodule;

use craft\helpers\UrlHelper;
use verbb\socialshare\base\Provider;

class LobstersProvider extends Provider
{
    public static string $handle = 'lobsters';

    public static function displayName(): string
    {
        return 'Lobsters';
    }

    public static function supportsShareButton(): bool
    {
        return true;
    }

    public function getPrimaryColor(): ?string
    {
        return '#ac130d';
    }

    public function getIcon(): ?string
    {
        return '<svg viewBox="0 0 24 24" fill="currentColor"><rect width="24" height="24" rx="4"/></svg>';
    }

    public function getShareUrl(string $url, ?string $text = null, array $params = []): ?string
    {
        return UrlHelper::urlWithParams('https://lobste.rs/stories/new', array_filter(array_merge([
            'url' => $url,
            'title' => $text,
        ], $params)));
    }
}

Every provider needs a primary colour and an icon, because every provider can render a Button. $handle identifies the provider in templates, such as craft.socialShare.renderShareButton('lobsters'). Replace the placeholder square in getIcon() with the platform’s own SVG icon.

Register the Provider

Social Share finds providers through the registerProviderTypes event. Register your class from your module or plugin’s init() method.

use craft\events\RegisterComponentTypesEvent;
use modules\sitemodule\LobstersProvider;
use verbb\socialshare\services\Providers;
use yii\base\Event;

Event::on(Providers::class, Providers::EVENT_REGISTER_PROVIDER_TYPES, function(RegisterComponentTypesEvent $event) {
    $event->types[] = LobstersProvider::class;
});

Render a share button in any template to check it works. The button should use your colour and icon, and link to Lobsters with the current page’s URL.

{{ craft.socialShare.renderShareButton('lobsters', { text: entry.title }) }}

Add Counts

A provider can also report follower counts and share counts. Each needs a static method that opts in, and a method that fetches the number.

Support Follower Counts

If your provider supports fetching the number of followers for a given account identifier, you can configure the following:

public static function supportsFollowersCount(): bool
{
    return true;
}

public function getFollowersCount(string $account): ?int
{
    // Your logic to fetch the followers count
}

Support Share Counts

If your provider supports fetching the number of shares for a given URL, you can configure the following:

public static function supportsSharesCount(): bool
{
    return true;
}

public function getSharesCount(string $url): ?int
{
    // Your logic to fetch the shares count
}

Log Provider Errors

If a provider API request fails, log it with verbb\socialshare\helpers\ProviderLog, which records the provider handle and exception class without credentials or request data. Import ProviderLog and Throwable at the top of your class.

try {
    // Your logic to fetch the count
} catch (Throwable $exception) {
    ProviderLog::apiError($this, $exception);

    return null;
}

Don’t log raw exception messages or traces, access tokens, client secrets, OAuth codes or state, response bodies, request headers, or complete URLs and query strings. ProviderLog is separate from the provider base class so it doesn’t conflict with custom provider methods. Custom providers can keep returning null after a failed count request so templates retain the built-in failure behaviour.

Methods

Override these methods in your provider class as needed. Only getPrimaryColor() and getIcon() are needed for every provider, unless $handle matches a provider Auth already knows.