Knp Piwik Client Laravel Package

Getting Started

This is a framework-agnostic, archived (last tag 2013) PHP client for the Piwik/Matomo HTTP API. There is no Laravel service provider, config file, facade, or published migrations — you wire it into the container yourself.

1. Decide whether you can install it at all. composer require knplabs/knp-piwik-client will likely fail on a modern Laravel app because it depends on Guzzle 3.x. Check the composer.json in the repo before trying; if it conflicts, composer require --dev it into a throwaway project to read the source, then copy the 2–3 real classes into app/Services/Analytics/.
2. Read these files first: src/Knp/PiwikClient/Client.php (the API surface — essentially a call($method, array $params) wrapper) and src/Knp/PiwikClient/Connection/HttpConnection.php (how it talks to index.php?module=API). Everything else is exception plumbing.
3. Get credentials. In Matomo go to Administration → Personal → Security → API, generate a token_auth, and note the site IDs under Administration → Websites → Manage. The token needs at least view on the sites you'll query.
4. Configure. Piwik was renamed Matomo in 2018; point the base URL at https://matomo.example.com/ (the client appends index.php). Drop these into config/services.php under a matomo key and read from env().
5. First use case: yesterday's traffic for the marketing dashboard. Construct the connection + client once, call VisitsSummary.get with idSite, period=day, date=yesterday, and stash the result in cache.

Implementation Patterns

Wrap it, don't sprinkle it. Bind a single MatomoClient wrapper as a singleton in AppServiceProvider and expose typed methods (visitsYesterday(int $siteId): int, topPages(int $siteId, string $period): array). The upstream call() string-method API is easy to typo and hard to mock in tests; your wrapper gives you a seam for Http::fake() alternatives.

// AppServiceProvider::register()
$this->app->singleton(Analytics::class, fn () => new Analytics(
    baseUrl: config('services.matomo.url'),
    token:   config('services.matomo.token'),
));

Use the connection as the extension point. ConnectionInterface is the one genuinely useful abstraction here: keep the Client logic and substitute a new HttpConnection built on Illuminate\Support\Facades\Http (or Guzzle 7). That gives you retries, timeouts, PSR-18, and Laravel test fakes without inheriting a 2013 Guzzle dependency.

Cache every report. Analytics data is not real-time-critical. Key the cache on md5($method . serialize($params)) with a 15–60 minute TTL:

return Cache::remember("matomo:{$site}:{$method}:".md5(serialize($params)), 1800, fn () => ...);

Batch by site, not by page. Loop over configured site IDs in a queued job or an artisan command (php artisan analytics:warm) and populate the cache on a schedule (->hourly()), so no user request ever waits on Matomo.

Know the common calls:

date accepts yesterday, today, last7, last30, YYYY-MM-DD, or YYYY-MM-DD,YYYY-MM-DD with period=range.

Segment support. Pass segment=... for filtered views; just make sure the segment string is part of your cache key or you'll cross-contaminate reports.

Gotchas and Tips

• The Guzzle 3 dependency is the real risk. It's incompatible with Guzzle 6/7 and modern PSR-7 tooling. Plan on porting the connection layer rather than resolving Composer conflicts.
• Errors come back as HTTP 200. Matomo returns a JSON/XML body with a result: error / message field (e.g. "You can't access this resource") rather than a 4xx. Every wrapper method must inspect the payload, not just the status code.
• token_auth is a full-access secret and this client passes it as a query parameter. It will end up in access logs, proxies, and Storage::logs. Never log the request URL, and rotate the token if it leaks.
• Decoding is on you. Depending on which revision you copy, the client may return the raw Guzzle response body. Confirm with a var_dump on your first call and json_decode accordingly — don't assume an array.
• Timezones. Matomo evaluates yesterday/today in the site's timezone, not config('app.timezone'). Set the site timezone in Matomo, or pass explicit dates calculated in that zone.
• today + period=day is the slowest query because the report archive is invalidated constantly. Use yesterday or last7 wherever you can, and cache harder for today.
• Pagination. filter_limit=-1 returns "everything" and can produce multi-megabyte responses on busy sites. Use filter_limit=50 with filter_offset and page through.
• No tests, no maintenance. Anything you build on top needs its own test suite. If you must keep it, pin the exact commit.
• Archived = treat as a reference implementation. With 17 stars and zero dependents, nobody is watching for breakage. For a greenfield Laravel app, a ~40-line wrapper over Http::withQueryParameters(...)->get("{$base}/index.php", ['module' => 'API', 'method' => ..., 'format' => 'json', ...]) is simpler, safer, and fully testable.