foldershare-8.x-1.2/src/FolderShareInterface.php

<?php
 
namespace Drupal\foldershare;
 
use Drupal\Core\Entity\ContentEntityInterface;
use Drupal\Core\Entity\EntityChangedInterface;
use Drupal\user\EntityOwnerInterface;
use Drupal\file\FileInterface;
use Drupal\user\UserInterface;
 
/**
 * Manages a hierarchy of folders, subfolders, and files.
 *
 * Implementations of this class support operations on folders and files
 * within folders. Operations include create, delete, move, copy, rename,
 * and changes to specific fields, such as names, descriptions, dates,
 * and owners.
 *
 * Object instances represent top-level root folders, subfolders, and specific
 * entries in the folders, such as files.
 *
 * @ingroup foldershare
 *
 * @see \Drupal\foldershare\Entity\Folder
 */
interface FolderShareInterface extends ContentEntityInterface, EntityOwnerInterface, EntityChangedInterface {
 
  /*---------------------------------------------------------------------
   *
   * Constants - Special entity IDs.
   *
   *---------------------------------------------------------------------*/
 
  /**
   * Indicates that any user ID matches, when used as a method argument.
   *
   * @var int
   */
  const ANY_USER_ID = (-1000);
 
  /**
   * Indicates that the current user ID matches, when used as a method argument.
   *
   * @var int
   */
  const CURRENT_USER_ID = (-1001);
 
  /**
   * Indicates that any item ID matches, when used as a method argument.
   *
   * @var int
   */
  const ANY_ITEM_ID = (-2000);
 
  /**
   * Indicates the user's own root list (a.k.a. personal root list).
   *
   * @var int
   */
  const USER_ROOT_LIST = (-100);
 
  /**
   * Indicates the public root list.
   *
   * @var int
   */
  const PUBLIC_ROOT_LIST = (-101);
 
  /**
   * Indicates the any-user ("all") root list for admins.
   *
   * @var int
   */
  const ALL_ROOT_LIST = (-102);
 
  /*---------------------------------------------------------------------
   *
   * Constants - Kinds.
   *
   *---------------------------------------------------------------------*/
 
  /**
   * The kind for a folder.
   *
   * @var string
   */
  const FOLDER_KIND = 'folder';
 
  /**
   * The kind for a file.
   *
   * The file is a managed File entity referenced by the FolderShare entity
   * via a 'file' field type.
   *
   * @var string
   */
  const FILE_KIND = 'file';
 
  /**
   * The kind for an image.
   *
   * The file is a managed File entity referenced by the FolderShare entity
   * via a 'image' field type.
   *
   * @var string
   */
  const IMAGE_KIND = 'image';
 
  /**
   * The kind for a media holder.
   *
   * The media is a Media entity referenced by the FolderShare entity
   * via an 'entity_reference' field type.
   *
   * @var string
   */
  const MEDIA_KIND = 'media';
 
  /*---------------------------------------------------------------------
   *
   * Constants - MIME types
   *
   *---------------------------------------------------------------------*/
 
  /**
   * The custom MIME type for folders.
   *
   * There is no official Internet standard for a MIME type for folders,
   * so we are forced to create one. This is primarily used for selecting
   * an icon in the user interface, and this module's styling provides
   * that icon.
   *
   * @var string
   */
  const FOLDER_MIME = 'folder/directory';
 
  /*---------------------------------------------------------------------
   *
   * Constants - Path schemes.
   *
   *---------------------------------------------------------------------*/
 
  /**
   * The personal scheme for the user's own files, or those shared with them.
   *
   * The scheme is used in virtual file and folder paths of the form:
   * - SCHEME://UID/PATH...
   *
   * @var string
   */
  const PERSONAL_SCHEME = "personal";
 
  /**
   * The public scheme for the site's publically accessible files.
   *
   * The scheme is used in virtual file and folder paths of the form:
   * - SCHEME://UID/PATH...
   *
   * The public scheme refers to content owned by another user and shared
   * with the anonymous user, which makes it publically accessible.
   *
   * @var string
   */
  const PUBLIC_SCHEME = "public";
 
  /*---------------------------------------------------------------------
   *
   * Constants - Parameters.
   *
   *---------------------------------------------------------------------*/
 
  /**
   * The maximum number of UTF-8 characters in a file or folder name.
   *
   * The File module imposes an internal limit of 255 characters for
   * file names. FolderShare uses this same limit for consistency.
   *
   * This limit is in *characters*, not bytes. The File and FolderShare
   * modules support UTF-8 names which include multi-byte characters.
   * So, a 255 character name may be use more than 255 bytes.
   *
   * All name handling must be multi-byte character safe. This often
   * means the use of the 'mb_' functions in PHP, such as 'mb_strlen()'.
   *
   * @var int
   */
  const MAX_NAME_LENGTH = 255;
 
  /*---------------------------------------------------------------------
   *
   * Kind field.
   *
   *---------------------------------------------------------------------*/
 
  /**
   * Returns the item's kind.
   *
   * An item's kind characterizes the functionality the item supports:
   * - 'folder': A group of child files and folders.
   * - 'file': An arbitrary data file.
   * - 'image': An image file.
   * - 'media': A media entity, such as a URL to an external video.
   *
   * <B>Example usage</B>
   * Loop through all children of this item and group them by kind:
   * @code
   *   $groups = [
   *     'folder' => [],
   *     'file'   => [],
   *     'image'  => [],
   *     'media'  => [],
   *   ];
   *   foreach ($item->findChildren() as $child) {
   *     $groups[$child->getKind()][] = $child;
   *   }
   * @endcode
   *
   * @return string
   *   Returns the kind of item.
   *
   * @see ::isFile()
   * @see ::isFolder()
   * @see ::isImage()
   * @see ::isMedia()
   * @see ::getMimeType()
   */
  public function getKind();
 
  /**
   * Returns TRUE if this item is a file, and FALSE otherwise.
   *
   * @return bool
   *   Returns TRUE if this item is a file.
   */
  public function isFile();
 
  /**
   * Returns TRUE if this item is a folder, and FALSE otherwise.
   *
   * @return bool
   *   Returns TRUE if this item is a folder.
   */
  public function isFolder();
 
  /**
   * Returns TRUE if this item is an image, and FALSE otherwise.
   *
   * @return bool
   *   Returns TRUE if this item is an image.
   */
  public function isImage();
 
  /**
   * Returns TRUE if this item is a media, and FALSE otherwise.
   *
   * @return bool
   *   Returns TRUE if this item is a media.
   */
  public function isMedia();
 
  /*---------------------------------------------------------------------
   *
   * MIME type field.
   *
   *---------------------------------------------------------------------*/
 
  /**
   * Returns the item's MIME type.
   *
   * If this item is a file or image, the returned MIME type is expected to
   * be that of the underlying stored file or image. If this item is a folder,
   * the FOLDER_MIME string is usually returned.
   *
   * @return string
   *   Returns the MIME type.
   *
   * @see \Drupal\file\FileInterface::getMimeType()
   * @see ::isMimeTypeImage()
   * @see ::FOLDER_MIME
   */
  public function getMimeType();
 
  /*---------------------------------------------------------------------
   *
   * File, Image, and Media fields.
   *
   *---------------------------------------------------------------------*/
 
  /**
   * Returns the item's file ID, if any.
   *
   * For file items, this method returns the File entity ID for the
   * underlying stored file. For all other item kinds, a FALSE is returned.
   *
   * While image items also have a File entity ID, file and image items
   * store their File entity IDs separately. Use getImageId() to get an
   * image item's File entity ID.
   *
   * <B>Example usage</B>
   * Get the File entity ID for file or image items:
   * @code
   *   $fileId = FALSE;
   *   if ($item->isFile() === TRUE) {
   *     $fileId = $item->getFileId();
   *   }
   *   elseif ($item->isImage() === TRUE) {
   *     $fileId = $item->getImageId();
   *   }
   * @endcode
   *
   * @return bool|int
   *   Returns the entity ID of the underlying File entity for file items,
   *   or FALSE if this item is not for a file.
   *
   * @see ::getFile()
   * @see ::getKind()
   * @see ::isFile()
   */
  public function getFileId();
 
  /**
   * Returns the item's File entity, if any.
   *
   * For file items, this method returns the File entity for the
   * underlying stored file. For all other item kinds, a NULL is returned.
   *
   * While image items also have a File entity, file and image items
   * store their File entities separately. Use getImage() to get an
   * image item's File entity.
   *
   * <B>Example usage</B>
   * Get the File entity for file or image items:
   * @code
   *   $file = NULL;
   *   if ($item->isFile() === TRUE) {
   *     $file = $item->getFile();
   *   }
   *   elseif ($item->isImage() === TRUE) {
   *     $file = $item->getImage();
   *   }
   * @endcode
   *
   * @return \Drupal\file\FileInterface
   *   Returns the File entity for the underlying file for file items,
   *   or a NULL if this item is not for a file.
   *
   * @see ::getFileId()
   * @see ::getKind()
   * @see ::isFile()
   */
  public function getFile();
 
  /**
   * Returns the item's image ID, if any.
   *
   * For image items, this method returns the File entity ID for the
   * underlying stored file. For all other item kinds, a FALSE is returned.
   *
   * While file items also have a File entity ID, file and image items
   * store their File entity IDs separately. Use getFileId() to get a
   * file item's File entity ID.
   *
   * <B>Example usage</B>
   * Get the File entity ID for file or image items:
   * @code
   *   $fileId = FALSE;
   *   if ($item->isFile() === TRUE) {
   *     $fileId = $item->getFileId();
   *   }
   *   elseif ($item->isImage() === TRUE) {
   *     $fileId = $item->getImageId();
   *   }
   * @endcode
   *
   * @return bool|int
   *   Returns the entity ID of the underlying File entity for image items,
   *   or FALSE if this item is not for an image file.
   *
   * @see ::getImage()
   * @see ::getKind()
   * @see ::isImage()
   */
  public function getImageId();
 
  /**
   * Returns the item's image File entity, if any.
   *
   * For image items, this method returns the File entity for the
   * underlying stored file. For all other item kinds, a NULL is returned.
   *
   * While file items also have a File entity, file and image items
   * store their File entities separately. Use getFile() to get a
   * file item's File entity.
   *
   * <B>Example usage</B>
   * Get the File entity for file or image items:
   * @code
   *   $file = NULL;
   *   if ($item->isFile() === TRUE) {
   *     $file = $item->getFile();
   *   }
   *   elseif ($item->isImage() === TRUE) {
   *     $file = $item->getImage();
   *   }
   * @endcode
   *
   * @return \Drupal\file\FileInterface
   *   Returns the File entity for the underlying image file for image items,
   *   or a NULL if this item is not for an image.
   *
   * @see ::getImageId()
   * @see ::getKind()
   * @see ::isImage()
   */
  public function getImage();
 
