A PHP client library for interacting with the Matomo API, providing robust and extensible functionality for managing and querying Matomo analytics data.
- Supports retry logic with
RetryingMatomoApiClientfor handling transient failures. - Caching with
Psr6CacheMatomoApiClientto minimize API calls and improve performance. - Fully PSR-compliant with PSR-6 (Caching), PSR-3 (Logging), PSR-17 (HTTP Factories), and PSR-18 (HTTP Client).
- Extensible via the
MatomoApiClientInterfacefor standardized requests to the Matomo API.
Install via Composer:
composer require tomkyle/matomo-api-clientClass MatomoApiClient is the primary client for sending requests to the Matomo API. The API response is returned as an associative array:
use tomkyle\MatomoApiClient\MatomoApiClient;
use GuzzleHttp\Psr7\Uri;
// Initialize the client
$uri = new Uri('https://your-matomo-domain.com');
$defaults = ['token_auth' => 'your-api-token'];
$client = new MatomoApiClient($uri, $defaults);
// Send a request
$params = ['idSite' => '1', 'period' => 'day', 'date' => 'today'];
$response = $client->request($params, 'VisitsSummary.get');
print_r($response);All classes in this package implement the MatomoApiClientInterface interface with a request method which returns the API response as an associative array. The method accepts the Matomo API parameters as well as an optional API method—See Matomo docs for more information:
/**
* @param array<string,string> $params API params
* @return array<string|int,mixed> API result
*/
public function request(array $params, string $method = null): array;The RetryingMatomoApiClient wraps the above MatomoApiClient instance. When a request fails due to server load, it will retry the request up to a specified number of attempts.
use tomkyle\MatomoApiClient\RetryingMatomoApiClient;
// Maximum 3 attempts, 5 seconds wait
$retryingClient = new RetryingMatomoApiClient($client, 3, 5);
// Send a request
$params = ['idSite' => '1', 'period' => 'day', 'date' => 'today'];
$response = $retryingClient->request($params, 'VisitsSummary.get');The Psr6CacheMatomoApiClient wraps any MatomoApiClientInterface instance and integrates with any PSR-6 compliant cache pool.
use tomkyle\MatomoApiClient\Psr6CacheMatomoApiClient;
use Symfony\Component\Cache\Adapter\FilesystemAdapter;
$cachePool = new FilesystemAdapter();
$cachingClient = new Psr6CacheMatomoApiClient($cachePool, $client);
$response = $cachingClient->request($params, 'VisitsSummary.get');- MatomoApiClientException: Thrown for errors during API requests or response handling.
This library is licensed under the MIT License. See the LICENSE file for details.
Contributions are welcome! Please open an issue or submit a pull request.
Run npm update to install development helpers. Watch the file system for PHP code changes using npm run watch and see what phpstan, phpcs, Rector, and PhpUnit say. See package.json for a list of all watch and test tasks.
$ npm run watch