- How do I install robbrazier/piwik in a Laravel application?
- Install it with Composer using composer require robbrazier/piwik, then publish the package config file with the vendor:publish command so the Piwik settings are available to your app. The service provider and facade are registered through Laravel package discovery, so manual registration is usually unnecessary. After publishing, set PIWIK_URL, PIWIK_SITE_ID, and optionally PIWIK_TOKEN_AUTH in your .env file. If you already know Matomo, a proof of concept typically takes hours rather than days.
- Which Laravel and PHP versions does robbrazier/piwik support?
- Support depends on the composer constraints of the current release, which mostly wrap the underlying Matomo PHP tracker library rather than the framework itself. Check the package's composer.json for its php and laravel/framework requirements before assuming it covers your runtime, particularly on PHP 8.x and newer Laravel majors. Because the package is a thin adapter, the tracker library's constraints usually set the real compatibility ceiling.
- How do I configure PIWIK_URL, PIWIK_SITE_ID, and PIWIK_TOKEN_AUTH in Laravel?
- Publish the config file and set the environment variables it reads: PIWIK_URL is the base URL of your Matomo instance, PIWIK_SITE_ID is the numeric ID of the site being tracked, and PIWIK_TOKEN_AUTH is an optional token used for authenticated API calls. Keep these values in .env rather than committing them, and run php artisan config:cache in production so the config is not re-read per request. If you use a token, scope it to only the permissions the integration actually needs.
- How do I track a server-side event or conversion with the Piwik facade?
- Call the facade's tracker methods, such as doTrackEvent or doTrackPageView, from the point in your backend flow where the conversion happens, for example after a payment succeeds or a user registers. The package exposes Matomo's tracker semantics directly, so the method names mirror Matomo's own tracking model. It is a fire-and-forget client: hits are sent to Matomo but nothing is read back, so it does not return metrics or act as a query interface.
- Does robbrazier/piwik work with Matomo, or only with Piwik?
- Piwik was renamed Matomo in 2018, and the library this package wraps is now the Matomo PHP tracker, so it still targets the same analytics platform under its old name. That branding lag means older documentation and issue threads may not match current Matomo behavior, so verify details against Matomo's own docs. In practice you point PIWIK_URL at a self-hosted Matomo or Matomo Cloud instance and track against a site ID as usual.
- Why is server-side Matomo tracking slowing down my Laravel requests?
- The underlying tracker makes a synchronous outbound HTTP call, so a slow or unreachable Matomo endpoint adds latency to whichever request fires the hit and can throw inside user-facing flows. Move tracking into a queued job or a post-response hook so analytics never blocks the response. The package itself does not batch, buffer, or queue hits, so that responsibility sits with your application.
- How does robbrazier/piwik resolve client IP and user agent behind a proxy or CDN?
- Matomo deduplicates visits and geolocates based on the IP address and user agent sent with each hit, and a thin wrapper like this typically relies on the values you supply rather than resolving them for you. Behind a proxy, load balancer, or CDN, the request IP will be the proxy's unless you read the forwarded headers yourself and pass the real client IP and user agent to the tracker. Getting this wrong skews visitor counts and geolocation, so treat it as an explicit integration step.
- How do I test server-side Matomo tracking in a Laravel application?
- The cleanest approach is to isolate tracking behind your own interface and fake or mock it in tests so the suite never makes a real outbound HTTP call. If you want to test the package itself, point PIWIK_URL at a local stub or test Matomo instance and assert on the requests it receives. Because the facade is fire-and-forget and returns no data, assertions generally target the outgoing request rather than a response from Matomo.
- Should I use the Piwik facade directly or call matomo/matomo-php-tracker myself?
- The facade leaks Matomo semantics such as doTrackPageView, doTrackEvent, and setUserId into application code, which couples your domain to Matomo's tracking model and version. If analytics is peripheral, wrap it behind an internal AnalyticsClient interface so you can later swap the adapter for the tracker library directly or another provider. Calling matomo/matomo-php-tracker yourself is viable if you only want configuration convenience and prefer fewer layers.
- Is robbrazier/piwik still maintained, and what are the alternatives?
- Adoption signal is thin, at roughly 110 GitHub stars and effectively zero dependents, which means you are close to being the primary user and will be the one finding regressions. The dependency to watch is the Matomo PHP tracker library, so confirm its composer constraints keep it patched, and consider depending on matomo/matomo-php-tracker directly. Alternatives include calling the tracker library yourself, using client-side matomo.js for pageviews, or routing events through your own internal analytics abstraction.