[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  /**
   4   * @package     Joomla.Administrator
   5   * @subpackage  com_media
   6   *
   7   * @copyright   (C) 2016 Open Source Matters, Inc. <https://www.joomla.org>
   8   * @license     GNU General Public License version 2 or later; see LICENSE.txt
   9   */
  10  
  11  namespace Joomla\Component\Media\Administrator\Adapter;
  12  
  13  // phpcs:disable PSR1.Files.SideEffects
  14  \defined('_JEXEC') or die;
  15  // phpcs:enable PSR1.Files.SideEffects
  16  
  17  /**
  18   * Media file adapter interface.
  19   *
  20   * @since  4.0.0
  21   */
  22  interface AdapterInterface
  23  {
  24      /**
  25       * Returns the requested file or folder. The returned object
  26       * has the following properties available:
  27       * - type:          The type can be file or dir
  28       * - name:          The name of the file
  29       * - path:          The relative path to the root
  30       * - extension:     The file extension
  31       * - size:          The size of the file
  32       * - create_date:   The date created
  33       * - modified_date: The date modified
  34       * - mime_type:     The mime type
  35       * - width:         The width, when available
  36       * - height:        The height, when available
  37       *
  38       * If the path doesn't exist a FileNotFoundException is thrown.
  39       *
  40       * @param   string  $path  The path to the file or folder
  41       *
  42       * @return  \stdClass
  43       *
  44       * @since   4.0.0
  45       * @throws  \Exception
  46       */
  47      public function getFile(string $path = '/'): \stdClass;
  48  
  49      /**
  50       * Returns the folders and files for the given path. The returned objects
  51       * have the following properties available:
  52       * - type:          The type can be file or dir
  53       * - name:          The name of the file
  54       * - path:          The relative path to the root
  55       * - extension:     The file extension
  56       * - size:          The size of the file
  57       * - create_date:   The date created
  58       * - modified_date: The date modified
  59       * - mime_type:     The mime type
  60       * - width:         The width, when available
  61       * - height:        The height, when available
  62       *
  63       * If the path doesn't exist a FileNotFoundException is thrown.
  64       *
  65       * @param   string  $path  The folder
  66       *
  67       * @return  \stdClass[]
  68       *
  69       * @since   4.0.0
  70       * @throws  \Exception
  71       */
  72      public function getFiles(string $path = '/'): array;
  73  
  74      /**
  75       * Returns a resource for the given path.
  76       *
  77       * @param   string  $path  The path
  78       *
  79       * @return  resource
  80       *
  81       * @since   4.0.0
  82       * @throws  \Exception
  83       */
  84      public function getResource(string $path);
  85  
  86      /**
  87       * Creates a folder with the given name in the given path.
  88       *
  89       * It returns the new folder name. This allows the implementation
  90       * classes to normalise the file name.
  91       *
  92       * @param   string  $name  The name
  93       * @param   string  $path  The folder
  94       *
  95       * @return  string
  96       *
  97       * @since   4.0.0
  98       * @throws  \Exception
  99       */
 100      public function createFolder(string $name, string $path): string;
 101  
 102      /**
 103       * Creates a file with the given name in the given path with the data.
 104       *
 105       * It returns the new file name. This allows the implementation
 106       * classes to normalise the file name.
 107       *
 108       * @param   string  $name  The name
 109       * @param   string  $path  The folder
 110       * @param   string  $data  The data
 111       *
 112       * @return  string
 113       *
 114       * @since   4.0.0
 115       * @throws  \Exception
 116       */
 117      public function createFile(string $name, string $path, $data): string;
 118  
 119      /**
 120       * Updates the file with the given name in the given path with the data.
 121       *
 122       * @param   string  $name  The name
 123       * @param   string  $path  The folder
 124       * @param   string  $data  The data
 125       *
 126       * @return  void
 127       *
 128       * @since   4.0.0
 129       * @throws  \Exception
 130       */
 131      public function updateFile(string $name, string $path, $data);
 132  
 133      /**
 134       * Deletes the folder or file of the given path.
 135       *
 136       * @param   string  $path  The path to the file or folder
 137       *
 138       * @return  void
 139       *
 140       * @since   4.0.0
 141       * @throws  \Exception
 142       */
 143      public function delete(string $path);
 144  
 145      /**
 146       * Moves a file or folder from source to destination.
 147       *
 148       * It returns the new destination path. This allows the implementation
 149       * classes to normalise the file name.
 150       *
 151       * @param   string  $sourcePath       The source path
 152       * @param   string  $destinationPath  The destination path
 153       * @param   bool    $force            Force to overwrite
 154       *
 155       * @return  string
 156       *
 157       * @since   4.0.0
 158       * @throws  \Exception
 159       */
 160      public function move(string $sourcePath, string $destinationPath, bool $force = false): string;
 161  
 162      /**
 163       * Copies a file or folder from source to destination.
 164       *
 165       * It returns the new destination path. This allows the implementation
 166       * classes to normalise the file name.
 167       *
 168       * @param   string  $sourcePath       The source path
 169       * @param   string  $destinationPath  The destination path
 170       * @param   bool    $force            Force to overwrite
 171       *
 172       * @return  string
 173       *
 174       * @since   4.0.0
 175       * @throws  \Exception
 176       */
 177      public function copy(string $sourcePath, string $destinationPath, bool $force = false): string;
 178  
 179      /**
 180       * Returns a public url for the given path. This function can be used by the cloud
 181       * adapter to publish the media file and create a permanent publicly accessible
 182       * url.
 183       *
 184       * @param   string  $path  The path to file
 185       *
 186       * @return  string
 187       *
 188       * @since   4.0.0
 189       * @throws  \Joomla\Component\Media\Administrator\Exception\FileNotFoundException
 190       */
 191      public function getUrl(string $path): string;
 192  
 193      /**
 194       * Returns the name of the adapter.
 195       * It will be shown in the Media Manager
 196       *
 197       * @return  string
 198       *
 199       * @since   4.0.0
 200       */
 201      public function getAdapterName(): string;
 202  
 203      /**
 204       * Search for a pattern in a given path
 205       *
 206       * @param   string  $path       The base path for the search
 207       * @param   string  $needle     The path to file
 208       * @param   bool    $recursive  Do a recursive search
 209       *
 210       * @return  \stdClass[]
 211       *
 212       * @since   4.0.0
 213       */
 214      public function search(string $path, string $needle, bool $recursive = false): array;
 215  }