[Assets] Add video thumbnail status endpoint for Studio polling

src/Asset/Controller/Video/ThumbnailStatusController.php

@@ -0,0 +1,97 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * This source file is available under the terms of the
+ * Pimcore Open Core License (POCL)
+ * Full copyright and license information is available in
+ * LICENSE.md which is distributed with this source code.
+ *
+ *  @copyright  Copyright (c) Pimcore GmbH (https://www.pimcore.com)
+ *  @license    Pimcore Open Core License (POCL)
+ */
+
+namespace Pimcore\Bundle\StudioBackendBundle\Asset\Controller\Video;
+
+use OpenApi\Attributes\Get;
+use OpenApi\Attributes\JsonContent;
+use Pimcore\Bundle\StudioBackendBundle\Asset\OpenApi\Attribute\Parameter\Path\ThumbnailNameParameter;
+use Pimcore\Bundle\StudioBackendBundle\Asset\Schema\Type\Video\VideoThumbnailStatus;
+use Pimcore\Bundle\StudioBackendBundle\Asset\Service\AssetServiceInterface;
+use Pimcore\Bundle\StudioBackendBundle\Asset\Service\VideoServiceInterface;
+use Pimcore\Bundle\StudioBackendBundle\Controller\AbstractApiController;
+use Pimcore\Bundle\StudioBackendBundle\Exception\Api\ForbiddenException;
+use Pimcore\Bundle\StudioBackendBundle\Exception\Api\InvalidElementTypeException;
+use Pimcore\Bundle\StudioBackendBundle\Exception\Api\InvalidThumbnailException;
+use Pimcore\Bundle\StudioBackendBundle\Exception\Api\NotFoundException;
+use Pimcore\Bundle\StudioBackendBundle\Exception\Api\UserNotFoundException;
+use Pimcore\Bundle\StudioBackendBundle\OpenApi\Attribute\Parameter\Path\IdParameter;
+use Pimcore\Bundle\StudioBackendBundle\OpenApi\Attribute\Response\DefaultResponses;
+use Pimcore\Bundle\StudioBackendBundle\OpenApi\Attribute\Response\SuccessResponse;
+use Pimcore\Bundle\StudioBackendBundle\OpenApi\Config\Tags;
+use Pimcore\Bundle\StudioBackendBundle\Security\Service\SecurityServiceInterface;
+use Pimcore\Bundle\StudioBackendBundle\Util\Constant\HttpResponseCodes;
+use Pimcore\Bundle\StudioBackendBundle\Util\Constant\UserPermissions;
+use Symfony\Component\HttpFoundation\JsonResponse;
+use Symfony\Component\Routing\Attribute\Route;
+use Symfony\Component\Security\Http\Attribute\IsGranted;
+use Symfony\Component\Serializer\SerializerInterface;
+
+/**
+ * @internal
+ */
+final class ThumbnailStatusController extends AbstractApiController
+{
+    public function __construct(
+        SerializerInterface $serializer,
+        private readonly AssetServiceInterface $assetService,
+        private readonly SecurityServiceInterface $securityService,
+        private readonly VideoServiceInterface $videoService,
+    ) {
+        parent::__construct($serializer);
+    }
+
+    /**
+     * @throws ForbiddenException
+     * @throws InvalidElementTypeException
+     * @throws InvalidThumbnailException
+     * @throws NotFoundException
+     * @throws UserNotFoundException
+     */
+    #[Route(
+        '/assets/{id}/video/thumbnail/{thumbnailName}/status',
+        name: 'pimcore_studio_api_video_thumbnail_status',
+        methods: ['GET']
+    )]
+    #[IsGranted(UserPermissions::ASSETS->value)]
+    #[Get(
+        path: self::PREFIX . '/assets/{id}/video/thumbnail/{thumbnailName}/status',
+        operationId: 'asset_video_thumbnail_status',
+        description: 'asset_video_thumbnail_status_description',
+        summary: 'asset_video_thumbnail_status_summary',
+        tags: [Tags::Assets->name]
+    )]
+    #[IdParameter(type: 'video')]
+    #[ThumbnailNameParameter]
+    #[SuccessResponse(
+        description: 'asset_video_thumbnail_status_success_response',
+        content: new JsonContent(ref: VideoThumbnailStatus::class)
+    )]
+    #[DefaultResponses([
+        HttpResponseCodes::BAD_REQUEST,
+        HttpResponseCodes::FORBIDDEN,
+        HttpResponseCodes::UNAUTHORIZED,
+        HttpResponseCodes::NOT_FOUND,
+    ])]
+    public function getVideoThumbnailStatus(int $id, string $thumbnailName): JsonResponse
+    {
+        $asset = $this->assetService->getAssetElement(
+            $this->securityService->getCurrentUser(),
+            $id
+        );
+
+        return $this->jsonResponse(
+            $this->videoService->getThumbnailStatus($asset, $thumbnailName)
+        );
+    }
+}

src/Asset/Schema/Type/Video/VideoThumbnailStatus.php

