1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
|
<?php
/**
* Piwik - Open source web analytics
*
* @link http://piwik.org
* @license http://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
*
* @category Piwik_Plugins
* @package Piwik_ExampleAPI
*/
use Piwik\DataTable\Row;
use Piwik\Piwik;
use Piwik\DataTable;
/**
* The ExampleAPI is useful to developers building a custom Piwik plugin.
*
* Please see the <a href='http://dev.piwik.org/trac/browser/trunk/plugins/ExampleAPI/API.php#L1' target='_blank'>source code in in the file plugins/ExampleAPI/API.php</a> for more documentation.
* @package Piwik_ExampleAPI
*/
class Piwik_ExampleAPI_API
{
/**
* * This is an example of a basic API file. Each plugin can have one public API.
* Each public function in this class will be available to be called via the API.
* Protected and private members will not be callable.
* Functions can be called internally using the PHP objects directly, or via the
* Piwik Web APIs, using HTTP requests. For more information, check out:
* http://piwik.org/docs/analytics-api/calling-techniques
*
* Parameters are passed automatically from the GET request to the API functions.
*
* Common API uses include:
* - requesting stats for a given date and period, for one or several websites
* - creating, editing, deleting entities (Goals, Websites, Users)
* - any logic that could be useful to a larger scope than the Controller (make a setting editable for example)
*
* It is highly recommended that all the plugin logic is done inside API implementations, and the
* Controller and other objects would all call the API internally using, eg.
* Piwik_ExampleAPI_API::getInstance()->getSum(1, 2);
*
*/
static private $instance = null;
/**
* Singleton
* @return Piwik_ExampleAPI_API
*/
static public function getInstance()
{
if (self::$instance == null) {
self::$instance = new self;
}
return self::$instance;
}
/**
* Get Piwik version
* @return string
*/
public function getPiwikVersion()
{
Piwik::checkUserHasSomeViewAccess();
return Piwik_Version::VERSION;
}
/**
* Get Answer to Life
* @return integer
*/
public function getAnswerToLife()
{
return 42;
}
/**
* Returns a custom object.
* API format conversion will fail for this custom object.
* If used internally, the data structure can be returned untouched by using
* the API parameter 'format=original'
*
* @return Piwik_MagicObject Will return a standard Piwik error when called from the Web APIs
*/
public function getObject()
{
return new Piwik_MagicObject();
}
/**
* Sums two floats and returns the result.
* The paramaters are set automatically from the GET request
* when the API function is called. You can also use default values
* as shown in this example.
*
* @param float|int $a
* @param float|int $b
* @return float
*/
public function getSum($a = 0, $b = 0)
{
return (float)($a + $b);
}
/**
* Returns null value
*
* @return null
*/
public function getNull()
{
return null;
}
/**
* Get array of descriptive text
* When called from the Web API, you see that simple arrays like this one
* are automatically converted in the various formats (xml, csv, etc.)
*
* @return array
*/
public function getDescriptionArray()
{
return array('piwik', 'open source', 'web analytics', 'free', 'Strong message: Свободный Тибет');
}
/**
* Returns a custom data table.
* This data table will be converted to all available formats
* when requested in the API request.
*
* @return DataTable
*/
public function getCompetitionDatatable()
{
$dataTable = new DataTable();
$row1 = new Row();
$row1->setColumns(array('name' => 'piwik', 'license' => 'GPL'));
// Rows Metadata is useful to store non stats data for example (logos, urls, etc.)
// When printed out, they are simply merged with columns
$row1->setMetadata('logo', 'logo.png');
$dataTable->addRow($row1);
$dataTable->addRowFromSimpleArray(array('name' => 'google analytics', 'license' => 'commercial'));
return $dataTable;
}
/**
* Get more information on the Answer to Life...
*
* @return string
*/
public function getMoreInformationAnswerToLife()
{
return "Check http://en.wikipedia.org/wiki/The_Answer_to_Life,_the_Universe,_and_Everything";
}
/**
* Returns a Multidimensional Array
* Only supported in JSON
*
* @return array
*/
public function getMultiArray()
{
$return = array(
'Limitation' => array(
"Multi dimensional arrays is only supported by format=JSON",
"Known limitation"
),
'Second Dimension' => array(true, false, 1, 0, 152, 'test', array(42 => 'end')),
);
return $return;
}
}
/**
* Magic Object
*
* @package Piwik_ExamplePlugin
*/
class Piwik_MagicObject
{
function Incredible()
{
return 'Incroyable';
}
protected $wonderful = 'magnifique';
public $great = 'formidable';
}
|