  /**
   * Returns the item's media ID, if any.
   *
   * For media items, this method returns the Media entity ID for the
   * underlying media object. For all other item kinds, a FALSE is returned.
   *
   * @return int
   *   Returns the entity ID of the underlying Media entity for media items,
   *   or FALSE if this item is not for media.
   *
   * @see ::getMedia()
   * @see ::getKind()
   * @see ::isMedia()
   */
  public function getMediaId();
 
  /**
   * Returns the item's Media entity, if any.
   *
   * For media items, this method returns the Media entity for the
   * media object. For all other item kinds, a NULL is returned.
   *
   * @return \Drupal\media\MediaInterface
   *   Returns the Media entity for the underlying media object for media
   *   items, or a NULL if this item is not for media.
   *
   * @see ::getMediaId()
   * @see ::getKind()
   * @see ::isMedia()
   */
  public function getMedia();
 
  /*---------------------------------------------------------------------
   *
   * Name field.
   *
   *---------------------------------------------------------------------*/
 
  /**
   * Returns the item's name.
   *
   * This function is equivalent to Entity::label(), but faster since it
   * does not require entity type introspection to find the field containing
   * the name.
   *
   * @return string
   *   Returns the name of the item.
   *
   * @see \Drupal\Core\Entity\label()
   * @see ::rename()
   */
  public function getName();
 
  /**
   * Returns TRUE if a proposed name is unique among this item's children.
   *
   * The $name argument specifies a proposed name for an existing or new
   * child of this item. The name is not validated and is presumed to be
   * of legal length and structure.
   *
   * The optional $inUseId indicates the ID of an existing child of this
   * item that is already using the name. If the value is not given, negative,
   * or FolderShareInterface::ANY_ITEM_ID, then it is presumed that no
   * current child has the proposed name.
   *
   * This function looks through the names of its children and returns TRUE
   * if the proposed name is not in use by any child, except the indicated
   * child, if any. If the name is in use by a child that is not $inUseId,
   * then FALSE is returned.
   *
   * @param string $name
   *   A proposed name.
   * @param int $inUseId
   *   (optional, default = FolderShareInterface::ANY_ITEM_ID) The ID of an
   *   existing FolderShare item child that is already using the proposed name.
   *
   * @return bool
   *   Returns TRUE if the name is unique among the item's children, and
   *   FALSE otherwise.
   *
   * @see ::findChildrenNames()
   * @see ::getName()
   * @see ::isNameLegal()
   * @see ::isRootNameUnique()
   * @see ::createUniqueName()
   */
  public function isNameUnique(string $name, int $inUseId = self::ANY_ITEM_ID);
 
  /*---------------------------------------------------------------------
   *
   * File name extensions.
   *
   *---------------------------------------------------------------------*/
 
  /**
   * Returns the item's filename extension.
   *
   * If the item is a folder, an empty string is returned.
   *
   * The extension is always converted to lower case.
   *
   * @return string
   *   The file name extension (the portion of the name after the last ".").
   */
  public function getExtension();
 
  /*---------------------------------------------------------------------
   *
   * Size field.
   *
   *---------------------------------------------------------------------*/
 
  /**
   * Returns the item's storage size, in bytes.
   *
   * For file, image, and media items, this function returns the size of
   * the underlying entity. For File and Image items, this is the size of
   * the locally stored file.
   *
   * For folders, this returns the sum of the sizes for all descendants.
   * The field is initialized to zero when a folder is created, and updated
   * each time a descendant is added, deleted, or moved. For some operations,
   * the size is temporarily cleared while the sum of descendant sizes is
   * recalculated. During this time, this function will return FALSE.
   *
   * @return bool|int
   *   Returns the size in bytes, or FALSE if the size is currently unknown.
   *
   * @see ::getKind()
   * @see \Drupal\file\FileInterface::getSize()
   */
  public function getSize();
 
  /*---------------------------------------------------------------------
   *
   * Created date/time field.
   *
   *---------------------------------------------------------------------*/
 
  /**
   * Returns the creation timestamp.
   *
   * @return int
   *   Returns the creation time stamp for this item.
   *
   * @see ::setCreatedTime()
   */
  public function getCreatedTime();
 
  /**
   * Sets the creation timestamp.
   *
   * The timestamp is not validated and is presumed to be valid.
   *
   * The caller must call save() for the change to take effect.
   *
   * <B>Process locks</B>
   * This method does not lock access. The caller should lock around changes
   * to the entity.
   *
   * @param int $timestamp
   *   The creation time stamp for this item. The value is not validated
   *   and is assumed to be a valid timestamp.
   *
   * @see ::getCreatedTime()
   */
  public function setCreatedTime($timestamp);
 
  /*---------------------------------------------------------------------
   *
   * Owner field.
   *
   *---------------------------------------------------------------------*/
 
  /**
   * Returns TRUE if the item is owned by the indicated user.
   *
   * @param int $uid
   *   The user ID to check.
   *
   * @return bool
   *   Returns TRUE if the item is owned by the indicated user, and FALSE
   *   otherwise.
   *
   * @see ::getOwnerId()
   */
  public function isOwnedBy(int $uid);
 
  /**
   * Sets the owner of this item.
   *
   * If this item is a file, the underlying file's ownership is also changed.
   *
   * If this item is a folder, the ownership of the folder's children
   * is not affected.
   *
   * This item is automatically saved after changes are made.
   *
   * System hidden and disabled items are also affected.
   *
   * <B>Process locks</B>
   * This method does not lock access. The caller should lock around changes
   * to the entity.
   *
   * @param \Drupal\user\UserInterface $account
   *   The user account of the new owner of the folder. If the value is NULL,
   *   the current user's account is used.
   *
   * @return \Drupal\foldershare\FolderShareInterface
   *   Returns this item.
   *
   * @see \Drupal\user\EntityOwnerInterface::getOwner()
   * @see \Drupal\user\EntityOwnerInterface::getOwnerId()
   */
  public function setOwner(UserInterface $account = NULL);
 
  /**
   * Sets the owner ID of this item.
   *
   * If this item is a file, the underlying file's ownership is also changed.
   *
   * If this item is a folder, the ownership of the folder's children
   * is not affected.
   *
   * The user ID is not validated and is presumed to be a valid ID for a
   * User entity.
   *
   * This item is automatically saved after changes are made.
   *
   * System hidden and disabled items are also affected.
   *
   * <B>Process locks</B>
   * This method does not lock access. The caller should lock around changes
   * to the entity. See changeOwnerId().
   *
   * @param int $ownerUid
   *   The user ID of the new owner of the folder. The ID is not validated
   *   and is presumed to be for a valid User entity.
   *
   * @return \Drupal\foldershare\FolderShareInterface
   *   Returns this item.
   *
   * @see ::changeOwnerId()
   * @see \Drupal\user\EntityOwnerInterface::getOwner()
   * @see \Drupal\user\EntityOwnerInterface::getOwnerId()
   */
  public function setOwnerId($ownerUid);
 
  /*---------------------------------------------------------------------
   *
   * Grant fields.
   *
   *---------------------------------------------------------------------*/
 
  /**
   * Returns user IDs for users granted author access to this root item.
   *
   * The returned unordered array has one entry for each user ID currently
   * granted author (create, update, delete) access to this root item.
   * The owner of the root item is always included in this list.
   *
   * If this is not a root item, an empty array is returned.
   *
   * @return int[]
   *   Returns an unordered array of user IDs for users with author access to
   *   this root item. If this is not a root item, an empty array is returned.
   *
   * @see ::getAccessGrantViewUserIds()
   * @see ::getAccessGrants()
   * @see ::isAccessGranted()
   */
  public function getAccessGrantAuthorUserIds();
 
  /**
   * Returns user IDs for users granted view access to this root item.
   *
   * The returned unordered array has one entry for each user ID currently
   * granted view access to this root item. The owner of the root item is
   * always included in this list.
   *
   * If this is not a root item, an empty array is returned.
   *
   * @return int[]
   *   Returns an unordered array of user IDs for users with view access to
   *   this root item. If this is not a root item, an empty array is returned.
   *
   * @see ::getAccessGrantAuthorUserIds()
   * @see ::getAccessGrants()
   * @see ::isAccessGranted()
   */
  public function getAccessGrantViewUserIds();
 
  /**
   * Returns all user IDs and access to this root item.
   *
   * The returned unordered associative array has user IDs as keys. For each
   * user, the array value is an array that contains either one or two string
   * values:
   * - ['view'] = user only has view access.
   * - ['author'] = user only has author access (which is odd).
   * - ['author', 'view'] = user has view and author access.
   *
   * The owner of the root folder is always included with both view and
   * author access.
   *
   * If this is not a root item, an empty array is returned.
   *
   * The returned array is in the same format as that used by
   * share().
   *
   * @return array
   *   Returns an unordered associative array with user IDs as keys and
   *   arrays as values. Array values contain strings indicating 'view' or
   *   'author' access. If this is not a root item, an empty array is
   *   returned.
   *
   * @see ::getAccessGrantAuthorUserIds()
   * @see ::getAccessGrantViewUserIds()
   * @see ::isAccessGranted()
   * @see ::share()
   */
  public function getAccessGrants();
 
  /**
   * Returns TRUE if access is explicitly granted to a user on this root item.
   *
   * The $uid argument indicates the user to look up to check if they have been
   * explicitly granted access to the root item and its descendants.
   *
   * The $access argument selects whether 'view' or 'author' access is
   * checked. For any other value, FALSE is returned.
   *
   * If this is not a root item, FALSE is returned. Use getRootItem() to
   * get the root item ancestor of this item, and then query it for access.
   *
   * If a root item grants access to the anonymous user (uid = 0), then
   * this method returns TRUE for all user IDs for 'author' and 'view'.
   *
   * A system hidden or disabled item may be queried for its access grants.
   * However the module's access control will deny access anyway if the user
   * is not an administrator.
   *
   * @param int $uid
   *   The user ID of a user granted access.
   * @param string $access
   *   The access to test. One of 'author' or 'view'.
   *
   * @return bool
   *   Returns TRUE if the access is granted, and FALSE otherwise. If this
   *   is not a root item, FALSE is returned.
   *
   * @see ::getAccessGrantAuthorUserIds()
   * @see ::getAccessGrantViewUserIds()
   * @see ::getAccessGrants()
   * @see ::share()
   */
  public function isAccessGranted(int $uid, string $access);
 
  /**
   * Returns TRUE if no-one but the owner has access to this root item.
   *
   * If the root item's owner is the only user ID listed in the item's
   * access grants, then the root item and its descendants are private
   * and this method returns TRUE. Otherwise it returns FALSE.
   *
   * If this is not a root item, FALSE is returned.
   *
   * A system hidden or disabled item may be queried for its access grants.
   * However the module's access control will deny access anyway if the user
   * is not an administrator.
   *
   * @return bool
   *   Returns TRUE if the owner is the only user granted access, and
   *   FALSE otherwise.
   *
   * @see ::isAccessGranted()
   * @see ::isAccessPublic()
   * @see ::isAccessShared()
   */
  public function isAccessPrivate();
 