@@ -0,0 +1,59 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * This source file is available under the terms of the
+ * Pimcore Open Core License (POCL)
+ * Full copyright and license information is available in
+ * LICENSE.md which is distributed with this source code.
+ *
+ *  @copyright  Copyright (c) Pimcore GmbH (https://www.pimcore.com)
+ *  @license    Pimcore Open Core License (POCL)
+ */
+
+namespace Pimcore\Bundle\StudioBackendBundle\Asset\Schema\Type\Video;
+
+use OpenApi\Attributes\Property;
+use OpenApi\Attributes\Schema;
+use Pimcore\Bundle\StudioBackendBundle\Util\Schema\AdditionalAttributesInterface;
+use Pimcore\Bundle\StudioBackendBundle\Util\Trait\AdditionalAttributesTrait;
+
+#[Schema(
+    schema: 'VideoThumbnailStatus',
+    title: 'Video Thumbnail Status',
+    required: ['status'],
+    type: 'object'
+)]
+final class VideoThumbnailStatus implements AdditionalAttributesInterface
+{
+    use AdditionalAttributesTrait;
+
+    public const string STATUS_FINISHED = 'finished';
+
+    public const string STATUS_INPROGRESS = 'inprogress';
+
+    public const string STATUS_ERROR = 'error';
+
+    public const string STATUS_NOT_STARTED = 'not_started';
+
+    public function __construct(
+        #[Property(
+            description: 'Conversion status of the requested video thumbnail.',
+            type: 'string',
+            enum: [
+                self::STATUS_FINISHED,
+                self::STATUS_INPROGRESS,
+                self::STATUS_ERROR,
+                self::STATUS_NOT_STARTED,
+            ],
+            example: self::STATUS_INPROGRESS,
+        )]
+        private readonly string $status,
+    ) {
+    }
+
+    public function getStatus(): string
+    {
+        return $this->status;
+    }
+}

src/Asset/Service/VideoService.php

@@ -14,7 +14,12 @@
 namespace Pimcore\Bundle\StudioBackendBundle\Asset\Service;
 
 use Pimcore\Bundle\StudioBackendBundle\Asset\Event\PreResponse\VideoTypeEvent;
+use Pimcore\Bundle\StudioBackendBundle\Asset\Schema\Type\Video\VideoThumbnailStatus;
 use Pimcore\Bundle\StudioBackendBundle\Asset\Schema\Type\Video\VideoType;
+use Pimcore\Bundle\StudioBackendBundle\Exception\Api\InvalidElementTypeException;
+use Pimcore\Bundle\StudioBackendBundle\Util\Constant\ElementTypes;
+use Pimcore\Model\Asset;
+use Pimcore\Model\Asset\Video as VideoAsset;
 use Pimcore\Model\DataObject\ClassDefinition\Data\Video;
 use Symfony\Component\EventDispatcher\EventDispatcherInterface;
 
@@ -25,6 +30,7 @@
 {
     public function __construct(
         private EventDispatcherInterface $eventDispatcher,
+        private ThumbnailServiceInterface $thumbnailService,
     ) {
     }
 
@@ -40,4 +46,23 @@
 
         return $types;
     }
+
+    public function getThumbnailStatus(Asset $video, string $thumbnailName): VideoThumbnailStatus
+    {
+        if (!$video instanceof VideoAsset) {
+            throw new InvalidElementTypeException($video->getType(), ElementTypes::TYPE_ASSET);
+        }
+
+        $configuration = $this->thumbnailService->getVideoThumbnailConfig($thumbnailName);
+
+        // Read the status from the custom setting directly: Asset\Video::getThumbnail() would
+        // start a conversion as a side effect and returns null for errored conversions,
+        // which would make the error status unreachable for polling clients.
+        $customSetting = $video->getCustomSetting('thumbnails');
+        $status = is_array($customSetting)
+            ? ($customSetting[$configuration->getName()]['status'] ?? VideoThumbnailStatus::STATUS_NOT_STARTED)
+            : VideoThumbnailStatus::STATUS_NOT_STARTED;
+
+        return new VideoThumbnailStatus((string) $status);
+    }
 }

src/Asset/Service/VideoServiceInterface.php

@@ -13,7 +13,11 @@
 
 namespace Pimcore\Bundle\StudioBackendBundle\Asset\Service;
 
+use Pimcore\Bundle\StudioBackendBundle\Asset\Schema\Type\Video\VideoThumbnailStatus;
 use Pimcore\Bundle\StudioBackendBundle\Asset\Schema\Type\Video\VideoType;
+use Pimcore\Bundle\StudioBackendBundle\Exception\Api\InvalidElementTypeException;
+use Pimcore\Bundle\StudioBackendBundle\Exception\Api\InvalidThumbnailException;
+use Pimcore\Model\Asset;
 
 /**
  * @internal
@@ -24,4 +28,10 @@
      * @return VideoType[]
      */
     public function getVideoTypes(): array;
+
+    /**
+     * @throws InvalidElementTypeException
+     * @throws InvalidThumbnailException
+     */
+    public function getThumbnailStatus(Asset $video, string $thumbnailName): VideoThumbnailStatus;
 }

