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

matomo / app / core / Tracker / RequestProcessor.php

matomo / app / core / Tracker Last commit date

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

RequestProcessor.php

175 lines

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