  /**
   * Returns TRUE if access is granted to anonymous on this root item.
   *
   * If the root item's 'view' or 'author' grants include the anonymous
   * user (UID = 0), then the root item and its descendants are public and
   * this method returns TRUE. Otherwise it returns FALSE.
   *
   * If this is not a root item, FALSE is returned.
   *
   * A system hidden or disabled item may be queried for its access grants.
   * However the module's access control will deny access anyway if the user
   * is not an administrator.
   *
   * @return bool
   *   Returns TRUE if access is granted to the anonymous user, and
   *   FALSE otherwise.
   *
   * @see ::isAccessGranted()
   * @see ::isAccessPrivate()
   * @see ::isAccessShared()
   */
  public function isAccessPublic();
 
  /**
   * Returns TRUE if access is granted to a non-owner of this root item.
   *
   * If the root item grants 'view' or 'author' access to anyone other
   * than the item's owner, the item is being shared and this method returns
   * TRUE. Otherwise it returns FALSE.
   *
   * If this is not a root item, FALSE is returned.
   *
   * A system hidden or disabled item may be queried for its access grants.
   * However the module's access control will deny access anyway if the user
   * is not an administrator.
   *
   * @return bool
   *   Returns TRUE if access is granted to anyone beyond the owner, and
   *   FALSE otherwise.
   *
   * @see ::isAccessGranted()
   * @see ::isAccessPrivate()
   * @see ::isAccessPublic()
   */
  public function isAccessShared();
 
  /**
   * Returns TRUE if the item is shared by the indicated user.
   *
   * An item is shared by a user if:
   * - It is owned by that user.
   * - It has view or author access grants for anybody else.
   *
   * @param int $uid
   *   The user ID of the user to check.
   *
   * @return bool
   *   Returns TRUE if the item is shared by the indicated user, and
   *   FALSE otherwise.
   *
   * @see ::isAccessGranted()
   * @see ::isOwnedBy()
   * @see ::isSharedWith()
   * @see ::getAccessGrantAuthorUserIds()
   * @see ::getAccessGrantViewUserIds()
   */
  public function isSharedBy(int $uid);
 
  /**
   * Returns TRUE if the item is shared with the indicated user.
   *
   * An item is shared with a user if:
   * - It is NOT owned by that user.
   * - It has the indicated access grants for that user.
   *
   * @param int $uid
   *   The user ID of the user to check.
   * @param string $access
   *   The access to test. One of 'author' or 'view'.
   *
   * @return bool
   *   Returns TRUE if the item is shared by the indicated user, and
   *   FALSE otherwise.
   *
   * @see ::isAccessGranted()
   * @see ::isOwnedBy()
   * @see ::isSharedBy()
   * @see ::getAccessGrantAuthorUserIds()
   * @see ::getAccessGrantViewUserIds()
   */
  public function isSharedWith(int $uid, string $access);
 
  /*---------------------------------------------------------------------
   *
   * Sharing status.
   *
   *---------------------------------------------------------------------*/
 
  /**
   * Returns a simplified statement about the entity's sharing status.
   *
   * Returned values include:
   * - "personal" = the item is not shared and it is owned by the
   *   current user.
   *
   * - "private" = the item is not shared and it is not owned by the
   *   current user.
   *
   * - "shared by you" = the item is shared and it is owned by the
   *   current user.
   *
   * - "shared with you" = the item is shared with the current user and it
   *   is not owned by the current user.
   *
   * - "public" = the item is owned by Anonymous or is shared with Anonymous.
   *
   * System hidden and disabled items are always "private".
   *
   * @return string
   *   Returns one of the above sharing status values.
   */
  public function getSharingStatus();
 
  /*---------------------------------------------------------------------
   *
   * SystemDisabled field.
   *
   *---------------------------------------------------------------------*/
 
  /**
   * Returns TRUE if the item is disabled by the system.
   *
   * Items are temporarily disabled during long-running operations, such as
   * copies and moves. Disabled items are normally visible, but non-functional
   * for users.
   *
   * @return bool
   *   Returns TRUE if the item is disabled, and FALSE otherwise.
   */
  public function isSystemDisabled();
 
  /*---------------------------------------------------------------------
   *
   * SystemHidden field.
   *
   *---------------------------------------------------------------------*/
 
  /**
   * Returns TRUE if the item is hidden by the system.
   *
   * Items are hidden during long-running destructive operations, such as
   * deletion. Hidden items are normally not visible to users.
   *
   * @return bool
   *   Returns TRUE if the item is hidden, and FALSE otherwise.
   */
  public function isSystemHidden();
 
  /*---------------------------------------------------------------------
   *
   * Description field.
   *
   *---------------------------------------------------------------------*/
 
  /**
   * Returns the item description.
   *
   * @return string
   *   Returns the description string for the item, or an empty string if
   *   there is no description.
   *
   * @see ::setDescription()
   */
  public function getDescription();
 
  /**
   * Sets the item description.
   *
   * The caller must call save() for the change to take effect.
   *
   * <B>Process locks</B>
   * This method does not lock access. The caller should lock around changes
   * to the entity. See changeOwnerId().
   *
   * @param string $text
   *   The description string for the item, or an empty string if there is no
   *   description. The description is not validated or filtered.
   *
   * @see ::getDescription()
   */
  public function setDescription(string $text);
 
  /*---------------------------------------------------------------------
   *
   * Child items.
   *
   *---------------------------------------------------------------------*/
 
  /**
   * Returns a list of children IDs of this item.
   *
   * System hidden or disabled items may or may not be returned, depending
   * upon the parameters.
   *
   * Items marked disabled are in use. They remain visible and are enabled
   * again when they are no longer in use. Typically, disabled items should
   * be included in the returned results, so $includeDisabled defaults to
   * TRUE.
   *
   * Items marked hidden are being deleted. They are not visible and will
   * never be enabled again. Typically, hidden items should not be included
   * in the returned results, so $includeHidden defaults to FALSE.
   *
   * <B>Example usage</B>
   * Loop through all children of this item:
   * @code
   *   foreach ($item->findChildrenIds() as $id) { ... }
   * @endcode
   *
   * @param bool $includeDisabled
   *   (optional, default = TRUE) When TRUE, disabled children are included.
   *   When FALSE, they are not.
   * @param bool $includeHidden
   *   (optional, default = FALSE) When TRUE, hidden children are included.
   *   When FALSE, they are not.
   *
   * @return int[]
   *   Returns an unordered array of integer entity IDs for children
   *   of this item, or an empty array if there are no children.
   *
   * @see ::findFileChildrenIds()
   * @see ::findFolderChildrenIds()
   * @see ::findChildrenNames()
   */
  public function findChildrenIds(
    bool $includeDisabled = TRUE,
    bool $includeHidden = FALSE);
 
  /**
   * Returns a list of children of this item.
   *
   * System hidden or disabled items may or may not be returned, depending
   * upon the parameters.
   *
   * Items marked disabled are in use. They remain visible and are enabled
   * again when they are no longer in use. Typically, disabled items should
   * be included in the returned results, so $includeDisabled defaults to
   * TRUE.
   *
   * Items marked hidden are being deleted. They are not visible and will
   * never be enabled again. Typically, hidden items should not be included
   * in the returned results, so $includeHidden defaults to FALSE.
   *
   * <B>Memory use</B>
   * Warning: There can be a large number of children. Loading them all
   * into memory at the same time could exceed PHP's memory limit.
   *
   * <B>Run time</B>
   * Warning: There can be a large number of children. Loading them all
   * at the same time could exceed PHP's execution time limit.
   *
   * @param bool $includeDisabled
   *   (optional, default = TRUE) When TRUE, disabled children are included.
   *   When FALSE, they are not.
   * @param bool $includeHidden
   *   (optional, default = FALSE) When TRUE, hidden children are included.
   *   When FALSE, they are not.
   *
   * @return array
   *   Returns a list of entities for children of this item, or an empty
   *   array if there are no children.
   *
   * @see ::findFileChildren()
   * @see ::findFolderChildren()
   */
  public function findChildren(
    bool $includeDisabled = TRUE,
    bool $includeHidden = FALSE);
 
  /**
   * Returns a list of names for children of this item.
   *
   * System hidden or disabled items may or may not be returned, depending
   * upon the parameters.
   *
   * Items marked disabled are in use. They remain visible and are enabled
   * again when they are no longer in use. Typically, disabled items should
   * be included in the returned results, so $includeDisabled defaults to
   * TRUE.
   *
   * Items marked hidden are being deleted. They are not visible and will
   * never be enabled again. Typically, hidden items should not be included
   * in the returned results, so $includeHidden defaults to FALSE.
   *
   * <B>Example usage</B>
   * Loop through all children names of this item:
   * @code
   *   foreach ($item->findChildrenNames() as $name) { ... }
   * @endcode
   *
   * @param bool $includeDisabled
   *   (optional, default = TRUE) When TRUE, disabled children are included.
   *   When FALSE, they are not.
   * @param bool $includeHidden
   *   (optional, default = FALSE) When TRUE, hidden children are included.
   *   When FALSE, they are not.
   *
   * @return array
   *   Returns an unordered associative array where keys are item names and
   *   values are entity IDs.
   *
   * @see ::findChildren()
   * @see ::findChildrenIds()
   * @see ::findFileChildren()
   * @see ::findFileChildrenIds()
   * @see ::findFolderChildren()
   * @see ::findFolderChildrenIds()
   */
  public function findChildrenNames(
    bool $includeDisabled = TRUE,
    bool $includeHidden = FALSE);
 
  /**
   * Returns the total size, in bytes, of all children.
   *
   * System hidden children are ignored. System disabled items are included.
   *
   * @return int
   *   Returns the size, in bytes, of the sum of the sizes of all children.
   *
   * @see ::findChildrenIds()
   * @see ::findFileChildren()
   * @see ::findChildrenNames()
   * @see ::getFileId()
   */
  public function findChildrenNumberOfBytes();
 
