README

Table of Content

Introduction
Requirements
Installation
Usage
Report Structure
Development
Contributors

Introduction

Google has a PHP API Library that allows making requests to Google APIs from a PHP execution, including Reporting API v4 which enables access to Google Analytics data. However, while the library is quite powerful, it can be unintuitive as users have to create objects from the library (Google's Tutorial for PHP), which takes a lot of digging in the documentation.

As someone who had to use this library extensively, I wanted something that's more intuitive. Specifically, if I'm already familiar with Google Analytics and the dimensions and metrics available, I should immediately be able to make requests and get my data; and thus this package was born.

Features

Validation: If you make an API request and you had a typo, Google would return a 400 Bad Request. In this case you didn't get your data, but from my experience it would still eat into your daily quota. This package uses cached results from metadata API which helps with offline validation. (Note: some dimensions and metrics cannot be queried together, this validator as of now does not address that)
Optimize Requests: Google API forces users to break apart requests:
- A batchGet() request can take 5 subrequests.
- A subrequest can have 10 metrics
This means it can be difficult to aggregate the requests needed for a batchGet() call. If done incorrectly, this can lead to wasting space (e.g., having a lower metrics count than 10 in a subrequest). This package optimizes the packaging process of building a batchGet() request so no space is wasted in a single request.
Intuitive Reports: Just as this package helps you aggregate the requests, it also reorganizes the fragmented reports Google returned so it's structured minimally and intuitively. See Report Structure for details.

Requirements

Create a Service Account and store the downloaded json file somewhere secure. This is needed to make calls to Google API.
Add the created Service Account Email to your Google Analytics view. You can do this by going to your Analytics Homeapge → Admin → User Management.
Note: If the above seemed confusing, there is a very well written tutorial on an older Google interface.

Installation

This package is available through Composer, and can be installed by entering:

$ composer require p1ho/google-analytics-api

Usage

<?php

require_once __DIR__ . '/vendor/autoload.php';

use P1ho\GoogleAnalyticsAPI\Client;

$googleAnalytics = new Client('path/to/your/credentials/json');

// this is the view id on your Google Analytics page that represents the website.
$viewId = '12345678';

// dates can be anything that can be parsed by strtotime()
$startDate = 'yesterday';
$endDate = 'today';

/*
For complete listing of dimensions and metrics,
see https://developers.google.com/analytics/devguides/reporting/core/dimsmets
 */

// no longer than 7
$dimensions = [
  'ga:city',
  'ga:cityId'
];
// no longer than 50
$metrics = [
  'ga:users',
  'ga:sessions'
];

// queries and get organized data
$report = $googleAnalytics->getData($viewId, $startDate, $endDate, $dimensions, $metrics);

If needed, you can also add a filter expression

<?php

// your code from before

$filtersExp = "your-filter-expression-here";
$report = $googleAnalytics
            ->getData($viewId, $startDate, $endDate, $dimensions, $metrics, $filtersExp);

Note: The filter expression is the reason why I still require the ga: prefixes, if I had taken it out, it could make writing the filters expression confusing. I could also make it so the getData() method receives optional parameters array $dimensionFilters and array $metricFilters, but even that could introduce confusion. If this is useful to anyone, please open an issue and let me know your preference, and why.

Report Structure

{
  // how much of daily quota was spent
  "requestCost": 1,

  // The request that was sent to Google API
  "request": {
    "viewId": "12345678",
    "startDate": "yyyy-mm-dd",
    "endDate": "yyyy-mm-dd",
    "dimensions": [
      "dimension",
      "dimension"
    ],
    "metrics": [
      "metric",
      "metric"
    ],
    "filtersExp": "specified-filters-expression"
  },

  // The returned report
  "report": {

    // the summed metric values in the date range you specified
    "totals": {
      "metric": "total-value",
      "metric": "total-value"
    },

    // each row contains the metric values with a unique dimension combination
    // If all metric values for a row are 0, the row will not display
    // Any metric within a row with a value of 0 will not display
    "rows": [
      {
        "dimensions": {
          "dimension": "value",
          "dimension": "value"
        },
        "metrics": {
          "metric": "value",
          "metric": "value"
        }
      },
      {
        "dimensions": {
          "dimension": "value",
          "dimension": "value"
        },
        "metrics": {
          "metric": "value",
          "metric": "value"
        }
      }
    ]
  }
}

Note: Empty rows and 0 metric values are not displayed to minimize memory usage. Since users have the list of metrics used to make the requests, the 0 can be implied.

Development

$ composer test will run all the tests (use $ composer test-win on Windows). To enable coverage analysis, a code coverage driver is needed. I used Xdebug when developing on Windows. Afterwards, run $ composer phpcov-merge (use $ composer phpcov-merge-win on Windows) to merge build/cov/coverage.cov with build/logs/clover.xml as instructed on php-coveralls doc.
Run $ composer style-fix-download to download the latest php-cs-fixer file to project directory. Afterwards, you can run $ composer style-fix to auto style fix all your code.
No caching mechanism has been developed, it is expected to be taken care of by the user of this package depending on their use case.

Contributors


p1ho

p1ho / google-analytics-api

Maintainers

Details