Space improvements: new methods & SpaceEnvironment (Preview URLs) support (#28)

* Adding Space class helpers

* Handling Environments / Preview URLs

Author: roberto-butti

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 1.0.8 - 2025-12-08
+- Space class improvement, added some helper methos like `isOwnedByUser()`, `domain()`, `isDemo()`, `fistToken()`, `removeDemoMode()`
+- Added Space methods for handling environments/Preview URLs
+
 ## 1.0.7 - 2025-12-07
 - Added support for creating workflow stage changes via the Management API.
 

README.md

@@ -185,13 +185,54 @@ $spaceId = "12345";
 $spaceApi = new SpaceApi($clientEU);
 $space = $spaceApi->get($spaceId)->data();
 
-printf(" The name for the Space id : %s is : %s . Plan: %s - %s" ,
+printf(
+    "Space ID: %s\n
+    Name: %s\n
+    Plan: %s (%s)\n
+    Domain: %s\n
+    Is Demo: %s\n
+    First Token: %s\n",
     $spaceId,
     $space->name(),
     $space->planLevel(),
-    $space->planDescription()
+    $space->planDescription(),
+    $space->domain(),
+    $space->isDemo() ? "yes" : "no",
+    $space->firstToken()
 );
 ```
+
+### Environments / Preview URLs
+
+Preview URLs allow you to define multiple environments (domains or locations) for quickly switching between different preview targets inside the story editor—such as local development, staging, or production.
+
+#### Listing Environments
+
+You can retrieve all configured environments for a space and iterate through them:
+
+```php
+foreach ($space->environments() as $key => $environment) {
+    echo "Name: " . $environment->name() . PHP_EOL;
+    echo "Location: " . $environment->location() . PHP_EOL;
+}
+```
+
+#### Adding a New Environment (Preview URL)
+
+To add a new preview environment, create a `SpaceEnvironment` instance and attach it to the space:
+
+```php
+$previewEnvironment = new SpaceEnvironment(
+    "Local Development",
+    $previewURLlocalhost
+);
+
+$editSpace->addEnvironment($previewEnvironment);
+```
+
+You can repeat this for any number of environments—such as staging, QA, production—allowing editors to switch preview contexts seamlessly.
+
+
 ### Update Space settings
 
 You can edit space settings using the `update()` method.

src/Data/Space.php

@@ -16,7 +16,7 @@ class Space extends BaseData
     public function __construct(string $name)
     {
         $this->data = [];
-        $this->data['name'] = $name;
+        $this->data["name"] = $name;
     }
 
     /**
@@ -35,47 +35,85 @@ public static function make(array $data = []): self
         }
 
         return $space;
-
     }
 
     public function setName(string $name): void
     {
-        $this->set('name', $name);
+        $this->set("name", $name);
     }
 
     public function setDomain(string $domain): void
     {
-        $this->set('domain', $domain);
+        $this->set("domain", $domain);
     }
 
     public function name(): string
     {
-        return $this->getString('name', "");
+        return $this->getString("name", "");
     }
 
     public function region(): string
     {
-        return $this->getString('region', "");
+        return $this->getString("region", "");
     }
 
     public function id(): string
     {
-        return $this->getString('id', "");
+        return $this->getString("id", "");
+    }
+
+    /**
+     * Retrieves the domain associated with the Space.
+     *
+     * Returns the value stored under the "domain" key as a string.
+     *
+     * @return string The domain name.
+     */
+    public function domain(): string
+    {
+        return $this->getString("domain");
+    }
+
+    /**
+     * Retrieves the first token associated with the Space.
+     *
+     * Returns the value stored under the "first_token" key.
+     *
+     * @return string The first token, or an empty string if none is defined.
+     */
+    public function firstToken(): string
+    {
+        return $this->getString("first_token", "");
+    }
+
+    public function environments(): SpaceEnvironments
+    {
+        return SpaceEnvironments::make($this->getArray("environments"));
+    }
+
+    public function addEnvironment(
+        SpaceEnvironment $spaceEnvironment,
+    ): SpaceEnvironments {
+        $environments = $this->getArray("environments");
+        $environments[] = $spaceEnvironment->toArray();
+        $this->set("environments", $environments);
+
+        return SpaceEnvironments::make($environments);
     }
 
     public function createdAt(): null|string
     {
-        return $this->getFormattedDateTime('created_at', "", format: "Y-m-d");
+        return $this->getFormattedDateTime("created_at", "", format: "Y-m-d");
     }
 
     public function updatedAt(): null|string
     {
-        return $this->getFormattedDateTime('updated_at', "", format: "Y-m-d");
+        return $this->getFormattedDateTime("updated_at", "", format: "Y-m-d");
     }
 
     public function planLevel(): string
     {
-        return $this->getString('plan_level');
+        return $this->getString("plan_level");
     }
 
     public function planDescription(): null|string
@@ -85,6 +123,39 @@ public function planDescription(): null|string
 
     public function ownerId(): string
     {
-        return $this->getString('owner_id', "");
+        return $this->getString("owner_id", "");
+    }
+
+    /**
+     * Determines whether the current entity is owned by the given user.
+     *
+     * Compares the space's owner ID with the ID of the provided user instance.
+     *
+     * @param User $user The user to check ownership against.
+     * @return bool True if the user owns the entity, false otherwise.
+     */
+    public function isOwnedByUser(User $user): bool
+    {
+        return $this->ownerId() === $user->id();
+    }
+
+    /**
+     * Checks whether the entity is marked as a demo instance.
+     *
+     * Retrieves the `is_demo` flag and returns its boolean value.
+     *
+     * @return bool True if the entity is marked as a demo, false otherwise.
+     */
+    public function isDemo(): bool
+    {
+        return $this->getBoolean("is_demo", false);
+    }
+
+    /**
+     * Remove the Demo mode flag
+     */
+    public function removeDemoMode(): void
+    {
+        $this->set("is_demo", false);
     }
 }

src/Data/SpaceEnvironment.php

@@ -0,0 +1,76 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Storyblok\ManagementApi\Data;
+
+use Storyblok\ManagementApi\Exceptions\StoryblokFormatException;
+
+class SpaceEnvironment extends BaseData
+{
+    public function __construct(string $name, string $location)
+    {
+        $this->data = [];
+        $this->data["location"] = $location;
+        $this->data["name"] = $name;
+    }
+
+    /**
+     * @param mixed[] $data
+     * @throws StoryblokFormatException
+     */
+    public static function make(array $data = []): self
+    {
+        $dataObject = new StoryblokData($data);
+        if (!$dataObject->hasKey("name")) {
+            throw new StoryblokFormatException(
+                "Environments/Preview URL is not valid, missing the name",
+            );
+        }
+
+        if (!$dataObject->hasKey("location")) {
+            throw new StoryblokFormatException(
+                "Environments/Preview URL is not valid, missing the location/URL",
+            );
+        }
+
+        return new self(
+            $dataObject->getString("name"),
+            $dataObject->getString("location"),
+        );
+    }
+
+    public function setName(string $name): void
+    {
+        $this->set("name", $name);
+    }
+
+    /**
+     * Environment/Preview URL name
+     */
+    public function name(): string
+    {
+        return $this->getString("name");
+    }
+
+    public function setLocation(string $location): void
+    {
+        $this->set("location", $location);
+    }
+
+    /**
+     * Environment/Preview URL location
+     */
+    public function location(): string
+    {
+        return $this->getString("location");
+    }
+
+    /**
+     * Validates if the Environment/Preview URL data contains all required fields and valid values
+     */
+    public function isValid(): bool
+    {
+        return $this->hasKey("name") && $this->hasKey("location");
+    }
+}

src/Data/SpaceEnvironments.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Storyblok\ManagementApi\Data;
+
+use Storyblok\ManagementApi\Data\StoryblokData;
+
+class SpaceEnvironments extends StoryblokData
+{
+    #[\Override]
+    public function getDataClass(): string
+    {
+        return SpaceEnvironment::class;
+    }
+
+    #[\Override]
+    public static function make(array $data = []): self
+    {
+        return new self($data);
+    }
+
+    public function howManyEnvironments(): int
+    {
+        return $this->count();
+    }
+}