  /**
   * Returns a list of file, image, and media IDs for children of this item.
   *
   * System hidden or disabled items may or may not be returned, depending
   * upon the parameters.
   *
   * Items marked disabled are in use. They remain visible and are enabled
   * again when they are no longer in use. Typically, disabled items should
   * be included in the returned results, so $includeDisabled defaults to
   * TRUE.
   *
   * Items marked hidden are being deleted. They are not visible and will
   * never be enabled again. Typically, hidden items should not be included
   * in the returned results, so $includeHidden defaults to FALSE.
   *
   * <B>Memory use</B>
   * Warning: There can be a large number of file children. Loading them all
   * into memory at the same time could exceed PHP's memory limit.
   *
   * <B>Run time</B>
   * Warning: There can be a large number of file children. Loading them all
   * at the same time could exceed PHP's execution time limit.
   *
   * @param bool $includeDisabled
   *   (optional, default = TRUE) When TRUE, disabled children are included.
   *   When FALSE, they are not.
   * @param bool $includeHidden
   *   (optional, default = FALSE) When TRUE, hidden children are included.
   *   When FALSE, they are not.
   *
   * @return int[]
   *   Returns an unordered array of integer entity IDs for file, image,
   *   or media children of this item, or an empty array if there are no
   *   matching children.
   *
   * @see ::findChildrenIds()
   * @see ::findFileChildren()
   * @see ::findChildrenNames()
   * @see ::getFileId()
   */
  public function findFileChildrenIds(
    bool $includeDisabled = TRUE,
    bool $includeHidden = FALSE);
 
  /**
   * Returns a list of entities for files, images, or media in this item.
   *
   * System hidden or disabled items may or may not be returned, depending
   * upon the parameters.
   *
   * Items marked disabled are in use. They remain visible and are enabled
   * again when they are no longer in use. Typically, disabled items should
   * be included in the returned results, so $includeDisabled defaults to
   * TRUE.
   *
   * Items marked hidden are being deleted. They are not visible and will
   * never be enabled again. Typically, hidden items should not be included
   * in the returned results, so $includeHidden defaults to FALSE.
   *
   * <B>Example usage</B>
   * Loop through all file, image, or media children of this item:
   * @code
   *   foreach ($item->findFileChildren() as $child) { ... }
   * @endcode
   *
   * @param bool $includeDisabled
   *   (optional, default = TRUE) When TRUE, disabled children are included.
   *   When FALSE, they are not.
   * @param bool $includeHidden
   *   (optional, default = FALSE) When TRUE, hidden children are included.
   *   When FALSE, they are not.
   *
   * @return array
   *   Returns an unordered array of entities for file, image,
   *   or media children of this item, or an empty array if there are no
   *   matching children.
   *
   * @see ::findChildren()
   * @see ::findFileChildrenIds()
   * @see ::findChildrenNames()
   * @see ::getFile()
   * @see ::getImage()
   * @see ::getMedia()
   */
  public function findFileChildren(
    bool $includeDisabled = TRUE,
    bool $includeHidden = FALSE);
 
  /**
   * Returns a list of folder IDs for children of this item.
   *
   * System hidden or disabled items may or may not be returned, depending
   * upon the parameters.
   *
   * Items marked disabled are in use. They remain visible and are enabled
   * again when they are no longer in use. Typically, disabled items should
   * be included in the returned results, so $includeDisabled defaults to
   * TRUE.
   *
   * Items marked hidden are being deleted. They are not visible and will
   * never be enabled again. Typically, hidden items should not be included
   * in the returned results, so $includeHidden defaults to FALSE.
   *
   * <B>Example usage</B>
   * Loop through all folder children of this item:
   * @code
   *   foreach ($item->findFolderChildrenIds() as $id) { ... }
   * @endcode
   *
   * @param bool $includeDisabled
   *   (optional, default = TRUE) When TRUE, disabled children are included.
   *   When FALSE, they are not.
   * @param bool $includeHidden
   *   (optional, default = FALSE) When TRUE, hidden children are included.
   *   When FALSE, they are not.
   *
   * @return array
   *   Returns an unordered array of integer entity IDs for folder
   *   children of this item, or an empty array if there are no folder
   *   children.
   *
   * @see ::findChildrenIds()
   * @see ::findFolderChildren()
   * @see ::findChildrenNames()
   */
  public function findFolderChildrenIds(
    bool $includeDisabled = TRUE,
    bool $includeHidden = FALSE);
 
  /**
   * Returns a list of entities for folder children of this item.
   *
   * System hidden or disabled items may or may not be returned, depending
   * upon the parameters.
   *
   * Items marked disabled are in use. They remain visible and are enabled
   * again when they are no longer in use. Typically, disabled items should
   * be included in the returned results, so $includeDisabled defaults to
   * TRUE.
   *
   * Items marked hidden are being deleted. They are not visible and will
   * never be enabled again. Typically, hidden items should not be included
   * in the returned results, so $includeHidden defaults to FALSE.
   *
   * <B>Memory use</B>
   * Warning: There can be a large number of folder children. Loading them all
   * into memory at the same time could exceed PHP's memory limit.
   *
   * <B>Run time</B>
   * Warning: There can be a large number of folder children. Loading them all
   * at the same time could exceed PHP's execution time limit.
   *
   * @param bool $includeDisabled
   *   (optional, default = TRUE) When TRUE, disabled children are included.
   *   When FALSE, they are not.
   * @param bool $includeHidden
   *   (optional, default = FALSE) When TRUE, hidden children are included.
   *   When FALSE, they are not.
   *
   * @return array
   *   Returns an unordered array of entities for folder children of
   *   this item, or an empty array if there are no folder children.
   *
   * @see ::findFolderChildrenIds()
   * @see ::findChildrenNames()
   * @see ::findChildren()
   */
  public function findFolderChildren(
    bool $includeDisabled = TRUE,
    bool $includeHidden = FALSE);
 
  /**
   * Returns the number of children.
   *
   * System hidden or disabled items may or may not be returned, depending
   * upon the parameters.
   *
   * Items marked disabled are in use. They remain visible and are enabled
   * again when they are no longer in use. Typically, disabled items should
   * be included in the returned results, so $includeDisabled defaults to
   * TRUE.
   *
   * Items marked hidden are being deleted. They are not visible and will
   * never be enabled again. Typically, hidden items should not be included
   * in the returned results, so $includeHidden defaults to FALSE.
   *
   * @param bool $includeDisabled
   *   (optional, default = TRUE) When TRUE, disabled children are included.
   *   When FALSE, they are not.
   * @param bool $includeHidden
   *   (optional, default = FALSE) When TRUE, hidden children are included.
   *   When FALSE, they are not.
   *
   * @return int
   *   Returns the number of children. If the item is not a folder, a zero
   *   is returned.
   *
   * @see ::findFileChildrenIds()
   */
  public function findNumberOfChildren(
    bool $includeDisabled = TRUE,
    bool $includeHidden = FALSE);
 
  /*---------------------------------------------------------------------
   *
   * Parent field.
   *
   *---------------------------------------------------------------------*/
 
  /**
   * Returns the parent folder, or NULL if there is no parent.
   *
   * Since only folders can have children, only folders can be parents,
   * and the returned entity is always a folder.
   *
   * A system hidden or disabled item are returned.
   *
   * <B>Example usage</B>
   * Build a list of ancestors by successively getting the parent, then
   * the parent's parent, and so forth:
   * @code
   *   $ancestors = [];
   *   $parent = $item->getParentFolder();
   *   while ($parent !== NULL) {
   *     $ancestors[] = $parent;
   *     $parent = $parent->getParentFolder();
   *   }
   * @endcode
   *
   * @return \Drupal\foldershare\FolderShareInterface
   *   Returns the parent entity, or NULL if this item is a root item and
   *   therefore has no parent.
   *
   * @see ::getParentFolderId()
   * @see ::getRootItem()
   * @see ::getRootItemId()
   * @see ::isFolder()
   * @see ::isRootItem()
   */
  public function getParentFolder();
 
  /**
   * Returns the parent folder ID, or a flag if there is no parent.
   *
   * If the item has no parent, it is a root list item and
   * FolderShareInterface::USER_ROOT_LIST is returned.
   *
   * Since only folders can have children, only folders can be parents,
   * and the returned entity ID is always for a folder.
   *
   * A system hidden or disabled item are returned.
   *
   * @return int
   *   Returns the parent ID, or FolderShareInterface::USER_ROOT_LIST if this
   *   item is a root item and therefore has no parent.
   *
   * @see ::getParentFolder()
   * @see ::getRootItem()
   * @see ::getRootItemId()
   * @see ::isFolder()
   * @see ::isRootItem()
   */
  public function getParentFolderId();
 
  /*---------------------------------------------------------------------
   *
   * Ancestors.
   *
   *---------------------------------------------------------------------*/
 
  /**
   * Returns a list of ancestor folder IDs.
   *
   * The returned list is ordered with this item's root first, then each
   * ancestor leading down to this item. This item's ID is not included.
   * If this item is a root, then the returned array is empty.
   *
   * System hidden and disabled items are included in the list.
   *
   * @return int[]
   *   Returns an ordered list of entity IDs as array values, starting
   *   with this item's root.
   *
   * @see ::findAncestorFolders()
   * @see ::findAncestorFolderNames()
   * @see ::findDescendantIds()
   * @see ::findDescendantIdsByOwner()
   * @see ::isAncestorOfFolderId()
   * @see ::isDescendantOfFolderId()
   */
  public function findAncestorFolderIds();
 
  /**
   * Returns a list of ancestor folder names.
   *
   * The returned list is ordered with this item's root first, then each
   * ancestor leading down to this item. This item's name is not included.
   * If this item is a root, then the returned array is empty.
   *
   * System hidden and disabled items are included in the list.
   *
   * <B>Example usage</B>
   * Build a path of ancestor names for this item:
   * @code
   *   $path = '/' . implode('/', $item->findAncestorFolderNames());
   * @endcode
   *
   * @return string[]
   *   Returns an ordered list of entity IDs as array values, starting
   *   with this item's root.
   *
   * @see ::findAncestorFolders()
   * @see ::findAncestorFolderIds()
   */
  public function findAncestorFolderNames();
 
  /**
   * Returns a list of ancestor folders.
   *
   * The returned list is ordered with this item's root first, then each
   * ancestor leading down to this item. This item is not included.
   * If this item is a root, then the returned array is empty.
   *
   * System hidden and disabled items are included in the list.
   *
   * <B>Memory use</B>
   * Warning: There can be a large number of ancestors. Loading them all
   * into memory at the same time could exceed PHP's memory limit.
   *
   * <B>Run time</B>
   * Warning: There can be a large number of ancestors. Loading them all
   * at the same time could exceed PHP's execution time limit.
   *
   * @return \Drupal\foldershare\FolderShareInterface
   *   Returns an ordered list of entities as array values, starting
   *   with this item's root.
   *
   * @see ::findAncestorFolderIds()
   * @see ::findAncestorFolderNames()
   * @see ::findDescendantIds()
   * @see ::findDescendantIdsByOwner()
   * @see ::isAncestorOfFolderId()
   * @see ::isDescendantOfFolderId()
   */
  public function findAncestorFolders();
 
