cloudinary-8.x-1.x-dev/modules/cloudinary_sdk/src/Service/AssetHelperInterface.php

<?php

namespace Drupal\cloudinary_sdk\Service;

use Cloudinary\Asset\AssetType;
use Cloudinary\Asset\Image;
use Cloudinary\Asset\Video;
use Cloudinary\Tag\BaseTag;
use Drupal\cloudinary_media_library_widget\Model\Asset;

/**
 * Define an interface for asset helper service.
 */
interface AssetHelperInterface {

  /**
   * Whether the value from custom form element is applicable for further usage.
   *
   * @param string $value
   *   The value from custom form element.
   *
   * @return bool
   *   TRUE if the value is applicable and can be used by the service.
   */
  public function isApplicable(string $value): bool;

  /**
   * Parse string value into array.
   *
   * @param string $value
   *   The value from custom form element.
   *
   * @return array
   *   The parsed value.
   */
  public function parseValue(string $value): array;

  /**
   * Load asset model by its public id.
   *
   * @param string $public_id
   *   The public id of the asset.
   * @param string $resource_type
   *   The resource type of the asset.
   *
   * @return \Drupal\cloudinary_media_library_widget\Model\Asset
   *   The asset model object.
   */
  public function loadAssetByPublicId(string $public_id, string $resource_type = AssetType::IMAGE): Asset;

  /**
   * Generate preview image based on value from the form element.
   *
   * @param string $value
   *   The value from custom form element.
   * @param int $width
   *   The width of the preview image.
   *
   * @return string|null
   *   Returns an absolute preview image url or NULL if not applicable.
   */
  public function generatePreviewImageUrl(string $value, int $width = 400): ?string;

  /**
   * Render asset based on value from the form element.
   *
   * @param string $value
   *   The value from custom form element.
   *
   * @return array|null
   *   Returns a renderable array of asset or NULL if nothing to render.
   */
  public function renderAsset(string $value): ?array;

  /**
   * Get base tag to manipulate and render later.
   *
   * @param string $value
   *   The value from custom form element.
   *
   * @return \Cloudinary\Tag\BaseTag|null
   *   The cloudinary base tag like VideoTag or ImageTag.
   */
  public function getBaseTag(string $value): ?BaseTag;

  /**
   * Generate string value.
   *
   * @param array $value
   *   The field item value as array.
   *
   * @return string
   *   The value for custom form element.
   */
  public function generateStringValue(array $value): string;

  /**
   * Get base media asset to manipulate and generate url.
   *
   * @param string $value
   *   The value from custom form element.
   *
   * @return \Cloudinary\Asset\Video|\Cloudinary\Asset\Image|null
   *   The asset object if available.
   */
  public function getBaseMediaAsset(string $value): Video|Image|NULL;

}