metricool / app / Http / Metricool / README.md

README.md in Metricool – Social media and site statistics 2.1.1, at app/Http/Metricool/README.md

206 lines 5.8 KB

Raw Download Zip

1	# Metricool Client internal package
2	To use the Client singleton in the App container, you can call the method below. This will return an instance of a Metricool client that you can use to interact with the API:
3	```php
4	/**
5	* Get the MetricoolApi facade to easily access
6	* the Metricool API
7	*/
8	App::getInstance()->client;
9	```
10
11	## Entities Facade
12	To make it easier to interact with the Metricool API, the client provides a facade that allows you to access various entities. These entities represent different aspects of your Metricool account, such as statistics, brands, subscription and more. This means that `App::getInstance()->client` will return an instance of the `MetricoolApi` class.
13
14	### Entities
15	All entities work quite similar. They register their endpoint, require the `MetricoolClient` and can do some basic operations like `get()`, `post()`, `put()`, and `delete()`. If an entity is filterable the Trait `isFilterable` can be used to add the ability to filter the results based on certain criteria. The `getAcceptedFilters()` method should be implemented in each entity to define which filters are accepted.
16
17	#### Example of the brands entity
18	```php
19	class ConnectedBrands
20	{
21	protected MetricoolClient $client;
22	private string $endpoint = 'admin/profiles-auth';
23
24	public function __construct(MetricoolClient $client)
25	{
26	$this->client = $client;
27	}
28
29	public function all(): array
30	{
31	return $this->client->get($this->endpoint);
32	}
33	}
34	```
35	#### Usage
36	```php
37	$response = App::getInstance()->client->connectedBrands()->get();
38	```
39
40	#### Response
41	_Truncated response for readability_
42	```json
43	[
44	{
45	"id": 2221200,
46	"userId": 1826104,
47	"ownerUserId": 1826104,
48	"label": "TestingMetri-Business",
49	"url": "https://help.metricool.com/es/",
50	"title": "Metricool",
51	"description": "Blog & Social Media Finally Together",
52	"picture": "https://static.metricool.com/brand-logo/202506/2221200-file-7594769922755525893.jpeg",
53	...
54	}
55	]
56	```
57
58	## Statistics
59	Statistics are bundled in their own facade, which can be accessed through the `statistics()` method of the client. This allows you to retrieve various statistics related to your Metricool account. They are grouped in two main categories: "distribution" and "timeline". These groups reflect the endpoint that is used to retrieve the data from the Metricool API. The other differences are the amount of accepted filters and the compatible metrics that can be retrieved.
60
61	```php
62	class TimelineStatistics
63	{
64	protected string $endpoint = 'stats/timeline/';
65
66	private array $compatibleMetrics = [
67	'PageViews',
68	'SessionsCount',
69	'Visitors',
70	'DailyPosts',
71	'DailyComments',
72	];
73
74	protected function getAcceptedFilters(): array
75	{
76	return [
77	'start' => '/^\d+$/',
78	'end' => '/^\d+$/',
79	];
80	}
81	}
82
83	class DistributionStatistics
84	{
85	protected string $endpoint = 'stats/distribution/';
86
87	private array $compatibleMetrics = [
88	'country',
89	'referers',
90	'sources',
91	];
92
93	protected function getAcceptedFilters(): array
94	{
95	return [
96	'start' => '/^\d+$/', // Just digits
97	'end' => '/^\d+$/', // Just digits
98	'country' => '/^[a-z]{2}$/', // ISO 3166-1 alpha-2 lowercase country code
99	];
100	}
101	}
102	```
103
104	### Get statistics for the last 7 days
105	```php
106	// Mocking a Request object
107	$request = new Storage([
108	'start' => Carbon::now()->subDays(4)->format('Ymd'),
109	'end' => Carbon::now()->format('Ymd'),
110	]);
111
112	$client = App::getInstance()->client;
113	$response = $client->statistics()->countries()->filter([
114	'start' => $request->getString('start'),
115	'end' => $request->getString('end'),
116	])->get();
117	```
118
119	Response contains reference points (that can be used in the graph) for each day in the specified range, with the date as a timestamp and the value as a string:
120	```json
121	[
122	[
123	"1752170400000",
124	"981.0"
125	],
126	[
127	"1752256800000",
128	"895.0"
129	],
130	[
131	"1752343200000",
132	"487.0"
133	],
134	[
135	"1752429600000",
136	"501.0"
137	]
138	]
139	```
140
141	## Traits
142	Some of the entities use traits for common functionality.
143
144	### isFilterable Trait
145	This trait can be used in entities that support filtering. It provides methods to apply filters to the entity's requests. The `getAcceptedFilters()` method should be implemented in the entity to define which filters are accepted.
146
147	#### Usage
148	```php
149	class ExampleEntity
150	{
151	use isFilterable;
152
153	protected string $endpoint = 'example/endpoint';
154
155	protected function getAcceptedFilters(): array
156	{
157	return [
158	'start' => '/^\d+$/', // Just digits
159	'end' => '/^\d+$/', // Just digits
160	];
161	}
162	}
163
164	// Filtering an entity
165	$response = App::getInstance()->client->example()->filter([
166	'start' => '20230101',
167	'end' => '20230131',
168	])->get();
169
170	// Endpoint that will be requested:
171	// example/endpoint?start=20230101&end=20230131
172	```
173
174	### IsUpdatable Trait
175	This trait can be used in entities that support updating. It provides methods to update the entity's data. The `getFillable()` method should be implemented in the entity to define the properties that can be updated.
176
177	#### Usage
178	```php
179	class ExampleEntity
180	{
181	use IsUpdatable;
182
183	protected string $endpoint = 'example/endpoint';
184
185	protected function getFillable(): array
186	{
187	return ['property1', 'property2'];
188	}
189	}
190
191	// Updating an entity
192	$response = App::getInstance()->client->example()->update([
193	'property1' => 'new value',
194	'property2' => 'another value',
195	'unlistedProperty' => 'should not be included', // This will be ignored
196	]);
197
198	// Endpoint that will be requested:
199	// example/endpoint?fields=new+value&fields=another+value
200
201	// With the payload:
202	// {
203	// "property1": "new value",
204	// "property2": "another value"
205	// }
206	```