Shariff Bundle Laravel Package

Getting Started

This is a thin Symfony 2-era wrapper around the heise/shariff PHP backend, so "getting started" is really three steps: install, register, point shariff.js at the bundle's route.

1. Install — composer require valiton/shariff-bundle. It pulls in heise/shariff (the privacy-friendly share-count backend) and Guzzle as the HTTP client.
2. Register the bundle in app/AppKernel.php:

   new Valiton\ShariffBundle\ValitonShariffBundle(),
   

3. Import routing in app/config/routing.yml:

   valiton_shariff:
       resource: "@ValitonShariffBundle/Resources/config/routing.yml"
   

   (Check the actual filename — it may be routing.xml. This bundle predates routing.yml being the default.)
4. Configure backends in app/config/config.yml under the bundle's extension key (likely valiton_shariff: — confirm against DependencyInjection/Configuration.php). You need at minimum a cache directory, an allowed-domains list, and which services to query:

   valiton_shariff:
       cache:
           ttl: 3600
           directory: "%kernel.cache_dir%/shariff"
       domains: ["example.com"]
       services: ["Facebook", "Twitter", "LinkedIn"]
   

5. First use case — drop shariff.min.js + CSS into your template and set data-backend-url="/shariff" (or whatever path the bundle's routing file exposes). Every social button on the page now fetches its count from your server instead of from Facebook/Twitter directly, which is the entire point of Shariff: no third-party requests, no user tracking.

Where to look first when something doesn't work: Resources/config/ (services, routing, DI extension), then Heise\Shariff\Backend\Shariff in vendor/heise/shariff — the bundle is a thin DI layer, the real logic is there.

Implementation Patterns

Server-side endpoint (the default path). The bundle's controller returns JSON of the form {"facebook": 12, "twitter": 4, "linkedin": 0}. shariff.js calls it as GET /shariff?url=<encoded>&services[]=facebook&services[]=twitter. Anything you do on the front end is just shariff.js configuration — the bundle's job ends at the JSON.

Injecting the backend service. For anything beyond the bundled controller (a JSON API, a queue worker warming counts, a per-article "popularity" score), pull the Shariff service out of the container and call getCounts($url). This is the real day-to-day use: you aren't limited to the share buttons.

Cache aggressively. Counts change slowly and the backend makes one outbound HTTP call per service per URL. Set ttl to 600–3600s and make the cache directory a shared, writable path — not %kernel.cache_dir% if you run multiple app servers. In production this is the difference between a fast endpoint and one that times out under load.

Per-environment backend selection. Enable Facebook/Twitter only where you can supply credentials; leave them off in dev so the endpoint doesn't fail on missing API keys. Keep domains restricted to your own hosts — it's an SSRF guard as much as a whitelist.

Rendering fallbacks. Shariff returns 0 for a service that failed or has no count; templates should treat 0 as "hide the count", not "show zero shares". Decide this once in Twig rather than per-button.

Testing. A functional test that hits the route with ?url=... and asserts valid JSON is worth more than unit-testing the wrapper — it catches the routing/DI wiring, which is the only thing this bundle actually owns.

Gotchas and Tips

• It's a Symfony 2 bundle, effectively unmaintained (0 stars, 0 dependents). Before adopting, check whether it registers via AppKernel only (i.e. won't work on Symfony 4+/Flex without conversion) and whether its composer.json still allows your PHP version. If it's a hard blocker, use heise/shariff directly — you lose roughly 60 lines of bundle boilerplate and gain a maintained dependency. That's usually the right trade.
• Every enabled service is an outbound HTTP request per cache miss. Rate limits, API deprecations, and timeouts are the normal failure mode, not exceptions in your code. Set a short Guzzle timeout and make sure the endpoint degrades to {} rather than a 500 when a network call fails.
• Credential-dependent backends. Twitter, LinkedIn, and Facebook counts require app credentials in the config; the API surfaces have changed repeatedly since this bundle was written. Verify each backend in heise/shariff still supports the service you want before configuring it.
• Cache directory permissions are the most common first-run failure. The directory must exist and be writable by the web user; the bundle typically won't create it.
• Route/path assumptions in shariff.js. If you mount the endpoint somewhere other than the default (behind a locale prefix, a CDN, or an API subdomain), set data-backend-url to an absolute URL. Cross-origin backends need CORS headers on the JSON response, which the bundle's controller almost certainly does not set — add them yourself.
• Configuration key guessing is a real cost here. With no docs and no maintainers, read DependencyInjection/Configuration.php directly rather than trusting README examples or blog posts; config trees in this era differed by a character or two (valiton_shariff vs shariff) and silently ignored unknown keys.
• Extension point if you need one: override the bundle's service definition in your app config to swap in a custom backend or a caching decorator. That's more maintainable than forking the bundle, and it survives a composer update.