Download the PHP package freema/ga4-analytics-data-bundle without Composer

Google Analytics 4 Data API Bundle for Symfony

A Symfony bundle for working with the Google Analytics 4 Data API. This bundle supports multiple Google Analytics properties, cache configuration, and provides a clean API to query analytics data.

Installation

Install the bundle using Composer:

The bundle uses Symfony Flex, so it will automatically:

• Enable the bundle in config/bundles.php
• Create the configuration file config/packages/ga4_analytics_data.yaml
• Add environment variables to your .env file
• Add the credentials file path to your .gitignore

Manual Installation (Without Flex)

If you're not using Symfony Flex, you need to:

1. Register the bundle in your config/bundles.php:

2. Create the configuration file at config/packages/ga4_analytics_data.yaml:

3. Add the required environment variables to your .env file:

Requirements

• PHP 8.1+
• Symfony 5.4|6.4|7.1
• Google Analytics 4 Property
• Service Account credentials with access to the GA4 property

Usage

Basic Usage

Using Multiple Clients

Custom Queries

Period Helper

The bundle includes a Period class to easily define date ranges:

Caching

The bundle provides flexible caching options:

• Enable/Disable: Set enabled: true/false in the cache config section
• Lifetime: Configure with lifetime_in_minutes (defaults to 1440 = 24 hours)
• Custom Cache: The bundle uses Symfony's cache system, so you can configure any PSR-6 cache adapter

Symfony Web Profiler Integration

The bundle includes a data collector for the Symfony Web Profiler that shows:

• Configured Analytics clients
• Property IDs
• Cache settings
• Proxy configuration

This can be disabled by setting profiler: false in the bundle config.

Getting Google Analytics 4 Credentials

Creating Service Account Credentials

1. Go to the Google Cloud Console
2. Create a new project or select an existing one
3. Enable the "Google Analytics Data API" for your project
4. Go to "APIs & Services" > "Credentials"
5. Create a new "Service Account"
6. Download the JSON key file for the service account
7. In Google Analytics, go to Admin > Property > Property Access Management
8. Add the service account email with "Viewer" permissions

Credentials File Format

The service account credentials file should be a JSON file with the following structure:

Security Best Practices

1. Store credentials securely: Keep the JSON file in a secure location, outside of your web root
2. Use environment variables: Reference the path to the credentials file using environment variables
3. Restrict permissions: Set appropriate file permissions to limit access to the credentials file
4. Environment-specific paths: Use different paths for different environments (dev, staging, prod)

Error Handling

The bundle validates the credentials file and provides clear error messages for common issues:

• File not found or unreadable
• Invalid JSON format
• Missing required fields
• Incorrect service account format

If you encounter credential errors, check:

1. That the file exists at the specified path
2. That the file has proper read permissions
3. That the file contains valid JSON with all required fields
4. That the service account has access to the Google Analytics property

License

This bundle is released under the MIT License. See the included LICENSE file.

Contributing

See CONTRIBUTING.md for information on how to contribute to this project.