Skip to content

Commit 0c6f8ff

Browse files
authored
Merge pull request #38 from aternosorg/fetch-methods
⚠️ !Breaking Change! Prefix wrapper methods that send a request with fetch
2 parents f5f977c + 9c83efe commit 0c6f8ff

14 files changed

Lines changed: 506 additions & 291 deletions

‎README.md‎

Lines changed: 26 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,10 @@ This client is a combination of code generated by [OpenAPI Generator](https://op
55
from the Hangar OpenAPI specification and some wrappers around it to improve the usability.
66

77
The generated code can be found in `src/Api` and `src/Model`. It is recommended to use the wrappers in
8-
`src/Client` instead. The wrappers provide methods to fetch related data from the API, the data returned
9-
by the API is available through `getData()`.
8+
`src/Client` instead. The wrappers extend the generated models, so the data returned by the API is available
9+
through the getters of the wrapper, e.g. `$project->getName()`. They also provide methods to fetch related data
10+
from the API. These methods start with `fetch`, e.g. `$project->fetchVersions()`, and send a request each time
11+
they are called. Only `fetchProject()` of `Version` and `ProjectPage` keeps the project once it is known.
1012

1113
## Requirements
1214
- PHP 8.4 or newer
@@ -92,7 +94,7 @@ you can use it like an array. It also has a `getResults()` method which returns
9294
$projects = $hangarClient->getProjects();
9395

9496
foreach ($projects as $project) {
95-
echo $project->getData()->getName() . PHP_EOL;
97+
echo $project->getName() . PHP_EOL;
9698
}
9799

98100
if ($projects->hasNextPage()) {
@@ -130,7 +132,7 @@ $projects = $hangarClient->getProjects($options);
130132
```php
131133
// get a project by its slug or id
132134
$project = $hangarClient->getProject("mclogs");
133-
echo $project->getData()->getName() . ": " . $project->getData()->getStats()->getDownloads() . " downloads" . PHP_EOL;
135+
echo $project->getName() . ": " . $project->getStats()->getDownloads() . " downloads" . PHP_EOL;
134136

135137
// get the project a file belongs to by the SHA-256 hash of the file
136138
$project = $hangarClient->getProjectByVersionHash(hash_file("sha256", "/path/to/plugin.jar"));
@@ -142,30 +144,30 @@ The `Project` wrapper provides methods to fetch related data:
142144
$project = $hangarClient->getProject("mclogs");
143145

144146
// versions of the project (paginated), optionally filtered by channel and platform
145-
$versions = $project->getVersions();
146-
$versions = $project->getVersions("Release", Platform::PAPER);
147+
$versions = $project->fetchVersions();
148+
$versions = $project->fetchVersions("Release", Platform::PAPER);
147149

148150
// a specific version by its name
149-
$version = $project->getVersion("3.3.4");
151+
$version = $project->fetchVersion("3.3.4");
150152

151153
// the owner of the project
152-
$owner = $project->getOwner();
154+
$owner = $project->fetchOwner();
153155

154156
// members, stargazers and watchers of the project (paginated)
155-
$members = $project->getMembers();
156-
$stargazers = $project->getStarGazers();
157-
$watchers = $project->getWatchers();
157+
$members = $project->fetchMembers();
158+
$stargazers = $project->fetchStarGazers();
159+
$watchers = $project->fetchWatchers();
158160

159161
// pages of the project
160-
$mainPage = $project->getMainPage();
161-
$page = $project->getPage("config");
162+
$mainPage = $project->fetchMainPage();
163+
$page = $project->fetchPage("config");
162164
```
163165

164166
The daily stats of a project require an API key of a member of the project:
165167
```php
166168
// stats since the project was created, or for a specific period
167-
$stats = $project->getDailyStats();
168-
$stats = $project->getDailyStats(new DateTime("2026-01-01"), new DateTime("2026-02-01"));
169+
$stats = $project->fetchDailyStats();
170+
$stats = $project->fetchDailyStats(new DateTime("2026-01-01"), new DateTime("2026-02-01"));
169171

170172
foreach ($stats as $date => $dayStats) {
171173
echo $date . ": " . $dayStats->getDownloads() . " downloads, " . $dayStats->getViews() . " views" . PHP_EOL;
@@ -176,8 +178,8 @@ foreach ($stats as $date => $dayStats) {
176178
Some methods, e.g. the projects a user has starred, return `CompactProject` objects. They contain less data,
177179
but provide the same methods as `Project`. You can fetch the full project:
178180
```php
179-
foreach ($hangarClient->getUser("Aternos")->getStarredProjects() as $compactProject) {
180-
$project = $compactProject->getProject();
181+
foreach ($hangarClient->getUser("Aternos")->fetchStarredProjects() as $compactProject) {
182+
$project = $compactProject->fetchProject();
181183
}
182184
```
183185

@@ -202,12 +204,12 @@ $latestRelease = $hangarClient->getLatestReleaseVersion("mclogs");
202204
$latestVersion = $hangarClient->getLatestVersion("mclogs", "Release");
203205

204206
// get the project of a version
205-
$project = $version->getProject();
207+
$project = $version->fetchProject();
206208
```
207209

208210
The daily stats of a version require an API key:
209211
```php
210-
$stats = $version->getDailyStats();
212+
$stats = $version->fetchDailyStats();
211213

212214
foreach ($stats as $date => $dayStats) {
213215
echo $date . ": " . $dayStats->getTotalDownloads() . " downloads" . PHP_EOL;
@@ -222,7 +224,7 @@ use Aternos\HangarApi\Client\Options\UserSearch\UserSortField;
222224

223225
// get a user by name
224226
$user = $hangarClient->getUser("Aternos");
225-
echo $user->getData()->getName() . ": " . $user->getData()->getProjectCount() . " projects" . PHP_EOL;
227+
echo $user->getName() . ": " . $user->getProjectCount() . " projects" . PHP_EOL;
226228

227229
// search for users (paginated)
228230
$users = $hangarClient->getUsers(new UserSearchOptions()->setQuery("aternos")->setSort(UserSortField::NAME));
@@ -232,14 +234,14 @@ $staff = $hangarClient->getStaff(sort: StaffSortField::ROLES);
232234
$authors = $hangarClient->getAuthors("aternos");
233235

234236
// get the projects of a user (paginated)
235-
$projects = $user->getProjects();
237+
$projects = $user->fetchProjects();
236238

237239
// get the projects a user has starred or is watching (paginated)
238-
$starredProjects = $user->getStarredProjects();
239-
$watchedProjects = $user->getWatchedProjects();
240+
$starredProjects = $user->fetchStarredProjects();
241+
$watchedProjects = $user->fetchWatchedProjects();
240242

241243
// get the projects a user has pinned on their profile
242-
$pinnedProjects = $user->getPinnedProjects();
244+
$pinnedProjects = $user->fetchPinnedProjects();
243245
```
244246

245247
## Project Pages

‎src/Client/CompactProject.php‎

Lines changed: 41 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -18,59 +18,49 @@
1818
* @package Aternos\HangarApi\Client
1919
* @description This class wraps a compact project (a project with fewer fields) and allows you to fetch additional data.
2020
*/
21-
class CompactProject
21+
class CompactProject extends ProjectCompact
2222
{
23+
/**
24+
* @param HangarAPIClient $client
25+
* @param ProjectCompact $data
26+
*/
2327
public function __construct(
2428
protected HangarAPIClient $client,
25-
protected ProjectCompact $project,
29+
ProjectCompact $data,
2630
)
2731
{
32+
parent::__construct($data->container);
2833
}
2934

3035
/**
31-
* @return ProjectCompact
32-
*/
33-
public function getData(): ProjectCompact
34-
{
35-
return $this->project;
36-
}
37-
38-
/**
39-
* Get the slug of this project (shorthand for getData()->getNamespace()->getSlug())
36+
* Get the slug of this project (shorthand for getNamespace()->getSlug())
4037
* @return string
4138
*/
4239
public function getSlug(): string
4340
{
44-
return $this->project->getNamespace()->getSlug();
45-
}
46-
47-
/**
48-
* Get the id of this project (shorthand for getData()->getId())
49-
* @return int
50-
*/
51-
public function getId(): int
52-
{
53-
return $this->project->getId();
41+
return $this->getNamespace()->getSlug();
5442
}
5543

5644
/**
57-
* Get the full project data
45+
* Fetch the full project data
46+
* This sends a request to the Hangar API every time it is called.
5847
* @return Project
5948
* @throws ApiException
6049
*/
61-
public function getProject(): Project
50+
public function fetchProject(): Project
6251
{
6352
return $this->client->getProject($this->getId());
6453
}
6554

6655
/**
67-
* Get all versions of this project (paginated)
56+
* Fetch all versions of this project (paginated)
57+
* This sends a request to the Hangar API every time it is called.
6858
* @param string|null $channel
6959
* @param Platform|null $platform
7060
* @return ProjectVersionList
7161
* @throws ApiException
7262
*/
73-
public function getVersions(?string $channel = null, ?Platform $platform = null): ProjectVersionList
63+
public function fetchVersions(?string $channel = null, ?Platform $platform = null): ProjectVersionList
7464
{
7565
$options = new VersionSearchOptions($this->getId());
7666
$options->setChannel($channel);
@@ -79,90 +69,98 @@ public function getVersions(?string $channel = null, ?Platform $platform = null)
7969
}
8070

8171
/**
82-
* get a single version
72+
* Fetch a single version
73+
* This sends a request to the Hangar API every time it is called.
8374
* @param string $name
8475
* @return Version
8576
* @throws ApiException
8677
*/
87-
public function getVersion(string $name): Version
78+
public function fetchVersion(string $name): Version
8879
{
8980
return $this->client->getVersion($this->getId(), $name);
9081
}
9182

9283
/**
93-
* Get all watchers of this project (paginated)
84+
* Fetch all watchers of this project (paginated)
85+
* This sends a request to the Hangar API every time it is called.
9486
* @return UserList
9587
* @throws ApiException
9688
*/
97-
public function getWatchers(): UserList
89+
public function fetchWatchers(): UserList
9890
{
9991
return $this->client->getProjectWatchers($this->getId());
10092
}
10193

10294
/**
103-
* Get a list of daily project stats
95+
* Fetch a list of daily project stats
10496
* Days without downloads/views are not be included
97+
* This sends a request to the Hangar API every time it is called.
10598
* @param DateTime|null $from default: project creation date
10699
* @param DateTime|null $to default: now
107100
* @return array<string, DayProjectStats>
108101
* @throws ApiException
109102
*/
110-
public function getDailyStats(?DateTime $from = null, ?DateTime $to = null): array
103+
public function fetchDailyStats(?DateTime $from = null, ?DateTime $to = null): array
111104
{
112105
return $this->client->getDailyProjectStats(
113106
$this->getId(),
114-
$from ?? $this->getData()->getCreatedAt(),
107+
$from ?? $this->getCreatedAt(),
115108
$to
116109
);
117110
}
118111

119112
/**
120-
* Get a list of users who starred this project (paginated)
113+
* Fetch a list of users who starred this project (paginated)
114+
* This sends a request to the Hangar API every time it is called.
121115
* @return UserList
122116
* @throws ApiException
123117
*/
124-
public function getStarGazers(): UserList
118+
public function fetchStarGazers(): UserList
125119
{
126120
return $this->client->getProjectStarGazers($this->getId());
127121
}
128122

129123
/**
130-
* Get a list of users who are members of this project (paginated)
124+
* Fetch a list of users who are members of this project (paginated)
125+
* This sends a request to the Hangar API every time it is called.
131126
* @return ProjectMemberList
132127
* @throws ApiException
133128
*/
134-
public function getMembers(): ProjectMemberList
129+
public function fetchMembers(): ProjectMemberList
135130
{
136131
return $this->client->getProjectMembers($this->getId());
137132
}
138133

139134
/**
140-
* Get the owner of this project
135+
* Fetch the owner of this project
136+
* This sends a request to the Hangar API every time it is called.
141137
* @return User
142138
* @throws ApiException
143139
*/
144-
public function getOwner(): User
140+
public function fetchOwner(): User
145141
{
146-
return $this->client->getUser($this->project->getNamespace()->getOwner());
142+
return $this->client->getUser($this->getNamespace()->getOwner());
147143
}
148144

149145
/**
150-
* Get the main page of this project
146+
* Fetch the main page of this project
147+
* This sends a request to the Hangar API every time it is called.
151148
* @return ProjectPage
152149
* @throws ApiException
153150
*/
154-
public function getMainPage(): ProjectPage
151+
public function fetchMainPage(): ProjectPage
155152
{
156153
return $this->client->getProjectMainPage($this->getId());
157154
}
158155

159156
/**
160-
* Get a page of this project
157+
* Fetch a page of this project
158+
* This sends a request to the Hangar API every time it is called.
161159
* @param string $path
162160
* @return ProjectPage
163161
* @throws ApiException
164162
*/
165-
public function getPage(string $path): ProjectPage
163+
public function fetchPage(string $path): ProjectPage
166164
{
167165
return $this->client->getProjectPage($this->getId(), $path);
168166
}

0 commit comments

Comments
 (0)