  /**
   * Returns TRUE if this item is an ancestor of the given item.
   *
   * System hidden and disabled items are considered in this test.
   *
   * @param int $folderId
   *   The ID of the item to check to see if this item is one of its ancestors.
   *
   * @return bool
   *   Returns TRUE if this item is an ancestor of the given item,
   *   and FALSE otherwise. If the given entity ID is invalid, FALSE
   *   is returned.
   *
   * @see ::findAncestorFolderIds()
   * @see ::findDescendantIds()
   * @see ::findDescendantIdsByOwner()
   * @see ::isDescendantOfFolderId()
   */
  public function isAncestorOfFolderId(int $folderId);
 
  /*---------------------------------------------------------------------
   *
   * Descendants.
   *
   *---------------------------------------------------------------------*/
 
  /**
   * Returns a list of descendant item IDs.
   *
   * The returned list includes the entity IDs of children, their children,
   * and so on for all descendants of this item.
   *
   * System hidden or disabled items may or may not be returned, depending
   * upon the parameters.
   *
   * Items marked disabled are in use. They remain visible and are enabled
   * again when they are no longer in use. Typically, disabled items should
   * be included in the returned results, so $includeDisabled defaults to
   * TRUE.
   *
   * Items marked hidden are being deleted. They are not visible and will
   * never be enabled again. Typically, hidden items should not be included
   * in the returned results, so $includeHidden defaults to FALSE.
   *
   * <B>Example usage</B>
   * Find all descendants of this item:
   * @code
   *   $allIds = $this->findDescendantIds();
   * @endcode
   *
   * @param bool $includeDisabled
   *   (optional, default = TRUE) When TRUE, disabled children are included.
   *   When FALSE, they are not.
   * @param bool $includeHidden
   *   (optional, default = FALSE) When TRUE, hidden children are included.
   *   When FALSE, they are not.
   *
   * @return int[]
   *   Returns an unordered list of descendant entity IDs.
   *
   * @see ::findAncestorFolderIds()
   * @see ::findDescendantIdsByOwner()
   * @see ::isAncestorOfFolderId()
   * @see ::isDescendantOfFolderId()
   */
  public function findDescendantIds(
    bool $includeDisabled = TRUE,
    bool $includeHidden = FALSE);
 
  /**
   * Returns a list of descendant item IDs based upon their owner ID.
   *
   * The returned list includes the entity IDs of children, their children,
   * and so on for all descendants of this item.
   *
   * The $ownerUid and $match arguments work together to constrain this list.
   * By default, all descendants for any owner are returned. If $ownerUid is
   * set and $match is TRUE, only those descendants with $ownerUid as the
   * owner are returned. If $ownerUid is set and $match is FALSE, only those
   * descendants that are NOT owned by $ownerUid are returned.
   *
   * System hidden and disabled items are included in the list.
   *
   * <B>Example usage</B>
   * Find all descendants owned by the current user, and all descendants
   * not owned by the current user:
   * @code
   *   $allIdsOwnedBy = $this->FindDescendantIdsByOwner(\Drupal::currentUser()->id());
   *   $allIdsNotOwnedBy = $this->FindDescendantIdsByOwner(\Drupal::currentUser()->id(), FALSE);
   * @endcode
   *
   * @param int $ownerUid
   *   (optional, default = FolderShareInterface::ANY_USER_ID) The user ID
   *   to use when looking up descendants. If the ID is not given or
   *   FolderShareInterface::ANY_USER_ID, then all descendants are returned,
   *   regardless of their owner.
   * @param bool $match
   *   (optional, default = TRUE = include matching owner IDs) When TRUE,
   *   all entities with an owner ID that matches the given $ownerUid are
   *   returned. When FALSE all entities that DO NOT match the given
   *   $ownerUid are returned.
   *
   * @return int[]
   *   Returns an unordered list of descendant entity IDs.
   *
   * @see ::findAncestorFolderIds()
   * @see ::findDescendantIdsByOwner()
   * @see ::isAncestorOfFolderId()
   * @see ::isDescendantOfFolderId()
   */
  public function findDescendantIdsByOwnerId(
    int $ownerUid,
    bool $match = TRUE);
 
  /**
   * Returns a list of descendant item IDs based upon their root ID.
   *
   * The returned list includes the entity IDs of children, their children,
   * and so on for all descendants of this item.
   *
   * The $rootId and $match arguments work together to constrain this list.
   * By default, all descendants with any root ID are returned. If $rootId is
   * set and $match is TRUE, only those descendants with $rootId as the
   * root are returned. If $rootId is set and $match is FALSE, only those
   * descendants that do NOT have $rootId as their root are returned.
   *
   * System hidden and disabled items are included in the list.
   *
   * @param int $rootId
   *   (optional, default = FolderShareInterface::ANY_ITEM_ID) The entity ID
   *   to use when looking up descendants. If the ID is not given or
   *   FolderShareInterface::ANY_ITEM_ID, then all descendants are returned,
   *   regardless of their root ID.
   * @param bool $match
   *   (optional, default = TRUE = include matching root IDs) When TRUE,
   *   all entities with a root ID that matches the given $rootId are
   *   returned. When FALSE all entities that DO NOT match the given
   *   $rootId are returned.
   *
   * @return int[]
   *   Returns an unordered list of descendant entity IDs.
   *
   * @see ::findAncestorFolderIds()
   * @see ::findDescendantIds()
   * @see ::findDescendantIdsByOwner()
   * @see ::isAncestorOfFolderId()
   * @see ::isDescendantOfFolderId()
   */
  public function findDescendantIdsByRootId(
    int $rootId,
    bool $match = TRUE);
 
  /**
   * Returns TRUE if this item is a descendant of the indicated entity.
   *
   * System hidden and disabled items are considered in this test.
   *
   * @param int $proposedAncestorId
   *   The entity ID of a proposed ancestor of this item.
   *
   * @return bool
   *   TRUE if this item is a descendant of the proposed ancestor, and
   *   FALSE otherwise. If the proposed ancestor's ID is invalid,
   *   FALSE is returned.
   *
   * @see ::findAncestorFolderIds()
   * @see ::findDescendantIds()
   * @see ::findDescendantIdsByOwner()
   * @see ::isAncestorOfFolderId()
   */
  public function isDescendantOfFolderId(int $proposedAncestorId);
 
  /*---------------------------------------------------------------------
   *
   * Root folder field.
   *
   *---------------------------------------------------------------------*/
 
  /**
   * Returns this item's root item.
   *
   * If this item is a root item, it returns itself.
   *
   * Applications may check if this item is a root item by any of the
   * following, in fastest to slowest order:
   *
   * @code
   *   $isRoot = ($this->getParentFolderId() == FALSE);
   *   $isRoot = $this->isRootItem();
   *   $isRoot = ($this->id() == $this->getRootItemId());
   *   $isRoot = ($this == $this->getRootItem());
   * @endcode
   *
   * @return \Drupal\foldershare\FolderShareInterface
   *   Returns the root item, or this item if the item is a root item.
   *
   * @see ::getParentFolder()
   * @see ::getParentFolderId()
   * @see ::getRootItemId()
   * @see ::isRootItem()
   */
  public function getRootItem();
 
  /**
   * Returns this item's root ID.
   *
   * If this item is a root item, it returns its own ID.
   *
   * Applications may check if this item is a root item by any
   * of the following, in fastest to slowest order:
   *
   * @code
   *   $isRoot = ($this->getParentFolderId() == FolderShareInterface::USER_ROOT_LIST);
   *   $isRoot = $this->isRootItem();
   *   $isRoot = ($this->id() == $this->getRootItemId());
   *   $isRoot = ($this == $this->getRootItem());
   * @endcode
   *
   * @return int
   *   Returns the root ID, or this item's ID if this item is a root item.
   *
   * @see ::getParentFolder()
   * @see ::getParentFolderId()
   * @see ::getRootItem()
   * @see ::isRootItem()
   */
  public function getRootItemId();
 
  /**
   * Returns TRUE if this item is a root item, and FALSE otherwise.
   *
   * Applications may check if this item is a root item by any
   * of the following, in fastest to slowest order:
   *
   * @code
   *   $isRoot = ($this->getParentFolderId() == FolderShareInterface::USER_ROOT_LIST);
   *   $isRoot = $this->isRootItem();
   *   $isRoot = ($this->id() == $this->getRootItemId());
   *   $isRoot = ($this == $this->getRootItem());
   * @endcode
   *
   * @return bool
   *   Returns TRUE if this item is a root item.
   *
   * @see ::getParentFolder()
   * @see ::getParentFolderId()
   * @see ::getRootItem()
   * @see ::getRootItemId()
   * @see ::isParentFolder()
   */
  public function isRootItem();
 
  /*---------------------------------------------------------------------
   *
   * Paths.
   *
   *---------------------------------------------------------------------*/
 
  /**
   * Builds a string path to the item.
   *
   * The returned path is a slash (/) followed by a series of slash-separated
   * ancestor names, ending with the item's own name.
   *
   * @return string
   *   Returns a string path to the item.
   */
  public function getPath();
 
  /*---------------------------------------------------------------------
   *
   * Folder operations.
   *
   *---------------------------------------------------------------------*/
 
  /**
   * Changes the owner of this item, and optionally all descendants.
   *
   * The owner user ID of this item is changed to the indicated user.
   * If $changeDescendants is TRUE, the owner user ID of all of this item's
   * descendants is changed as well.
   *
   * The user ID is not validated. It is presumed to be a valid entity ID
   * for a User entity. It should not be negative.
   *
   * If this is a root item, then the item's name is checked for a collision
   * with another root item with the same name in the new owner's root list.
   * If there is a collision, an exception is thrown and no change is made.
   *
   * System hidden and disabled items are also affected.
   *
   * <B>Background change ownership</B>
   * When $changeDescendants is TRUE, this method schedules background tasks
   * to traverse the folder tree and update descendants. This will delay
   * completion of the change to a time in the future that depends upon
   * the size of the folder tree being changed and server load.
   *
   * <B>Process locks</B>
   * This method locks the item's root folder tree for exclusive use during
   * the change. This will prevent any other edit operation from being
   * performed on the same folder tree until the change completes. When
   * background tasks are used, unlocking the root folder tree does not
   * occur until the last descendant is changed.
   *
   * <B>Post-operation hooks</B>
   * This method calls the "hook_foldershare_post_operation_change_owner" hook.
   *
   * <B>Activity log</B>
   * This method posts a log message after the item is changed.
   *
   * @param int $uid
   *   The owner user ID for the new owner of the folder tree. The ID
   *   is not validated and is presumed to be that of a User entity.
   * @param bool $changeDescendants
   *   (optional, default = FALSE) When FALSE, only this item's ownership
   *   is changed. When TRUE, the ownership of all of this item's descendants
   *   is updated as well.
   *
   * @throws \Drupal\foldershare\Entity\Exception\LockException
   *   Throws an exception if an access lock could not be acquired.
   * @throws \Drupal\foldershare\Entity\Exception\ValidationException
   *   Throws an exception if this is a root item and it's name is
   *   already in use in the root list of the new user.
   *
   * @see ::setOwnerId()
   * @see \Drupal\user\EntityOwnerInterface::getOwner()
   * @see \Drupal\user\EntityOwnerInterface::getOwnerId()
   */
  public function changeOwnerId(int $uid, bool $changeDescendants = FALSE);
 
