Skip to content

Commit 665b9d8

Browse files
roberto-buttiroberto-butti
committed
Add AppApi and AppProvisionApi endpoints for managing apps and app provisions
1 parent 168a5e1 commit 665b9d8

21 files changed

+1040
-0
lines changed

‎CHANGELOG.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,11 @@
11
# Changelog
22

33
## 1.1.3 - WIP
4+
- Adding `AppApi` endpoint for listing and getting apps from the Storyblok marketplace
5+
- Adding `AppProvisionApi` endpoint for managing installed apps (list, get, install, uninstall)
6+
- Adding `App`, `Apps`, `AppProvision`, `AppProvisions` data classes
7+
- Adding `AppResponse`, `AppsResponse`, `AppProvisionResponse`, `AppProvisionsResponse` response classes
8+
- Adding `AppsParams` query parameter class for filtering apps by space ID with pagination
49
- Adding `SpacesParams` with `search` parameter for filtering spaces by name in `SpaceApi::all()`
510
- Adding `isNestable()`, `isContentType()`, `isUniversal()`, and `getComponentTypeDetail()` helper methods for Component
611
- Adding User helper methods: `friendlyName()`, `altEmail()`, `phone()`, `lang()`, `loginStrategy()`, `jobRole()`, `partnerRole()`, `isEditor()`, `isSso()`

‎README.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1299,6 +1299,155 @@ According to the structure of the Management API, when creating a new workflow s
12991299
- `commentMessage`: a text message added to the stage change, useful for providing context or reviewer instructions.
13001300
- `notify`: a boolean indicating whether Storyblok should send notifications to users associated with the workflow stage.
13011301