tests/Unit/Asset/Service/VideoServiceTest.php

@@ -0,0 +1,104 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * This source file is available under the terms of the
+ * Pimcore Open Core License (POCL)
+ * Full copyright and license information is available in
+ * LICENSE.md which is distributed with this source code.
+ *
+ *  @copyright  Copyright (c) Pimcore GmbH (https://www.pimcore.com)
+ *  @license    Pimcore Open Core License (POCL)
+ */
+
+namespace Pimcore\Bundle\StudioBackendBundle\Tests\Unit\Asset\Service;
+
+use Codeception\Test\Unit;
+use Exception;
+use Pimcore\Bundle\StudioBackendBundle\Asset\Schema\Type\Video\VideoThumbnailStatus;
+use Pimcore\Bundle\StudioBackendBundle\Asset\Service\ThumbnailServiceInterface;
+use Pimcore\Bundle\StudioBackendBundle\Asset\Service\VideoService;
+use Pimcore\Bundle\StudioBackendBundle\Asset\Service\VideoServiceInterface;
+use Pimcore\Bundle\StudioBackendBundle\Exception\Api\InvalidElementTypeException;
+use Pimcore\Model\Asset\Document;
+use Pimcore\Model\Asset\Video;
+use Pimcore\Model\Asset\Video\Thumbnail\Config;
+use Symfony\Component\EventDispatcher\EventDispatcherInterface;
+
+/**
+ * @internal
+ */
+final class VideoServiceTest extends Unit
+{
+    private const string THUMBNAIL_NAME = 'content';
+
+    public function testGetThumbnailStatusWithWrongElementType(): void
+    {
+        $this->expectException(InvalidElementTypeException::class);
+
+        $this->getVideoService()->getThumbnailStatus(new Document(), self::THUMBNAIL_NAME);
+    }
+
+    /**
+     * @throws Exception
+     */
+    public function testGetThumbnailStatusReturnsStatusFromCustomSetting(): void
+    {
+        $video = $this->makeEmpty(Video::class, [
+            'getCustomSetting' => [
+                self::THUMBNAIL_NAME => [
+                    'status' => VideoThumbnailStatus::STATUS_ERROR,
+                ],
+            ],
+        ]);
+
+        $status = $this->getVideoService()->getThumbnailStatus($video, self::THUMBNAIL_NAME);
+
+        $this->assertSame(VideoThumbnailStatus::STATUS_ERROR, $status->getStatus());
+    }
+
+    /**
+     * @throws Exception
+     */
+    public function testGetThumbnailStatusReturnsNotStartedWithoutCustomSetting(): void
+    {
+        $video = $this->makeEmpty(Video::class, [
+            'getCustomSetting' => null,
+        ]);
+
+        $status = $this->getVideoService()->getThumbnailStatus($video, self::THUMBNAIL_NAME);
+
+        $this->assertSame(VideoThumbnailStatus::STATUS_NOT_STARTED, $status->getStatus());
+    }
+
+    /**
+     * @throws Exception
+     */
+    public function testGetThumbnailStatusReturnsNotStartedForUnknownThumbnail(): void
+    {
+        $video = $this->makeEmpty(Video::class, [
+            'getCustomSetting' => [
+                'other-thumbnail' => [
+                    'status' => VideoThumbnailStatus::STATUS_FINISHED,
+                ],
+            ],
+        ]);
+
+        $status = $this->getVideoService()->getThumbnailStatus($video, self::THUMBNAIL_NAME);
+
+        $this->assertSame(VideoThumbnailStatus::STATUS_NOT_STARTED, $status->getStatus());
+    }
+
+    private function getVideoService(): VideoServiceInterface
+    {
+        $config = new Config();
+        $config->setName(self::THUMBNAIL_NAME);
+
+        return new VideoService(
+            $this->makeEmpty(EventDispatcherInterface::class),
+            $this->makeEmpty(ThumbnailServiceInterface::class, [
+                'getVideoThumbnailConfig' => $config,
+            ]),
+        );
+    }
+}

translations/studio_api_docs.en.yaml

@@ -212,6 +212,12 @@ asset_video_stream_by_thumbnail_description: |
   List of <b>thumbnail names</b> can be obtained via the thumbnail video collection endpoint
 asset_video_stream_by_thumbnail_success_response: Video stream based on thumbnail name
 asset_video_stream_by_thumbnail_summary: Stream video asset by ID and thumbnail name
+asset_video_thumbnail_status_description: |
+  Get the conversion status of a video thumbnail based on the provided <strong>{id}</strong> and <strong>{thumbnailName}</strong>. <br>
+  The <strong>{id}</strong> must be an ID of existing asset video <br>
+  List of <b>thumbnail names</b> can be obtained via the thumbnail video collection endpoint
+asset_video_thumbnail_status_success_response: Conversion status of the video thumbnail
+asset_video_thumbnail_status_summary: Get video thumbnail conversion status by asset ID and thumbnail name
 asset_get_search_configuration: Get asset search configuration
 asset_get_search_configuration_description: Get asset configuration
 asset_get_search_configuration_summary: Get asset search configuration