  /**
   * Creates a new folder with the given name as a child of this folder.
   *
   * If the name is empty, it is set to a default.
   *
   * The name is checked for uniqueness within the parent folder.
   * If needed, a sequence number is appended before the extension(s) to
   * make it unique (e.g. 'My folder 12').
   *
   * <B>Process locks</B>
   * This method locks the root folder tree for exclusive use during
   * creation of the folder. This will prevent any other edit operation from
   * being performed on the same folder tree until the creation completes.
   *
   * <B>Post-operation hooks</B>
   * This method calls the "hook_foldershare_post_operation_new_folder" hook.
   *
   * <B>Activity log</B>
   * This method posts a log message after the folder is created.
   *
   * @param string $name
   *   (optional, default = '') The name for the new folder. If the name is
   *   empty, it is set to a default name.
   * @param bool $allowRename
   *   (optional, default = TRUE) When TRUE, the entity will be automatically
   *   renamed, if needed, to insure that it is unique within the folder.
   *   When FALSE, non-unique names cause an exception to be thrown.
   *
   * @return \Drupal\foldershare\Entity\FolderShareInterface
   *   Returns the new folder. The folder has been saved.
   *
   * @throws \Drupal\foldershare\Entity\Exception\LockException
   *   Throws an exception if an access lock could not be acquired.
   * @throws \Drupal\foldershare\Entity\Exception\ValidationException
   *   Throws an exception if the name is already in use.
   */
  public function createFolder(string $name = '', bool $allowRename = TRUE);
 
  /**
   * Copies this item into the user's root list.
   *
   * A copy of this item is created and added to the current user's root list.
   * The copy is owned by the current user and given default access grants
   * that give the user, and only the user, access.
   *
   * If this item is a folder, copying recurses through all descendants to
   * replicate the folder tree. Copied descendants retain the same names
   * and field values as the originals, and organized in the same tree
   * structure.
   *
   * File, image, and media items are copied along with copies of their
   * underlying File and Media entities.
   *
   * Copying marks each new folder as disabled until all children have been
   * copied into the folder. UIs may show disabled items specially and prevent
   * operations until the item is enabled.
   *
   * The copy will fail if a lock cannot be obtained on the original and
   * the root list. The copy will fail and be incomplete if any of the
   * children cannot be locked as they are copied. Everything that can be
   * copied will be.
   *
   * System hidden and disabled items are also affected.
   *
   * <B>Background copy</B>
   * File copies occur immediately, but folder copies schedule background
   * tasks to traverse the folder tree and update descendants. This will
   * delay completion of the copy to a time in the future that depends upon
   * the size of the folder tree being copied and server load.
   *
   * <B>Post-operation hooks</B>
   * This method calls the "hook_foldershare_post_operation_copy" hook for
   * each item copied.
   *
   * <B>Process locks</B>
   * This method locks the root folder tree of the item being copied, and
   * the user's root list, while copying items.
   *
   * <B>Activity log</B>
   * This method posts a log message each time an item is copied.
   *
   * @param string $newName
   *   (optional, default = '' = no name change) When empty, the copy will
   *   have the same name as the original. When a new name is not empty,
   *   the given name will be used as the name for the copy.
   * @param bool $allowRename
   *   (optional, default = FALSE) When FALSE, the copy uses the same name
   *   as the original, or the given new name. If there is already an item
   *   with the same name in the user's root list, an exception is thrown.
   *   When TRUE, the copy starts with the same name as the original, or the
   *   given new name, and then the name is modified to create a unique name
   *   in the user's root list.
   *
   * @return \Drupal\foldershare\Entity\FolderShareInterface
   *   Returns the new root item.
   *
   * @throws \Drupal\foldershare\Entity\Exception\LockException
   *   Throws an exception if an access lock could not be acquired.
   * @throws \Drupal\foldershare\Entity\Exception\ValidationException
   *   If $newName is not empty, an exception is thrown if the name is not
   *   legal or if this is a file or image and the name's filename extension
   *   is not allowed for the site. If $allowRename is FALSE, an exception
   *   is thrown if the name is already in use in the user's root list.
   * @throws \Drupal\foldershare\Entity\Exception\SystemException
   *   For files, throws an exception if a serious system error occurs while
   *   duplicating the underlying local file. System errors may indicate a
   *   file system has become unreadable/unwritable, is full, or is offline.
   *
   * @see ::addFile()
   * @see ::copyToFolder()
   * @see ::createFolder()
   */
  public function copyToRoot(string $newName = '', bool $allowRename = FALSE);
 
  /**
   * Copies this item into a selected folder.
   *
   * A copy of this item is created and added to the given folder.
   * The copy is owned by the current user.
   *
   * If this item is a folder, copying recurses through all descendants to
   * replicate the folder tree. Copied descendants retain the same names
   * and field values as the originals, and organized in the same tree
   * structure.
   *
   * File, image, and media items are copied along with copies of their
   * underlying File and Media entities.
   *
   * Copying marks each new folder as disabled until all children have been
   * copied into the folder. UIs may show disabled items specially and prevent
   * operations until the item is enabled.
   *
   * The copy will fail if a lock cannot be obtained on the original and
   * the new parent. The copy will fail and be incomplete if any of the
   * children cannot be locked as they are copied. Everything that can be
   * copied will be.
   *
   * System hidden and disabled items are also affected.
   *
   * <B>Background copy</B>
   * File copies occur immediately, but folder copies schedule background
   * tasks to traverse the folder tree and update descendants. This will
   * delay completion of the copy to a time in the future that depends upon
   * the size of the folder tree being copied and server load.
   *
   * <B>Post-operation hooks</B>
   * This method calls the "hook_foldershare_post_operation_copy" hook for
   * each item copied.
   *
   * <B>Process locks</B>
   * This method locks the root folder tree of the item being copied, and
   * the root folder tree of the destination, while copying items.
   *
   * <B>Activity log</B>
   * This method posts a log message each time an item is copied.
   *
   * @param \Drupal\foldershare\FolderShareInterface $destination
   *   (optional, default = NULL = copy to the root list) The folder
   *   into which to place the copy. When NULL, the copy is added to the
   *   user's root list (see copyToRoot()).
   * @param string $newName
   *   (optional, default = '' = no name change) When empty, the copy will
   *   have the same name as the original. When a new name is not empty,
   *   the given name will be used as the name for the copy.
   * @param bool $allowRename
   *   (optional, default = FALSE) When FALSE, the copy uses the same name
   *   as the original, or the given new name. If there is already an item
   *   with the same name in the destination, an exception is thrown.
   *   When TRUE, the copy starts with the same name as the original, or the
   *   given new name, and then the name is modified to create a unique name
   *   within the destination.
   *
   * @return \Drupal\foldershare\Entity\FolderShareInterface
   *   Returns the new item.
   *
   * @throws \Drupal\foldershare\Entity\Exception\LockException
   *   Throws an exception if an access lock could not be acquired.
   * @throws \Drupal\foldershare\Entity\Exception\ValidationException
   *   If $newName is not empty, an exception is thrown if the name is not
   *   legal or if this is a file or image and the name's filename extension
   *   is not allowed for the site. If $allowRename is FALSE, an exception
   *   is thrown if the name is in use already in the destination.
   * @throws \Drupal\foldershare\Entity\Exception\SystemException
   *   For files, throws an exception if a serious system error occurs while
   *   duplicating the underlying local file. System errors may indicate a
   *   file system has become unreadable/unwritable, is full, or is offline.
   *
   * @see ::addFile()
   * @see ::copyToRoot()
   * @see ::createFolder()
   */
  public function copyToFolder(
    FolderShareInterface $destination = NULL,
    string $newName = '',
    bool $allowRename = FALSE);
 
  /**
   * Deletes this item and all of its descendants.
   *
   * Implements \Drupal\Core\Entity\EntityInterface::delete.
   * Overrides \Drupal\Core\Entity\Entity::delete.
   *
   * The item root's folder tree is locked for the duration of the operation.
   * This will prevent any other edit operation from being performed on the
   * same root folder tree until the deletion completes.
   *
   * If this item is a file, image, or media item, the underlying File or
   * Media entity is deleted along with the item. After deletion, the root
   * folder tree is unlocked.
   *
   * If this item is a folder, the folder is marked as hidden so that it is
   * no longer listed in file/folder listings. A background task is then
   * scheduled to continue deletion by recursively traversing through the
   * folder's descendants. After the folder and descendants have been
   * deleted, the root folder tree is unlocked. Because deletion executes as
   * a background task, completion of the delete will occur after this
   * method returns and at a time in the future that depends upon the size
   * of the folder tree being deleted and server load.
   *
   * System hidden and disabled items can be deleted.
   *
   * <B>Background delete</B>
   * File deletion occurs immediately, but folder deletion schedules background
   * tasks to traverse the folder tree and delete descendants. This will
   * delay completion of the delete to a time in the future that depends upon
   * the size of the folder tree being deleted and server load.
   *
   * <B>Process locks</B>
   * This method locks the item root's folder tree for exclusive use during
   * the delete. This will prevent any other edit operation from being
   * performed on the same root folder tree until the deletion completes.
   * When deletion requires scheduled background tasks, unlocking the root
   * folder tree does not occur until the last descendant is deleted.
   *
   * <B>Post-operation hooks</B>
   * This method calls the "hook_foldershare_post_operation_delete" hook as
   * items are deleted. When deletion requires scheduled background tasks,
   * deletion hooks are called as those tasks are serviced.
   *
   * <B>Activity log</B>
   * This method posts a log message each time an item is deleted. When
   * deletion requires scheduled background tasks, log messages are posted
   * as those tasks are serviced.
   *
   * @throws \Drupal\foldershare\Entity\Exception\LockException
   *   Throws an exception if an access lock could not be acquired.
   *
   * @see ::isSystemHidden()
   */
  public function delete();
 
