Piwik Api Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require devhelp/piwik-api
   

2. Basic Initialization

   use Devhelp\PiwikApi\Piwik;
   
   $piwik = new Piwik([
       'url' => 'https://your-piwik-instance.com',
       'auth_token' => 'your_auth_token_here',
       'site_id' => 1, // Default site ID
   ]);
   

3. First Use Case: Fetch Visits

   $visits = $piwik->getVisits();
   print_r($visits);
   

Key Files to Explore

• src/Piwik.php – Core class with all API methods.
• src/Exceptions/ – Custom exceptions for error handling.
• config/piwik.php (if auto-generated) – Configuration options.

Implementation Patterns

Common Workflows

1. Dynamic API Calls

Use runtime arguments for flexibility:

$period = 'day';
$date = '2023-10-01';
$metrics = $piwik->getMetric('nb_visits', [
    'period' => $period,
    'date' => $date,
]);

2. Bulk Operations

Fetch multiple metrics in one call:

$metrics = $piwik->getMetrics(['nb_visits', 'bounce_count'], [
    'period' => 'week',
]);

3. Authentication Handling

• Token-based: Pass auth_token in constructor.
• Login API: Use login() method for temporary tokens:

  $piwik->login('username', 'password');
  

4. Integration with Laravel

• Service Provider: Bind Piwik to the container:

  $this->app->singleton(Piwik::class, function ($app) {
      return new Piwik(config('piwik.settings'));
  });
  

• Facade: Create a facade for cleaner syntax:

  // PiwikFacade.php
  namespace App\Facades;
  use Illuminate\Support\Facades\Facade;
  class PiwikFacade extends Facade {
      protected static function getFacadeAccessor() { return 'piwik'; }
  }
  

  Usage:

  $visits = \App\Facades\Piwik::getVisits();
  

5. Caching Responses

Cache API responses to reduce calls:

$cacheKey = "piwik_visits_{$date}";
$visits = Cache::remember($cacheKey, now()->addHours(1), function () use ($piwik, $date) {
    return $piwik->getVisits(['date' => $date]);
});

Gotchas and Tips

Pitfalls

1. Authentication Failures

   • Ensure auth_token or login credentials are correct.
   • Check Piwik’s API token permissions (e.g., "View" access for metrics).
   • Debug with:

     try {
         $piwik->getVisits();
     } catch (\Devhelp\PiwikApi\Exceptions\AuthException $e) {
         Log::error('Piwik Auth Error: ' . $e->getMessage());
     }
     

2. Rate Limiting

   • Piwik may throttle requests. Implement exponential backoff:

     use Symfony\Component\HttpClient\RetryableHttpClient;
     $client = new RetryableHttpClient($piwik->getHttpClient(), [
         'max_retries' => 3,
         'delay_factor' => 2,
     ]);
     

3. Date/Period Formatting

   • Piwik expects specific formats (e.g., YYYY-MM-DD for date, day/week/month for period).
   • Validate inputs:

     if (!preg_match('/^\d{4}-\d{2}-\d{2}$/', $date)) {
         throw new \InvalidArgumentException('Invalid date format');
     }
     

4. Site ID Mismatch

   • If site_id is omitted or invalid, API calls may return empty data or errors.
   • Always validate site_id exists in Piwik’s Sites Manager.

Tips

1. Logging Enable debug logging for API responses:

   $piwik->setDebug(true); // Logs raw API responses to storage/logs/piwik.log
   

2. Extending the Package

   • Custom Methods: Extend Piwik class:

     class ExtendedPiwik extends \Devhelp\PiwikApi\Piwik {
         public function getCustomMetric($metricId, $params = []) {
             return $this->callApi('getMetric', [$metricId], $params);
         }
     }
     

   • HTTP Client: Override the default Guzzle client for custom headers/proxies:

     $piwik->setHttpClient(new \GuzzleHttp\Client([
         'headers' => ['User-Agent' => 'MyApp/1.0'],
         'proxy' => 'http://proxy.example.com',
     ]));
     

3. Testing

   • Mock the Piwik class in PHPUnit:

     $mock = $this->createMock(\Devhelp\PiwikApi\Piwik::class);
     $mock->method('getVisits')->willReturn(['nb_visits' => 100]);
     

   • Use Piwik’s Test API (if enabled) for sandbox testing.

4. Configuration

   • Store sensitive data (e.g., auth_token) in Laravel’s .env:

     PIWIK_URL=https://your-piwik-instance.com
     PIWIK_AUTH_TOKEN=your_token_here
     PIWIK_SITE_ID=1
     

   • Load config in config/piwik.php:

     return [
         'settings' => [
             'url' => env('PIWIK_URL'),
             'auth_token' => env('PIWIK_AUTH_TOKEN'),
             'site_id' => env('PIWIK_SITE_ID', 1),
         ],
     ];
     

5. Error Handling

   • Catch specific exceptions:

     try {
         $data = $piwik->getVisits();
     } catch (\Devhelp\PiwikApi\Exceptions\ApiException $e) {
         // Handle API errors (e.g., invalid parameters)
         abort(500, 'Piwik API Error: ' . $e->getMessage());
     } catch (\Devhelp\PiwikApi\Exceptions\NetworkException $e) {
         // Handle network issues
         abort(503, 'Piwik Service Unavailable');
     }
     

6. Performance

   • Batch Requests: Combine multiple metrics into a single API call where possible.
   • Async Processing: Use Laravel Queues for non-critical Piwik data fetches:

     dispatch(new FetchPiwikData($piwik, $params))->onQueue('piwik');