<?php
/**
 * GA4 page paths for a post.
 *
 * @package Tagsmith
 */

declare(strict_types=1);

namespace Tagsmith\Reports;

defined( 'ABSPATH' ) || exit;

/**
 * Derives the pagePath values GA4 records for a post, for path_filter
 * reports (per-post stats, posts list column).
 */
class PostPaths {

	/**
	 * The post's permalink path plus its trailing-slash variant, and, for
	 * non-ASCII slugs, the percent-decoded form of each (WordPress emits
	 * `/caf%c3%a9/`, while GA4 may record `/café/`), after the
	 * `tagsmith_post_paths` filter; null when the site uses plain
	 * permalinks (`/?p=123`), because GA4's pagePath drops the query string
	 * and every post would then match '/'.
	 *
	 * @param \WP_Post $post Post.
	 * @return string[]|null
	 */
	public static function for_post( \WP_Post $post ): ?array {
		$permalink = (string) get_permalink( $post );
		$query     = wp_parse_url( $permalink, PHP_URL_QUERY );

		if ( '' === $permalink || ( is_string( $query ) && '' !== $query ) ) {
			return null;
		}

		$path  = (string) wp_parse_url( $permalink, PHP_URL_PATH );
		$path  = '' === $path ? '/' : $path;
		$paths = array( $path );

		if ( '/' !== $path ) {
			$paths[] = '/' === substr( $path, -1 ) ? untrailingslashit( $path ) : trailingslashit( $path );
		}

		foreach ( $paths as $encoded ) {
			$decoded = rawurldecode( $encoded );

			if ( $decoded !== $encoded ) {
				$paths[] = $decoded;
			}
		}

		/**
		 * Filters the GA4 page paths counted as one post.
		 *
		 * @since 2.0.0
		 *
		 * @param string[] $paths The permalink path and its trailing-slash variant, plus their percent-decoded forms when they differ.
		 * @param \WP_Post $post  The post.
		 */
		$filtered = apply_filters( 'tagsmith_post_paths', $paths, $post );

		return array_values( array_unique( array_filter( (array) $filtered, static fn( $p ): bool => is_string( $p ) && '' !== $p ) ) );
	}
}