<?php
/**
 * Base class for reports.
 *
 * @package TurtleReport
 */

namespace TurtleReport\Reports;

use TurtleReport\Google\ServicesFactory;
use TurtleReport\Profiles\Profile;

defined( 'ABSPATH' ) || exit;

/**
 * A report is one REST endpoint that reads Google data for a site.
 *
 * Each report gets its own route, /sites/{site}/reports/{id}, with its own
 * validated arguments. Add a report by extending this class and adding it
 * through the "turtlereport_reports" filter. Access checks are done by the
 * controller before run() is called.
 */
abstract class Report {

	/**
	 * Google services factory.
	 *
	 * @var ServicesFactory
	 */
	protected $google;

	/**
	 * Constructor.
	 *
	 * @param ServicesFactory $google Google services factory.
	 */
	public function __construct( ServicesFactory $google ) {
		$this->google = $google;
	}

	/**
	 * Route slug, e.g. "search-console".
	 *
	 * @return string
	 */
	abstract public function id();

	/**
	 * The site section this report belongs to (Profile::SECTION_*).
	 *
	 * The controller refuses the request when the section is switched off for
	 * the site, so no data is fetched from Google for it.
	 *
	 * @return string
	 */
	abstract public function section();

	/**
	 * The Google source this report reads (Profile::SOURCE_*). Decides which of
	 * the site's connections is used and which one is flagged when sign-in fails.
	 *
	 * @return string
	 */
	public function source() {
		return Profile::source_for_section( $this->section() );
	}

	/**
	 * Segment types this report can be filtered by (Policy\Segments::TYPE_*).
	 *
	 * @return string[]
	 */
	public function segment_types() {
		return array();
	}

	/**
	 * The segment requested for this run, validated against segment_types().
	 *
	 * @param Profile $site   Site.
	 * @param array   $params Parameters.
	 * @return array|null
	 * @throws \TurtleReport\Auth\ApiException When the segment is unknown or doesn't apply.
	 */
	protected function segment( Profile $site, array $params ) {
		return SegmentFilter::resolve( $site, isset( $params['segment'] ) ? (string) $params['segment'] : '', $this->segment_types() );
	}

	/**
	 * REST arguments other than start and end, in register_rest_route() format.
	 *
	 * @return array
	 */
	public function args() {
		return array();
	}

	/**
	 * Runs the report.
	 *
	 * @param Profile $site   Site being reported on.
	 * @param array   $params Validated parameters, including start and end.
	 * @return mixed JSON-serialisable data.
	 * @throws \TurtleReport\Auth\ApiException On Google or setup errors.
	 */
	abstract public function run( Profile $site, array $params );

	/**
	 * Cache lifetime for a date range.
	 *
	 * Ranges that end before the last few days won't change, so they are
	 * kept longer.
	 *
	 * @param string $end End date (Y-m-d).
	 * @return int Seconds.
	 */
	protected function ttl( $end ) {
		$settled = $end < gmdate( 'Y-m-d', time() - 4 * DAY_IN_SECONDS );
		$ttl     = $settled ? DAY_IN_SECONDS : 3 * HOUR_IN_SECONDS;

		/**
		 * Filters how long a report response is cached.
		 *
		 * @param int    $ttl       Seconds.
		 * @param string $report_id Report ID.
		 * @param string $end       End date of the requested range.
		 */
		return (int) apply_filters( 'turtlereport_cache_ttl', $ttl, $this->id(), $end );
	}

	/**
	 * Lowercases a landing-page path and removes its trailing slash.
	 *
	 * @param string $path Path.
	 * @return string
	 */
	protected static function normalize_path( $path ) {
		$path = strtolower( (string) $path );
		if ( strlen( $path ) > 1 && '/' === substr( $path, -1 ) ) {
			$path = substr( $path, 0, -1 );
		}
		return $path;
	}

	/**
	 * Converts an empty array to an object so it encodes as {} in JSON.
	 *
	 * @param array $map Map.
	 * @return array|\stdClass
	 */
	protected static function map( array $map ) {
		return $map ? $map : new \stdClass();
	}
}