RequestProcessor.php — Matomo Analytics – Powerful, Privacy-First Insights for WordPress 5.2.0

matomo / app / core / Tracker / RequestProcessor.php

matomo / app / core / Tracker Last commit date

Db 1 year ago Handler 2 years ago Visit 1 year ago Action.php 1 year ago ActionPageview.php 2 years ago Cache.php 1 year ago Db.php 1 year ago Failures.php 1 year ago FingerprintSalt.php 1 year ago GoalManager.php 1 year ago Handler.php 2 years ago IgnoreCookie.php 1 year ago LogTable.php 1 year ago Model.php 1 year ago PageUrl.php 1 year ago Request.php 1 year ago RequestProcessor.php 1 year ago RequestSet.php 1 year ago Response.php 1 year ago ScheduledTasksRunner.php 1 year ago Settings.php 1 year ago TableLogAction.php 1 year ago TrackerCodeGenerator.php 1 year ago TrackerConfig.php 2 years ago Visit.php 1 year ago VisitExcluded.php 1 year ago VisitInterface.php 2 years ago Visitor.php 1 year ago VisitorNotFoundInDb.php 2 years ago VisitorRecognizer.php 1 year ago

RequestProcessor.php

173 lines

1	<?php
2
3	/**
4	* Matomo - free/libre analytics platform
5	*
6	* @link https://matomo.org
7	* @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
8	*/
9	namespace Piwik\Tracker;
10
11	use Piwik\Tracker\Visit\VisitProperties;
12	/**
13	* Base class for all tracker RequestProcessors. RequestProcessors handle and respond to tracking
14	* requests.
15	*
16	* ## Concept: Request Metadata
17	*
18	* RequestProcessors take a Tracker\Request object and based on its information, set request metadata.
19	*
20	* Request metadata is information about the current tracking request, for example, whether
21	* the request is for an existing visit or new visit, or whether the current visitor is a known
22	* visitor, etc. It is used to control tracking behavior.
23	*
24	* Request metadata is shared between RequestProcessors, so RequestProcessors can tweak each others
25	* behavior, and thus, the behavior of the Tracker. Request metadata can be set and get using the
26	* {@link Request::setMetadata()} and {@link Request::getMetadata()}
27	* methods.
28	*
29	* Each RequestProcessor lists the request metadata it computes and exposes in its class
30	* documentation.
31	*
32	* ## The Tracking Process
33	*
34	* When Piwik handles a single tracking request, it gathers all available RequestProcessors and
35	* invokes their methods in sequence.
36	*
37	* The first method called is {@link self::manipulateRequest()}. By default this is a no-op, but
38	* RequestProcessors can use it to manipulate tracker requests before they are processed.
39	*
40	* The second method called is {@link self::processRequestParams()}. RequestProcessors should use
41	* this method to compute request metadata and set visit properties using the tracking request.
42	* An example includes the ActionRequestProcessor, which uses this method to determine the action
43	* being tracked.
44	*
45	* The third method called is {@link self::afterRequestProcessed()}. RequestProcessors should
46	* use this method to either compute request metadata/visit properties using other plugins'
47	* request metadata, OR override other plugins' request metadata to tweak tracker behavior.
48	* An example of the former can be seen in the GoalsRequestProcessor which uses the action
49	* detected by the ActionsRequestProcessor to see if there are any action-matching goal
50	* conversions. An example of the latter can be seen in the PingRequestProcessor, which on
51	* ping requests, aborts conversion recording and new visit recording.
52	*
53	* After these methods are called, either {@link self::onNewVisit()} or {@link self::onExistingVisit()}
54	* is called. Generally, plugins should favor defining Dimension classes instead of using these methods,
55	* however sometimes it is not possible (as is the case with the CustomVariables plugin).
56	*
57	* Finally, the {@link self::recordLogs()} method is called. In this method, RequestProcessors
58	* should use the request metadata that was set (and maybe overridden) to insert whatever log data
59	* they want.
60	*
61	* ## Extending The Piwik Tracker
62	*
63	* Plugins that want to change the tracking process in order to track new data or change how
64	* existing data is tracked can create RequestProcessors to accomplish.
65	*
66	* _Note: If you only want to add tracked data to visits, actions or conversions, you should create
67	* a {@link Dimension} class._
68	*
69	* To create a new RequestProcessor, create a new class that derives from this one, and implement the
70	* methods you need. Then put this class inside the `Tracker` directory of your plugin.
71	*
72	* Final note: RequestProcessors are shared between tracking requests, and so, should ideally be
73	* stateless. They are stored in DI, so they can contain references to other objects in DI, but
74	* they shouldn't contain data that might change between tracking requests.
75	*/
76	abstract class RequestProcessor
77	{
78	/**
79	* This is the first method called when processing a tracker request.
80	*
81	* Derived classes can use this method to manipulate a tracker request before the request
82	* is handled. Plugins could change the URL, add custom variables, etc.
83	*
84	* @param Request $request
85	*/
86	public function manipulateRequest(\Piwik\Tracker\Request $request)
87	{
88	// empty
89	}
90	/**
91	* This is the second method called when processing a tracker request.
92	*
93	* Derived classes should use this method to set request metadata based on the tracking
94	* request alone. They should not try to access request metadata from other plugins,
95	* since they may not be set yet.
96	*
97	* When this method is called, `$visitProperties->visitorInfo` will be empty.
98	*
99	* @param VisitProperties $visitProperties
100	* @param Request $request
101	* @return bool If `true` the tracking request will be aborted.
102	*/
103	public function processRequestParams(VisitProperties $visitProperties, \Piwik\Tracker\Request $request)
104	{
105	return \false;
106	}
107	/**
108	* This is the third method called when processing a tracker request.
109	*
110	* Derived classes should use this method to set request metadata that needs request metadata
111	* from other plugins, or to override request metadata from other plugins to change
112	* tracking behavior.
113	*
114	* When this method is called, you can assume all available request metadata from all plugins
115	* will be initialized (but not at their final value). Also, `$visitProperties->visitorInfo`
116	* will contain the values of the visitor's last known visit (if any).
117	*
118	* @param VisitProperties $visitProperties
119	* @param Request $request
120	* @return bool If `true` the tracking request will be aborted.
121	*/
122	public function afterRequestProcessed(VisitProperties $visitProperties, \Piwik\Tracker\Request $request)
123	{
124	return \false;
125	}
126	/**
127	* This method is called before recording a new visit. You can set/change visit information here
128	* to change what gets inserted into `log_visit`.
129	*
130	* Only implement this method if you cannot use a Dimension for the same thing.
131	*
132	* Please note that the `onNewAction` hook in an action dimension is executed after this method.
133	*
134	* @param VisitProperties $visitProperties
135	* @param Request $request
136	*/
137	public function onNewVisit(VisitProperties $visitProperties, \Piwik\Tracker\Request $request)
138	{
139	// empty
140	}
141	/**
142	* This method is called before updating an existing visit. You can set/change visit information
143	* here to change what gets recorded in `log_visit`.
144	*
145	* Only implement this method if you cannot use a Dimension for the same thing.
146	*
147	* Please note that the `onNewAction` hook in an action dimension is executed before this method.
148	*
149	* @param array &$valuesToUpdate
150	* @param VisitProperties $visitProperties
151	* @param Request $request
152	*/
153	public function onExistingVisit(&$valuesToUpdate, VisitProperties $visitProperties, \Piwik\Tracker\Request $request)
154	{
155	// empty
156	}
157	/**
158	* This method is called last. Derived classes should use this method to insert log data. They
159	* should also only read request metadata, and not set it.
160	*
161	* When this method is called, you can assume all request metadata have their final values. Also,
162	* `$visitProperties->visitorInfo` will contain the properties of the visitor's current visit (in
163	* other words, the values in the array were persisted to the DB before this method was called).
164	*
165	* @param VisitProperties $visitProperties
166	* @param Request $request
167	*/
168	public function recordLogs(VisitProperties $visitProperties, \Piwik\Tracker\Request $request)
169	{
170	// empty
171	}
172	}
173