1302+
## Handling Apps
1303+
1304+
For using the `AppApi` class you have to import:
1305+
1306+
```php
1307+
use Storyblok\ManagementApi\Endpoints\AppApi;
1308+
```
1309+
1310+
For using the `App` class you have to import:
1311+
1312+
```php
1313+
use Storyblok\ManagementApi\Data\App;
1314+
```
1315+
1316+
### Getting the `AppApi` instance
1317+
1318+
To handle apps, you can start getting the instance of `AppApi` that allows you to access the methods for handling apps. Unlike most endpoints, `AppApi` does not require a space ID in the constructor—the space ID is passed as a parameter to each method.
1319+
1320+
```php
1321+
use Storyblok\ManagementApi\ManagementApiClient;
1322+
$client = new ManagementApiClient($storyblokPersonalAccessToken);
1323+
1324+
$appApi = new AppApi($client);
1325+
```
1326+
1327+
### Getting the apps list
1328+
1329+
To get the apps list you can use the `page` method from `AppApi` class. You need to provide an `AppsParams` object with the space ID and optional pagination parameters.
1330+
1331+
```php
1332+
use Storyblok\ManagementApi\QueryParameters\AppsParams;
1333+
1334+
$spaceId = "your-space-id";
1335+
$params = new AppsParams(spaceId: $spaceId);
1336+
// you can also set page and perPage:
1337+
// $params = new AppsParams(spaceId: $spaceId, page: 1, perPage: 25);
1338+
$response = $appApi->page($params);
1339+
$apps = $response->data();
1340+
echo "Apps count: " . $apps->howManyApps() . PHP_EOL;
1341+
foreach ($apps as $app) {
1342+
echo $app->name() . PHP_EOL;
1343+
echo $app->slug() . PHP_EOL;
1344+
echo $app->status() . PHP_EOL;
1345+
echo "---" . PHP_EOL;
1346+
}
1347+
```
1348+
1349+
### Getting a single app
1350+
1351+
To get a single app by its ID, you can use the `get` method. You need to provide the app ID and the space ID.
1352+
1353+
```php
1354+
$appId = 14;
1355+
$spaceId = "your-space-id";
1356+
$response = $appApi->get($appId, $spaceId);
1357+
$app = $response->data();
1358+
echo $app->name() . PHP_EOL;
1359+
echo $app->slug() . PHP_EOL;
1360+
echo $app->description() . PHP_EOL;
1361+
echo $app->author() . PHP_EOL;
1362+
echo $app->status() . PHP_EOL;
1363+
```
1364+
1365+
## Handling App Provisions
1366+
1367+
App provisions allow you to install, list, get, and uninstall apps in a specific space.
1368+
1369+
For using the `AppProvisionApi` class you have to import:
1370+
1371+
```php
1372+
use Storyblok\ManagementApi\Endpoints\AppProvisionApi;
1373+
```
1374+
1375+
For using the `AppProvision` class you have to import:
1376+
1377+
```php
1378+
use Storyblok\ManagementApi\Data\AppProvision;
1379+
```
1380+
1381+
### Getting the `AppProvisionApi` instance
1382+
1383+
To handle app provisions, get an instance of `AppProvisionApi` by providing the client and the space ID.
1384+
1385+
```php
1386+
use Storyblok\ManagementApi\ManagementApiClient;
1387+
$client = new ManagementApiClient($storyblokPersonalAccessToken);
1388+
1389+
$spaceId = "your-space-id";
1390+
$appProvisionApi = new AppProvisionApi($client, $spaceId);
1391+
```
1392+
1393+
### Listing installed apps
1394+
1395+
To get the list of installed apps (app provisions) in a space, you can use the `page` method.
1396+
1397+
```php
1398+
$response = $appProvisionApi->page();
1399+
$appProvisions = $response->data();
1400+
echo "Installed apps: " . $appProvisions->howManyAppProvisions() . PHP_EOL;
1401+
foreach ($appProvisions as $appProvision) {
1402+
echo $appProvision->name() . PHP_EOL;
1403+
echo $appProvision->slug() . PHP_EOL;
1404+
echo $appProvision->appId() . PHP_EOL;
1405+
echo "---" . PHP_EOL;
1406+
}
1407+
```
1408+
1409+
### Getting a single app provision
1410+
1411+
To get a single app provision by the app ID, you can use the `get` method.
1412+
1413+
```php
1414+
$appId = 14;
1415+
$response = $appProvisionApi->get($appId);
1416+
$appProvision = $response->data();
1417+
echo $appProvision->name() . PHP_EOL;
1418+
echo $appProvision->slug() . PHP_EOL;
1419+
echo $appProvision->planLevel() . PHP_EOL;
1420+
```
1421+
1422+
### Installing an app
1423+
1424+
To install an app in a space, you can use the `install` method by providing the app ID.
1425+
1426+
```php
1427+
$appId = 14;
1428+
$response = $appProvisionApi->install($appId);
1429+
if ($response->isOk()) {
1430+
$appProvision = $response->data();
1431+
echo "Installed: " . $appProvision->name() . PHP_EOL;
1432+
} else {
1433+
echo $response->getErrorMessage();
1434+
}
1435+
```
1436+
1437+
### Uninstalling an app
1438+
1439+
To uninstall an app from a space, you can use the `delete` method by providing the app ID. A successful deletion returns a 204 status code.
1440+
1441+
```php
1442+
$appId = 14;
1443+
$response = $appProvisionApi->delete($appId);
1444+
if ($response->isOk()) {
1445+
echo "App uninstalled successfully" . PHP_EOL;
1446+
} else {
1447+
echo $response->getErrorMessage();
1448+
}
1449+
```
1450+
13021451
## Using the `ManagementApi` class
13031452

13041453
To illustrate how to use the `ManagementApi` class, we will demonstrate its usage with the Internal Tags endpoint.