  /**
   * Duplicates this item into the same parent folder or the user's root list.
   *
   * If this item is in a folder, the item is duplicated into the same folder
   * and given a unique name (e.g. "myitem" becomes "mytime 1").
   *
   * If this item is in a root list (whether the user's or another root list),
   * it is duplicated into the user's root list and given a unique name.
   *
   * The copied files and folders are owned by the current user.
   *
   * System hidden and disabled items are also affected.
   *
   * <B>Background duplicate</B>
   * File copies occur immediately, but folder copies schedule background
   * tasks to traverse the folder tree and update descendants. This will
   * delay completion of the copy to a time in the future that depends upon
   * the size of the folder tree being copied and server load.
   *
   * <B>Process locks</B>
   * This method locks the item's root folder tree for exclusive use during
   * the duplication. This will prevent any other edit operation from
   * being performed on the same folder tree until the move completes.
   *
   * <B>Post-operation hooks</B>
   * This method calls the "hook_foldershare_post_operation_copy" hook for
   * each item copied.
   *
   * <B>Activity log</B>
   * This method posts a log message after the item is copied.
   *
   * @throws \Drupal\foldershare\Entity\Exception\LockException
   *   Throws an exception if an access lock could not be acquired.
   * @throws \Drupal\foldershare\Entity\Exception\ValidationException
   *   Throws an exception if a unique name for the duplicate could not be
   *   created.
   * @throws \Drupal\foldershare\Entity\Exception\SystemException
   *   For files, throws an exception if a serious system error occurs while
   *   duplicating the underlying local file. System errors may indicate a
   *   file system has become unreadable/unwritable, is full, or is offline.
   *
   * @see ::copyToFolder()
   * @see ::copyToRoot()
   */
  public function duplicate();
 
  /**
   * Moves this item into the user's root list.
   *
   * The item's current root folder tree, and the item's own folder tree,
   * are both locked at the start of the operation. This will prevent any
   * other edit operation from being performed on either folder tree. After
   * the item is moved to become a root item, the original root folder tree
   * is unlocked. The lock on the item's own folder tree remains until all
   * descendants have been updated and the move completes.
   *
   * This item's parent and root IDs are updated to move it into the root list.
   * The item is then given default access grants that give the user, and
   * only the user, access.
   *
   * If this item is a folder, a background task is scheduled to complete the
   * move by recursively traversing through the folder's descendants to set
   * each one's root ID. After all descendants have been updated, the root
   * folder tree is unlocked. Because the move executes as a background task,
   * completion of the move will occur after this method returns and at a
   * time in the future that depends upon the size of the folder tree being
   * moved and server load.
   *
   * System hidden and disabled items are also affected.
   *
   * <B>Background move</B>
   * File moves occur immediately, but folder moves schedule background
   * tasks to traverse the folder tree and update descendants. This will
   * delay completion of the move to a time in the future that depends upon
   * the size of the folder tree being moved and server load.
   *
   * <B>Process locks</B>
   * This method locks the item's original root folder tree, and the item's
   * own folder tree for exclusive use during the move. This will prevent
   * any other edit operation from being performed on the same folder trees
   * until the move completes. The original root folder tree lock is released
   * as soon as the item has moved to the root list. When moves require
   * scheduled background tasks, unlocking the item's own root folder tree
   * does not occur until the last descendant is updated.
   *
   * <B>Post-operation hooks</B>
   * This method calls the "hook_foldershare_post_operation_move" hook after
   * the item is moved. The hook is not called for the item's descendants
   * since they have not moved and remain descendants of the original item.
   *
   * <B>Activity log</B>
   * This method posts a log message after the item is moved. Log messages
   * are not posted as the item's descendants are updated since they have
   * not moved and remain descendants of the original item.
   *
   * @param string $newName
   *   (optional, default = '' = don't rename) The proposed new name for
   *   entity once it is moved into the root folder list. If the name is
   *   empty, the folder is not renamed.
   * @param bool $allowRename
   *   (optional, default = FALSE) When FALSE, the moved item keeps its
   *   original name, or is renamed to the given new name. If there is
   *   already an item with the same name in the user's root list, an
   *   exception is thrown. When TRUE, the move starts with the original
   *   name, or the given new name, and then the name is modified to create
   *   a unique name within the user's root list.
   *
   * @throws \Drupal\foldershare\Entity\Exception\LockException
   *   Throws an exception if an access lock could not be acquired.
   * @throws \Drupal\foldershare\Entity\Exception\ValidationException
   *   If $newName is not empty, an exception is thrown if the name is not
   *   legal or if this is a file or image and the name's filename extension
   *   is not allowed for the site. If $allowRename is FALSE, an exception
   *   is thrown if the name is in use already in the user's root list.
   *
   * @see ::moveToFolder()
   */
  public function moveToRoot(
    string $newName = '',
    bool $allowRename = FALSE);
 
  /**
   * Moves this item to a new destination folder.
   *
   * The item's current root folder tree and the destination's root folder
   * tree are both locked at the start of the operation. This will prevent any
   * other edit operation from being performed on either folder tree. After
   * the item is moved, the original root folder tree is unlocked. The lock
   * on the destination's root folder tree remains until all descendants have
   * been updated and the move completes.
   *
   * This item's parent and root IDs are updated to move it into the
   * destination. The item's access grants are cleared.
   *
   * If this item is a folder, a background task is scheduled to complete the
   * move by recursively traversing through the folder's descendants to set
   * each one's root ID. After all descendants have been updated, the
   * destination root folder tree is unlocked. Because the move executes as
   * a background task, completion of the move will occur after this method
   * returns and at a time in the future that depends upon the size of the
   * folder tree being moved and server load.
   *
   * System hidden and disabled items are also affected.
   *
   * <B>Background move</B>
   * File moves occur immediately, but folder moves schedule background
   * tasks to traverse the folder tree and update descendants. This will
   * delay completion of the move to a time in the future that depends upon
   * the size of the folder tree being moved and server load.
   *
   * <B>Process locks</B>
   * This method locks the item's original root folder tree and the
   * destination's root folder tree for exclusive use during the move. This
   * will prevent any other edit operation from being performed on the same
   * folder trees until the move completes. The original root folder tree
   * lock is released as soon as the item has moved to the destination.
   * When moves require scheduled background tasks, unlocking the destination
   * root folder tree does not occur until the last descendant is updated.
   *
   * <B>Post-operation hooks</B>
   * This method calls the "hook_foldershare_post_operation_move" hook after
   * the item is moved. The hook is not called for the item's descendants
   * since they have not moved and remain descendants of the original item.
   *
   * <B>Activity log</B>
   * This method posts a log message after the item is moved. Log messages
   * are not posted as the item's descendants are updated since they have
   * not moved and remain descendants of the original item.
   *
   * @param \Drupal\foldershare\FolderShareInterface $destination
   *   (optional, default = NULL = move to root) The destination folder
   *   into which to move the item.
   * @param string $newName
   *   (optional, default = '' = don't rename) The proposed new name for
   *   entity once it is moved into the destination folder. If the name is
   *   empty, the item is not renamed.
   * @param bool $allowRename
   *   (optional, default = FALSE) When FALSE, the copy uses the same name
   *   as the original, or the given new name. If there is already an item
   *   with the same name in the destination, an exception is thrown.
   *   When TRUE, the copy starts with the same name as the original, or the
   *   given new name, and then the name is modified to create a unique name
   *   within the destination.
   *
   * @throws \Drupal\foldershare\Entity\Exception\LockException
   *   Throws an exception if an access lock could not be acquired.
   * @throws \Drupal\foldershare\Entity\Exception\ValidationException
   *   If $newName is not empty, an exception is thrown if the name is not
   *   legal or if this is a file or image and the name's filename extension
   *   is not allowed for the site. If $allowRename is FALSE, an exception
   *   is thrown if the name is in use already in the destination.
   *
   * @see ::moveToRoot()
   */
  public function moveToFolder(
    FolderShareInterface $destination = NULL,
    string $newName = '',
    bool $allowRename = FALSE);
 
  /**
   * Renames this item to use the given name.
   *
   * The item's name is changed. If the item is a file, the underling File or
   * Media entity name is also changed. File names are subject to file name
   * extension restrictions, if the site has any.
   *
   * System hidden and disabled items are also affected.
   *
   * <B>Process locks</B>
   * This method locks the item's root folder tree for the duration of the
   * rename. This will prevent any other edit operation from being performed
   * on the same folder tree until the rename is done.
   *
   * <B>Post-operation hooks</B>
   * This method calls the "hook_foldershare_post_operation_rename" hook.
   *
   * <B>Activity log</B>
   * This method posts a log message after the item is renamed.
   *
   * @param string $newName
   *   The new name for this item.
   *
   * @throws \Drupal\foldershare\Entity\Exception\LockException
   *   Throws an exception if an access lock could not be acquired.
   * @throws \Drupal\foldershare\Entity\Exception\ValidationException
   *   If the item could not be renamed because the name is invalid or
   *   already in use.
   *
   * @see ::setName()
   */
  public function rename(string $newName);
 
  /**
   * Shares this root item by setting user IDs and access grants.
   *
   * If this is not a root item, this call has no effect.
   *
   * The given associative array is in the same format as that returned by
   * getAccessGrants(), and is used to completely reset all access grants
   * for this root item. Any prior grants are removed.
   *
   * The array must have user IDs as keys. For each user,
   * the array value must be an array of strings with one or two values:
   * - ['view'] = user only has view access.
   * - ['author'] = user only has author access (which is odd).
   * - ['author', 'view'] = user has view and author access.
   *
   * The owner of the root item is automaticaly included with both view and
   * author access, whether or not they are included in the given array.
   *
   * System hidden and disabled entities may be changed, however the module's
   * access control will deny access for any user that is not an administrator.
   *
   * <B>Process locks</B>
   * This method locks the item's root folder tree for the duration of the
   * update. This will prevent any other edit operation from being performed
   * on the same folder tree until the update is done.
   *
   * <B>Post-operation hooks</B>
   * This method calls the "hook_foldershare_post_operation_share" hook.
   *
   * <B>Activity log</B>
   * This method posts a log message after the item is updated.
   *
   * @param array $grants
   *   An unordered associative array with user IDs as keys and
   *   arrays as values. Array values contain strings indicating 'view' or
   *   'author' access.
   *
   * @throws \Drupal\foldershare\Entity\Exception\LockException
   *   Throws an exception if an access lock could not be acquired.
   *
   * @see ::getAccessGrants()
   * @see ::getAccessGrantAuthorUserIds()
   * @see ::getAccessGrantViewUserIds()
   * @see ::isAccessGranted()
   * @see ::unshare()
   */
  public function share(array $grants);
 
