t3g / analytics
TYPO3 Analytics Extension
Requires
- php: ^8.2
- ext-sodium: *
- typo3/cms-backend: ^13.4.18 || ^14.0
- typo3/cms-core: ^13.4 || ^14.0
- typo3/cms-dashboard: ^13.4 || ^14.0
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.64
- phpstan/phpstan: ^2.1
- phpunit/phpunit: ^11.0
- rector/rector: ^2.4
- saschaegerer/phpstan-typo3: ^3.0
- ssch/typo3-rector: ^3.13
- typo3/testing-framework: ^8.0 || ^9.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
- dev-develop
- 1.1.1
- 1.1.0
- 1.0.5
- 1.0.4
- 1.0.3
- 1.0.2
- 1.0.1
- 1.0.0
- 0.10.2
- 0.10.1
- 0.10.0
- 0.9.15
- 0.9.14
- 0.9.13
- 0.9.11
- 0.9.10
- 0.9.9
- 0.9.8
- 0.9.7
- 0.9.6
- 0.9.5
- 0.9.4
- 0.9.3
- 0.9.2
- 0.9.1
- 0.9.0
- dev-feature/analytics-settings-plugin-namespace
- dev-feature/analytics-site-data-file
- dev-feature/analytics-data-client-utility
- dev-feature/site-attach
- dev-feature/ui-overhaul
- dev-bugfix/validate-email-before-registration
- dev-task/load-dashboard-only-from-https-urls
- dev-bugfix/match-language-base-at-path-boundary
- dev-task/mark-secrets-as-sensitive-parameters
- dev-bugfix/allow-tracking-code-in-frontend-csp
- dev-bugfix/lock-site-settings-writes
- dev-task/encode-website-id
- dev-task/disable-api-redirects
- dev-main
- dev-bugfix/phpstan
This package is auto-updated.
Last update: 2026-11-18 09:26:15 UTC
README
A TYPO3 backend extension that integrates TYPO3 Analytics into the TYPO3 site management panel. It lets editors register TYPO3 sites with the TYPO3 Analytics API, monitor registration status, and open the analytics dashboard without leaving the TYPO3 backend.
For the full documentation, see docs.typo3.org.
Contents
Installation
Composer (recommended)
composer require t3g/analytics
Activate the extension in the TYPO3 Extension Manager or via:
vendor/bin/typo3 extension:setup analytics
TER / Classic mode
In a non-Composer TYPO3 installation, search for analytics in Admin Tools → Extensions (TYPO3 v13) or System → Extensions (TYPO3 v14) and install it from there. Make sure the Dashboard system extension is active before installing.
Deployment note
The extension writes sensitive data (credentials, tracking code and API keys) into config/sites/<identifier>/settings.yaml of each site. Do not commit this file to the repository. For more information, see Installation.
Configuration
Development settings
| Key | Type | Default | Description |
|---|---|---|---|
demoData |
bool | 0 |
When enabled, replaces analytics API calls with static demo data. Only takes effect in a TYPO3 Development application context. |
Dashboard settings
| Key | Type | Default | Description |
|---|---|---|---|
dashboardPeriods |
string | 7,14,30 |
Comma-separated list of time period options (in days) shown in all dashboard widget dropdowns and the page performance bar. Must be positive integers. |
dashboardDefaultPeriod |
int | 7 |
Pre-selected time period (in days) for all dashboard widgets. Must be one of the values in dashboardPeriods. |
Example — custom time period:
$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['analytics']['dashboardPeriods'] = '7,30,90'; $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['analytics']['dashboardDefaultPeriod'] = 30;
Cache settings
| Key | Type | Default | Description |
|---|---|---|---|
pageAnalyticsCacheTtl |
int | 3600 |
Lifetime in seconds for analytics data caches. Increase this value to reduce API calls in high-traffic backend installations. |
Example — longer cache lifetime:
$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['analytics']['pageAnalyticsCacheTtl'] = 7200;
Local development with DDEV
The repository ships a fully automated DDEV environment that spins up a dummy TYPO3 installation with five sub-domain sites.
Prerequisites
- DDEV installed
- Docker running
Start the environment
ddev start
On first start DDEV automatically runs the setup script. You will be prompted to choose the TYPO3 major version:
TYPO3 version to install (13/14) [13]:
The script will:
- Create a fresh TYPO3 project in
.Build/dummy-typo3/usingtypo3/cms-base-distribution - Drop and recreate the database for a clean slate
- Require and symlink this extension from the repository root
- Run
vendor/bin/typo3 setupnon-interactively - Create five root pages (Site 1–5)
- Write site configurations for five subdomains
- Remove the
FIRST_INSTALLflag so the backend is immediately accessible
Available URLs after setup
| URL | Description |
|---|---|
https://analytics.ddev.site/typo3 |
TYPO3 backend |
https://site1.analytics.ddev.site/ |
Frontend site 1 |
https://site2.analytics.ddev.site/ |
Frontend site 2 |
https://site3.analytics.ddev.site/ |
Frontend site 3 |
https://site4.analytics.ddev.site/ |
Frontend site 4 |
https://site5.analytics.ddev.site/ |
Frontend site 5 |
https://analytics.ddev.site:1337 |
Documentation preview |
Backend credentials: admin / Admin1234!
Re-run setup manually
ddev exec composer dummy-typo3
Reset everything
# Remove the dummy installation (keeps DDEV containers) rm -rf .Build/dummy-typo3 # Then restart — setup runs automatically ddev restart
Run an additional environment in parallel
You can run an additional environment next to the existing one, for example to test with another TYPO3 version.
Use another checkout of the repository for this, for example a clone or a git worktree.
Two DDEV projects with the same name cannot run at the same time.
The project name in .ddev/config.yaml is analytics.
Do not change .ddev/config.yaml.
Set a different name in a local override file instead.
-
In the other checkout, create the file
.ddev/config.local.yaml:name: analytics-v14 override_config: true additional_fqdns: - site1.analytics-v14.ddev.site - site2.analytics-v14.ddev.site - site3.analytics-v14.ddev.site - site4.analytics-v14.ddev.site - site5.analytics-v14.ddev.site
override_config: truereplaces the listadditional_fqdns. Without it, DDEV adds the new host names to the host names from.ddev/config.yaml. -
Run
ddev startin the other checkout. -
Select the TYPO3 version when the setup script asks for it.
The setup script reads the host name from DDEV.
Thus, the URLs of the additional environment use the new name, for example https://analytics-v14.ddev.site/typo3.
Git ignores the file .ddev/config.local.yaml.
Documentation preview
The ddev-typo3-docs add-on renders the .rst files in Documentation/ with the same renderer used by docs.typo3.org. It starts automatically with ddev start/ddev restart and watches for changes.
Open https://analytics.ddev.site:1337 and edit files under Documentation/ — the preview re-renders automatically on save.
Code quality
# PHP CS Fixer (dry-run) composer t3g:cgl # PHP CS Fixer (fix) composer t3g:cgl:fix # PHPStan composer t3g:phpstan # Rector (dry-run) composer t3g:rector:dry-run # Rector (apply) composer t3g:rector:fix
Tests
# All tests composer t3g:test # Unit tests only composer t3g:test:unit # Functional tests (SQLite, no external DB required) composer t3g:test:functional
Unit tests use the TYPO3 testing framework with an in-process bootstrap. Functional tests use SQLite via pdo_sqlite — no external database server is required.
Compatibility notes
Encryption
Credentials are encrypted using XChaCha20-Poly1305 via libsodium. On TYPO3 v14+ the built-in TYPO3\CMS\Core\Crypto\Cipher\CipherService is used automatically; on v13 an equivalent custom implementation is used, ensuring values remain decryptable after upgrading.
TYPO3 v13
ext_emconf.phpis required and evaluated by TYPO3.- The custom sodium-based cipher is used for credential encryption.
- Module access is controlled via
'access' => 'user'. - The Material Design icon (
Extension-v13.svg) is used automatically.
TYPO3 v14
ext_emconf.phpis deprecated (Feature #108345). Extension metadata is read fromcomposer.json(extra.typo3/cms).- The built-in
TYPO3\CMS\Core\Crypto\Cipher\CipherServiceis used automatically. - Module access uses the gate-registry pattern;
'user,group'is no longer valid —'user'is used instead. - The adaptive theme icon (
Extension.svg) is used automatically.