README

One shared allowlist and one sanitization algorithm for URLs sent to Tracks, published as matching JS and PHP packages.

sanitizeUrl removes query params that aren't on the allowlist, sanitizes URLs nested in param values (like redirect_to), and removes fragments and userinfo (name:extra@):

https://wordpress.com/log-in?redirect_to=https%3A%2F%2Fwordpress.com%2Fcheckout%3Futm_source%3Demail%26extra%3D1&notAllowed=1#section
→ https://wordpress.com/log-in?redirect_to=https%3A%2F%2Fwordpress.com%2Fcheckout%3Futm_source%3Demail

The full behavior is defined in SPEC.md. Both ports must pass every case in shared/test-cases.json.

Usage

JavaScript / TypeScript

npm install @automattic/tracks-shared-utils

import { sanitizeUrl, URL_PROPS } from '@automattic/tracks-shared-utils';

for ( const prop of URL_PROPS ) {
	if ( typeof props[ prop ] === 'string' ) {
		props[ prop ] = sanitizeUrl( props[ prop ] );
	}
}

Both ESM and CommonJS builds are included, along with TypeScript types. ALLOWED_PARAMS is also exported.

PHP (7.2+)

composer require automattic/tracks-shared-utils

use function Automattic\TracksSharedUtils\sanitize_url;
use function Automattic\TracksSharedUtils\url_props;

foreach ( url_props() as $prop ) {
	if ( isset( $props[ $prop ] ) && is_string( $props[ $prop ] ) ) {
		$props[ $prop ] = sanitize_url( $props[ $prop ] );
	}
}

allowed_params() is also available.

Development

Repo layout

shared/url-sanitization.json   # the allowlist, URL props and limits (source of truth)
shared/test-cases.json         # input → expected cases, run by both ports
js/                            # TypeScript port (npm package)
php/                           # PHP port (Composer package; composer.json is at the root)
php/generated/                 # PHP copy of the config, generated by `composer build:config`
SPEC.md                        # the algorithm both ports implement

JS

Requires Node 22.12+ (or 24+).

cd js
npm install
npm test            # run the shared cases with Vitest
npm run typecheck   # tsc --noEmit
npm run build       # ESM + CJS + type declarations into js/dist
npm run check:dist  # run the shared cases against the built bundles

PHP

Requires PHP 7.2+ and Composer. Run these from the repo root:

composer install
composer test          # run the shared cases with PHPUnit
composer lint:compat   # check that the code stays PHP 7.2-compatible
composer build:config  # regenerate php/generated/ from shared/url-sanitization.json

JS/PHP parity

CI runs both ports over the same fuzzed inputs and fails on any difference. To run it locally, build the JS package first:

(cd js && npm run build && npm run parity:generate -- /tmp/parity.jsonl)
composer parity:check -- /tmp/parity.jsonl

Changing behavior or the allowlist

Edit shared/url-sanitization.json and/or add cases to shared/test-cases.json. For a behavior change, update SPEC.md too.
If you edited the JSON, run composer build:config and commit the regenerated php/generated/url-sanitization.php.
Update both ports until npm test and composer test pass.

CI runs both suites on every pull request.

Releasing

The two packages share one version. Bump version in js/package.json, tag the commit vX.Y.Z, then publish:

Composer: Packagist picks up the tag.
npm: run npm publish from js/. This runs typecheck, tests and build first.

License

GPL-2.0-or-later

automattic / tracks-shared-utils

Package info

Security

Statistics