  /**
   * Unshares this root item for the indicated user and access.
   *
   * If this is not a root item, this call has no effect.
   *
   * Access grants are adjusted to remove the indicated user for shared access.
   * The $access argument may be 'view' or 'author', or left empty to unshare
   * for both.
   *
   * <B>Process locks</B>
   * This method locks the item's root folder tree for the duration of the
   * update. This will prevent any other edit operation from being performed
   * on the same folder tree until the update is done.
   *
   * <B>Post-operation hooks</B>
   * This method calls the "hook_foldershare_post_operation_share" hook.
   *
   * <B>Activity log</B>
   * This method posts a log message after the item is updated.
   *
   * @param int $uid
   *   The user ID for the user to remove from the item's access grants.
   * @param string $access
   *   (optional, default = '' = view and author) The access grant to remove.
   *   This is either 'view' or 'author', or an empty string to remove both.
   *
   * @throws \Drupal\foldershare\Entity\Exception\LockException
   *   Throws an exception if an access lock could not be acquired.
   *
   * @see ::getAccessGrants()
   * @see ::getAccessGrantAuthorUserIds()
   * @see ::getAccessGrantViewUserIds()
   * @see ::isAccessGranted()
   * @see ::share()
   */
  public function unshare(int $uid, string $access);
 
  /*---------------------------------------------------------------------
   *
   * File operations.
   *
   *---------------------------------------------------------------------*/
 
  /**
   * Adds a file to this folder.
   *
   * If $allowRename is FALSE, an exception is thrown if the file's
   * name is not unique within the folder. But if $allowRename is
   * TRUE and the name is not unique, the file's name is adjusted
   * to include a sequence number immediately before the first "."
   * in the name, or at the end of the name if there is no "."
   * (e.g. "myfile.png" becomes "myfile 1.png").
   *
   * An exception is thrown if the file is already in a folder.
   *
   * System hidden and disabled items are also affected.
   *
   * <B>Post-operation hooks</B>
   * This method calls the "hook_foldershare_post_operation_add_files" hook.
   *
   * <B>Process locks</B>
   * This method locks this item's root folder tree for exclusive use for
   * the duration of the addition. This will prevent any other edit operation
   * from being performed on the same folder tree until the addition
   * completes.
   *
   * <B>Activity log</B>
   * This method posts a log message after the files have been added.
   *
   * @param \Drupal\file\FileInterface $file
   *   The file to be added to this folder.
   * @param bool $allowRename
   *   (optional) When TRUE, the file's name should be automatically renamed to
   *   insure it is unique within the folder. When FALSE, non-unique
   *   file names cause an exception to be thrown.  Defaults to FALSE.
   *
   * @return \Drupal\foldershare\FolderShareInterface
   *   Returns the new FolderShare entity that wraps the given File entity.
   *
   * @throws \Drupal\foldershare\Entity\Exception\LockException
   *   Throws an exception if an access lock could not be acquired.
   * @throws \Drupal\foldershare\Entity\Exception\ValidationException
   *   If the file could not be added because the file is already
   *   in a folder, or if the file doesn't pass validation because
   *   the name is invalid or already in use (if $allowRename FALSE).
   *
   * @see ::addFiles()
   */
  public function addFile(FileInterface $file, bool $allowRename = FALSE);
 
  /**
   * Adds files to this folder.
   *
   * If $allowRename is FALSE, an exception is thrown if the file's
   * name is not unique within the folder. But if $allowRename is
   * TRUE and the name is not unique, the file's name is adjusted
   * to include a sequence number immediately before the first "."
   * in the name, or at the end of the name if there is no "."
   * (e.g. "myfile.png" becomes "myfile 1.png").
   *
   * All files are checked and renamed before any files are added
   * to the folder. If any file is invalid, an exception is thrown
   * and no files are added.
   *
   * An exception is thrown if any file is already in a folder.
   *
   * System hidden and disabled items are also affected.
   *
   * <B>Post-operation hooks</B>
   * This method calls the "hook_foldershare_post_operation_add_files" hook.
   *
   * <B>Process locks</B>
   * This method locks this item's root folder tree for exclusive use for
   * the duration of the addition. This will prevent any other edit operation
   * from being performed on the same folder tree until the addition
   * completes.
   *
   * <B>Activity log</B>
   * This method posts a log message after the files have been added.
   *
   * @param \Drupal\file\FileInterface[] $files
   *   An array of files to be added to this folder.  NULL files
   *   are silently skipped.
   * @param bool $allowRename
   *   (optional) When TRUE, each file's name should be automatically renamed
   *   to insure it is unique within the folder. When FALSE, non-unique
   *   file names cause an exception to be thrown.  Defaults to FALSE.
   *
   * @return \Drupal\foldershare\FolderShareInterface[]
   *   Returns an array of new FolderShare entities that wrap the given
   *   File entities.
   *
   * @throws \Drupal\foldershare\Entity\Exception\LockException
   *   Throws an exception if an access lock could not be acquired.
   * @throws \Drupal\foldershare\Entity\Exception\ValidationException
   *   If the file could not be added because the file is already
   *   in a folder, or if the file doesn't pass validation because
   *   the name is invalid or already in use (if $allowRename FALSE).
   *
   * @see ::addFile()
   */
  public function addFiles(array $files, bool $allowRename = FALSE);
 
  /**
   * Adds uploaded files for the named form field into this folder.
   *
   * When a file is uploaded via an HTTP form post from a browser, PHP
   * automatically saves the data into "upload" files saved in a
   * PHP-managed temporary directory. This method sweeps those uploaded
   * files, pulls out the ones associated with the named form field,
   * and adds them to this folder with their original names.
   *
   * If there are no uploaded files, this method returns immediately.
   *
   * Files may be automatically renamed, if needed, to insure they have
   * unique names within the folder.
   *
   * System hidden and disabled items are also affected.
   *
   * <B>Process locks</B>
   * This method locks this item's root folder tree for the duration of
   * the addition.
   *
   * <B>Post-operation hooks</B>
   * This method calls the "hook_foldershare_post_operation_add_files" hook.
   *
   * <B>Activity log</B>
   * This method posts a log message after the files have been added.
   *
   * @param string $formFieldName
   *   The name of the form field with associated uploaded files pending.
   * @param bool $allowRename
   *   (optional, default = TRUE) When TRUE, if a file's name collides with the
   *   name of an existing entity, the name is modified by adding a number on
   *   the end so that it doesn't collide. When FALSE, a file name collision
   *   throws an exception.
   *
   * @return array
   *   The returned array contains one entry per uploaded file.
   *   An entry may be a File object uploaded into the current folder,
   *   or a string containing an error message about that file and
   *   indicating that it could not be uploaded and added to the folder.
   *   An empty array is returned if there were no files to upload
   *   and add to the folder.
   *
   * @throws \Drupal\foldershare\Entity\Exception\LockException
   *   Throws an exception if an access lock could not be acquired.
   *
   * @see ::addFile()
   * @see ::addFiles()
   *
   * @todo The error messages returned here should be removed in favor of
   * error codes and arguments so that the caller can know which file
   * had which error and do something about it or report their own
   * error message. Returning text messages here is not flexible.
   */
  public function addUploadFiles(
    string $formFieldName,
    bool $allowRename = TRUE);
 
  /**
   * Adds a PHP input stream file into this folder.
   *
   * When a file is uploaded via an HTTP post handled by a web services
   * "REST" resource, the file's data is available via the PHP input
   * stream. This method reads that stream, creates a file, and adds
   * that file to this folder with the given name.
   *
   * System hidden and disabled items are also affected.
   *
   * <B>Post-operation hooks</B>
   * This method calls the "hook_foldershare_post_operation_add_files" hook.
   *
   * <B>Process locks</B>
   * This item's root folder tree is locked for exclusive editing access
   * for the duration of the addition.
   *
   * <B>Activity log</B>
   * This method posts a log message after the files have been added.
   *
   * @param string $filename
   *   The name for the new file.
   * @param bool $allowRename
   *   (optional, default = TRUE) When TRUE, if $filename collides with the
   *   name of an existing entity, the name is modified by adding a number on
   *   the end so that it doesn't collide. When FALSE, a file name collision
   *   throws an exception.
   *
   * @return \Drupal\foldershare\FolderShareInterface
   *   Returns the newly added FolderShare entity wrapping the file.
   *
   * @throws \Drupal\foldershare\Entity\Exception\LockException
   *   Throws an exception if an access lock could not be acquired.
   *
   * @see ::addFile()
   * @see ::addFiles()
   * @see ::addUploadedFiles()
   */
  public function addInputFile(string $filename, bool $allowRename = TRUE);
 
  /*---------------------------------------------------------------------
   *
   * Archive operations.
   *
   *---------------------------------------------------------------------*/
 
  /**
   * Archives the given items to a new archive added to this folder.
   *
   * A new ZIP archive is created in this folder and all of the given,
   * items, and their children, recursively, are added to the archive.
   *
   * All items must be children of this item.
   *
   * <B>Process locks</B>
   * The root folder trees above the items added to the archive are locked
   * for exclusive use during the operation.
   *
   * <B>Post-operation hooks</B>
   * This method calls the "hook_foldershare_post_operation_add_files" hook.
   *
   * <B>Activity log</B>
   * This method posts a log message after the archive is created.
   *
   * @param \Drupal\foldershare\FoldershareInterface[] $items
   *   An array of children of this folder that are to be included in a
   *   new archive added as a new child of this folder.
   *
   * @return \Drupal\foldershare\FolderShareInterface
   *   Returns the FolderShare entity for the new archive.
   *
   * @throws \Drupal\foldershare\Entity\Exception\LockException
   *   Thrown if an access lock on this folder could not be acquired.
   * @throws \Drupal\foldershare\Entity\Exception\ValidationException
   *   Thrown if this item is not a folder or root folder, or if any of
   *   the children in the array are not children of this folder.
   * @throws \Drupal\foldershare\Entity\Exception\SystemException
   *   Thrown if the archive file could not be created, such as if the
   *   temporary directory does not exist or is not writable, if a temporary
   *   file for the archive could not be created, or if any of the file
   *   children of this item could not be read and saved into the archive.
   */
  public function archiveToFolder(array $items);
 
  /**
   * Extracts all contents of this archive and adds them to the parent folder.
   *
   * This item must be a ZIP file. All of the contents of the ZIP file are
   * extracted and added as new files and folders into this file's parent
   * folder.
   *
   * <B>Process locks</B>
   * The root folder tree above the ZIP file is locked for exclusive use.
   *
   * <B>Post-operation hooks</B>
   * This method calls the "hook_foldershare_post_operation_add_files" hook
   * for each added file from the archive.
   *
   * <B>Activity log</B>
   * This method posts a log message after each file is uncompressed.
   *
   * @throws \Drupal\foldershare\Entity\Exception\LockException
   *   Thrown if an access lock on this folder could not be acquired.
   * @throws \Drupal\foldershare\Entity\Exception\ValidationException
   *   Thrown if the archive is not a valid archive or it has become
   *   corrpted.
   * @throws \Drupal\foldershare\Entity\Exception\SystemException
   *   Thrown if the archive file could not be accessed or there was a
   *   problem creating any of the new files and folders from the archive.
   */
  public function unarchiveFromZip();
 
}
Главная | Обратная связь
You are here

foldershare-8.x-1.2/src/FolderShareInterface.php
