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

matomo / app / core / Tracker / RequestProcessor.php

matomo / app / core / Tracker Last commit date

Config 4 months ago Db 3 months ago Handler 2 years ago Visit 1 month ago Action.php 3 months ago ActionPageview.php 2 years ago BotRequest.php 3 months ago BotRequestProcessor.php 1 month ago Cache.php 6 months ago Db.php 1 year ago Failures.php 6 months ago FingerprintSalt.php 1 year ago GoalManager.php 1 month ago Handler.php 2 years ago IgnoreCookie.php 1 year ago LogTable.php 1 year ago Model.php 6 months ago PageUrl.php 2 weeks ago Request.php 1 month ago RequestHandlerTrait.php 4 months ago RequestProcessor.php 1 month ago RequestSet.php 6 months ago Response.php 3 months ago ScheduledTasksRunner.php 1 year ago Settings.php 3 months ago TableLogAction.php 6 months ago TrackerCodeGenerator.php 1 year ago TrackerConfig.php 1 month ago Visit.php 3 months ago VisitExcluded.php 3 months ago VisitInterface.php 3 months ago Visitor.php 1 month ago VisitorNotFoundInDb.php 1 month ago VisitorRecognizer.php 1 year ago

RequestProcessor.php

159 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	public function manipulateRequest(\Piwik\Tracker\Request $request)
85	{
86	// empty
87	}
88	/**
89	* This is the second method called when processing a tracker request.
90	*
91	* Derived classes should use this method to set request metadata based on the tracking
92	* request alone. They should not try to access request metadata from other plugins,
93	* since they may not be set yet.
94	*
95	* When this method is called, `$visitProperties->visitorInfo` will be empty.
96	*
97	* @return bool If `true` the tracking request will be aborted.
98	*/
99	public function processRequestParams(VisitProperties $visitProperties, \Piwik\Tracker\Request $request)
100	{
101	return \false;
102	}
103	/**
104	* This is the third method called when processing a tracker request.
105	*
106	* Derived classes should use this method to set request metadata that needs request metadata
107	* from other plugins, or to override request metadata from other plugins to change
108	* tracking behavior.
109	*
110	* When this method is called, you can assume all available request metadata from all plugins
111	* will be initialized (but not at their final value). Also, `$visitProperties->visitorInfo`
112	* will contain the values of the visitor's last known visit (if any).
113	*
114	* @return bool If `true` the tracking request will be aborted.
115	*/
116	public function afterRequestProcessed(VisitProperties $visitProperties, \Piwik\Tracker\Request $request)
117	{
118	return \false;
119	}
120	/**
121	* This method is called before recording a new visit. You can set/change visit information here
122	* to change what gets inserted into `log_visit`.
123	*
124	* Only implement this method if you cannot use a Dimension for the same thing.
125	*
126	* Please note that the `onNewAction` hook in an action dimension is executed after this method.
127	*/
128	public function onNewVisit(VisitProperties $visitProperties, \Piwik\Tracker\Request $request)
129	{
130	// empty
131	}
132	/**
133	* This method is called before updating an existing visit. You can set/change visit information
134	* here to change what gets recorded in `log_visit`.
135	*
136	* Only implement this method if you cannot use a Dimension for the same thing.
137	*
138	* Please note that the `onNewAction` hook in an action dimension is executed before this method.
139	*
140	* @param array &$valuesToUpdate
141	*/
142	public function onExistingVisit(&$valuesToUpdate, VisitProperties $visitProperties, \Piwik\Tracker\Request $request)
143	{
144	// empty
145	}
146	/**
147	* This method is called last. Derived classes should use this method to insert log data. They
148	* should also only read request metadata, and not set it.
149	*
150	* When this method is called, you can assume all request metadata have their final values. Also,
151	* `$visitProperties->visitorInfo` will contain the properties of the visitor's current visit (in
152	* other words, the values in the array were persisted to the DB before this method was called).
153	*/
154	public function recordLogs(VisitProperties $visitProperties, \Piwik\Tracker\Request $request)
155	{
156	// empty
157	}
158	}
159