1	<?php
2
3	namespace MediaWiki\Extension\PageViewInfo;
4
5	use StatusValue;
6	use Title;
7
8	/**
9	* PageViewService provides an abstraction for different methods to access pageview data
10	* (HitCounter extension DB tables, Piwik API, Google Analytics API etc).
11	*/
12	interface PageViewService {
13	/** Page view count */
14	public const METRIC_VIEW = 'view';
15	/** Unique visitors (devices) for some period, typically last 30 days */
16	public const METRIC_UNIQUE = 'unique';
17
18	/** Return data for a given article */
19	public const SCOPE_ARTICLE = 'article';
20	/** Return a list of the top articles */
21	public const SCOPE_TOP = 'top';
22	/** Return data for the whole site */
23	public const SCOPE_SITE = 'site';
24
25	/**
26	* Whether the service can provide data for the given metric/scope combination.
27	* @param string $metric One of the METRIC_* constants.
28	* @param string $scope One of the METRIC_* constants.
29	* @return bool
30	*/
31	public function supports( $metric, $scope );
32
33	/**
34	* Returns an array of daily counts for the last $days days, in the format
35	*   title => [ date => count, ... ]
36	* where date is in ISO format (YYYY-MM-DD). Which time zone to use is left to the implementation
37	* (although UTC is the recommended one, unless the site has a very narrow audience). Exactly
38	* which days are returned is also up to the implentation; recent days with incomplete data
39	* should be omitted. (Typically that means that the returned date range will end with the
40	* previous day, but given a sufficiently slow backend, the last full day for which data is
41	* available and the last full calendar day might not be the same thing).
42	* Count will be null when there is no data or there was an error. The order of titles will be
43	* the same as in the parameter $titles, but some implementations might return fewer titles than
44	* requested, if fetching more data is considered too expensive. In that case the returned data
45	* will be for a prefix slice of the $titles array.
46	* @param Title[] $titles
47	* @param int $days The number of days.
48	* @param string $metric One of the METRIC_* constants.
49	* @return StatusValue A status object with the data. Its success property will contain
50	*   per-title success information.
51	*/
52	public function getPageData( array $titles, $days, $metric = self::METRIC_VIEW );
53
54	/**
55	* Returns an array of total daily counts for the whole site, in the format
56	*   date => count
57	* where date is in ISO format (YYYY-MM-DD). The same considerations apply as for getPageData().
58	* @param int $days The number of days.
59	* @param string $metric One of the METRIC_* constants.
60	* @return StatusValue A status object with the data.
61	*/
62	public function getSiteData( $days, $metric = self::METRIC_VIEW );
63
64	/**
65	* Returns a list of the top pages according to some metric, sorted in descending order
66	* by that metric, in
67	*   title => count
68	* format (where title has the same format as Title::getPrefixedDBKey()).
69	* @param string $metric One of the METRIC_* constants.
70	* @return StatusValue A status object with the data.
71	*/
72	public function getTopPages( $metric = self::METRIC_VIEW );
73
74	/**
75	* Returns the length of time for which it is acceptable to cache the results.
76	* Typically this would be the end of the current day in whatever timezone the data is in.
77	* @param string $metric One of the METRIC_* constants.
78	* @param string $scope One of the METRIC_* constants.
79	* @return int Time in seconds
80	*/
81	public function getCacheExpiry( $metric, $scope );
82	}