Shariff Bundle Laravel Package

Getting Started

A word before you start: this bundle is archived (3.3.0, December 2021, was the final release) and has no meaningful dependents. It still works as a thin Symfony wrapper around heise/shariff, and 3.3.0 modernised its support matrix to PHP 8.0+ and Symfony 5.4/6.0 (Symfony 4 and PHP 7 were dropped). That means it is genuinely usable on a Symfony 6 app without --ignore-platform-reqs hacks — but Symfony 7, PHP 8.3 tooling and any future security fixes are off the table. For a greenfield project, seriously consider wiring shariff-php (the backend) plus the @heise/shariff JS/CSS yourself — it is a few dozen lines and removes the abandoned dependency. Use the bundle if you already have a Symfony 5.4/6 app and want the Twig glue, the DI wiring and the count controller for free.

Minimal setup:

1. Install the package and its backend:

   composer require nucleos/shariff-bundle heise/shariff
   

   If Flex doesn't auto-register it, add Nucleos\ShariffBundle\NucleosShariffBundle::class => ['all' => true] to config/bundles.php.

2. Create config/packages/nucleos_shariff.yaml. This is where all the real work happens — the bundle mostly maps this file into a Heise\Shariff\Backend instance plus a Twig extension:

   nucleos_shariff:
     services:
       - Facebook
       - Reddit
       - Twitter
       - Whatsapp
     cache:
       ttl: 3600
   

   Only enable services you actually want counts from; each one adds an outbound HTTP call per uncached count request.

3. Publish Shariff's frontend assets. The bundle ships the PHP side, not the JS/CSS. Grab them from npm (@heise/shariff or the heise/shariff package) and copy shariff.min.js / shariff.min.css into public/. There is no assets:install magic here.

4. Render buttons in a Twig template — this is the first use case you'll hit:

   {{ shariff() }}
   

   The Twig function emits the <div class="shariff" data-services="..." data-backend-url="..."> markup pointing at the bundle's built-in count endpoint. Include the JS/CSS you published and Shariff handles the rest.

Where to look first in the source: DependencyInjection/Configuration.php (the config schema), the Shariff controller (the /shariff count endpoint), and the Twig extension (rendering + defaults).

Implementation Patterns

Server-side counts, not client-side. The whole point of Shariff is privacy: the browser never talks to Facebook/Twitter directly. The bundle registers a controller (typically under a path like /shariff) that the JS calls, and the controller delegates to Heise\Shariff\Backend, which fetches counts from the enabled services. Keep that route behind your normal firewall/anonymous access rules as appropriate.

Override the default markup via a Twig partial. Rather than fighting the Twig function's options, render your own <div class="shariff"> in a reused partial (templates/_shariff.html.twig) and pass data-services, data-theme, data-orientation, data-url. This is the pattern that ages best if you later drop the bundle.

Configuration-as-deployment. Keep the service list in nucleos_shariff.yaml per environment. In dev you may want cache.ttl: 0 so you're not staring at stale counts while iterating; in prod set a longer TTL (e.g. 3600) because most share-count APIs rate-limit aggressively.

Caching backend. shariff-php caches via a CacheInterface. The bundle wires its own adapter by default. If you run multiple web nodes, configure a shared cache (or override the cache adapter service) so counts are consistent and you don't hammer external APIs from every pod.

CSP and privacy policies. Because everything is same-origin, you usually don't need connect-src allowances for social networks — that's the selling point. But do add the Shariff CSS/JS to your CSP script-src/style-src self allow-list, and document the single /shariff endpoint in your privacy notice (some auditors want it named).

Testing. You don't want unit tests hitting Facebook. Override the Heise\Shariff\Backend service in config/services_test.yaml with a stub returning fixed counts, or skip the Twig function in tests and assert on config/markup instead. The bundle's own services are constructor-injected, so a decoration of the backend service is the clean seam.

Gotchas and Tips

• Pin the bundle to 3.3.x and read the constraint before upgrading. 3.3.0 dropped Symfony 4 and PHP 7; if you are still on Symfony 4.4 the resolver will silently keep you on 3.2.x. Conversely, Symfony 7 is not supported by any release and never will be. Budget for the fork/escape-hatch path below before you build a long-term dependency on this.
• Rendering a block without a template now throws. 3.3.0 added a LogicException when the Twig block is rendered with no template configured. If you call the block-rendering entry point directly (rather than {{ shariff() }}), make sure the template option is set — the older failure mode was a silently-empty render, so a hard exception can surface as a new 500 after upgrade. It's a good failure, but it is a behaviour change.
• The facebook, twitter (now X), and google share-count APIs have changed dramatically since 2021. Google+ is dead, X's count endpoint has been restricted, Facebook's Graph count changed. Expect some configured services to silently return 0 — that is not a bundle bug, it's upstream API rot. Verify each service's count endpoint independently with curl before blaming the integration.
• Missing assets is the #1 "it doesn't work." The Twig function renders a div but nothing visible appears until shariff.min.js runs. Check the browser console for a 404 on the JS/CSS first.
• Counts are cached aggressively and by default. If you change the service list and see stale results, clear the cache pool (or the bundle's cache directory) — the count endpoint doesn't cache-bust on config changes.
• Curl is a hard requirement. shariff-php fetches counts with cURL. In a minimal Docker image without ext-curl you get empty counts and only a log line. Verify php -m | grep curl.
• Debugging a zero count. Hit the backend route directly (curl 'https://yoursite/shariff?url=https://example.com/article') to see whether the problem is frontend wiring or the backend fetch. Shariff's JS will happily render 0 with no error.
• Extension points. The Twig extension and the backend service are both normal Symfony services; decorate or override them via config/services.yaml rather than patching the vendor directory. This is the one real advantage over using shariff-php directly — you get DI wiring and Twig defaults for free.
• Migration escape hatch. If you're on a maintained Symfony (7.x), the only sustainable move is to drop the bundle: register Heise\Shariff\Backend as a service yourself, expose a small controller returning json_encode($backend->getCounts($url)), and render the markup in Twig with no bundle at all. You lose ~nothing — the bundle's surface is a config tree, one controller and one Twig function — and gain Symfony 7 / PHP 8.3+ support. Doing this on 3.3.0 while it still works is far cheaper than doing it under pressure later.