‎src/Data/App.php‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace Storyblok\ManagementApi\Data;
6+
7+
use Storyblok\ManagementApi\Exceptions\StoryblokFormatException;
8+
9+
class App extends BaseData
10+
{
11+
public function __construct(
12+
string $name
13+
) {
14+
$this->data = [];
15+
$this->data['name'] = $name;
16+
}
17+
18+
/**
19+
* @param mixed[] $data
20+
* @throws StoryblokFormatException
21+
*/
22+
public static function make(array $data = []): self
23+
{
24+
$dataObject = new StoryblokData($data);
25+
if (!($dataObject->hasKey('name'))) {
26+
// is not valid
27+
}
28+
29+
$app = new self(
30+
$dataObject->getString("name")
31+
);
32+
$app->setData($dataObject->toArray());
33+
// validate
34+
if (! $app->isValid()) {
35+
throw new StoryblokFormatException("App is not valid");
36+
}
37+
38+
return $app;
39+
}
40+
41+
public function isValid(): bool
42+
{
43+
return $this->hasKey('name');
44+
}
45+
46+
public function name(): string
47+
{
48+
return $this->getString('name');
49+
}
50+
51+
public function id(): string
52+
{
53+
return $this->getString('id');
54+
}
55+
56+
public function slug(): string
57+
{
58+
return $this->getString('slug');
59+
}
60+
61+
public function icon(): string
62+
{
63+
return $this->getString('icon');
64+
}
65+
66+
public function description(): string
67+
{
68+
return $this->getString('description');
69+
}
70+
71+
public function intro(): string
72+
{
73+
return $this->getString('intro');
74+
}
75+
76+
public function status(): string
77+
{
78+
return $this->getString('status');
79+
}
80+
81+
public function author(): string
82+
{
83+
return $this->getString('author');
84+
}
85+
86+
public function website(): string
87+
{
88+
return $this->getString('website');
89+
}
90+
91+
public function planLevel(): int|null
92+
{
93+
return $this->getInt('plan_level');
94+
}
95+
96+
public function updatedAt(): string
97+
{
98+
return $this->getString('updated_at');
99+
}
100+
101+
public function inSidebar(): bool
102+
{
103+
return $this->getBoolean('in_sidebar', false);
104+
}
105+
106+
public function inToolbar(): bool
107+
{
108+
return $this->getBoolean('in_toolbar', false);
109+
}
110+
}

‎src/Data/AppProvision.php‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace Storyblok\ManagementApi\Data;
6+
7+
use Storyblok\ManagementApi\Exceptions\StoryblokFormatException;
8+
9+
class AppProvision extends BaseData
10+
{
11+
public function __construct(
12+
string $name
13+
) {
14+
$this->data = [];
15+
$this->data['name'] = $name;
16+
}
17+
18+
/**
19+
* @param mixed[] $data
20+
* @throws StoryblokFormatException
21+
*/
22+
public static function make(array $data = []): self
23+
{
24+
$dataObject = new StoryblokData($data);
25+
if (!($dataObject->hasKey('name'))) {
26+
// is not valid
27+
}
28+
29+
$appProvision = new self(
30+
$dataObject->getString("name")
31+
);
32+
$appProvision->setData($dataObject->toArray());
33+
// validate
34+
if (! $appProvision->isValid()) {
35+
throw new StoryblokFormatException("AppProvision is not valid");
36+
}
37+
38+
return $appProvision;
39+
}
40+
41+
public function isValid(): bool
42+
{
43+
return $this->hasKey('name');
44+
}
45+
46+
public function name(): string
47+
{
48+
return $this->getString('name');
49+
}
50+
51+
public function appId(): string
52+
{
53+
return $this->getString('app_id');
54+
}
55+
56+
public function slug(): string
57+
{
58+
return $this->getString('slug');
59+
}
60+
61+
public function planLevel(): int|null
62+
{
63+
return $this->getInt('plan_level');
64+
}
65+
66+
public function inSidebar(): bool
67+
{
68+
return $this->getBoolean('in_sidebar', false);
69+
}
70+
71+
public function inToolbar(): bool
72+
{
73+
return $this->getBoolean('in_toolbar', false);
74+
}
75+
76+
public function enableSpaceSettings(): bool
77+
{
78+
return $this->getBoolean('enable_space_settings', false);
79+
}
80+
}

‎src/Data/AppProvisions.php‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace Storyblok\ManagementApi\Data;
6+
7+
class AppProvisions extends StoryblokData
8+
{
9+
#[\Override]
10+
public function getDataClass(): string
11+
{
12+
return AppProvision::class;
13+
}
14+
15+
/**
16+
* @param mixed[] $data
17+
*/
18+
#[\Override]
19+
public static function make(array $data = []): self
20+
{
21+
return new self($data);
22+
}
23+
24+
public function howManyAppProvisions(): int
25+
{
26+
return $this->count();
27+
}
28+
}

0 commit comments

Comments
 (0)