[4.1] Add some events when fetching media data

administrator/components/com_media/src/Event/AbstractMediaItemValidationEvent.php

@@ -0,0 +1,127 @@
+<?php
+/**
+ * @package     Joomla.Administrator
+ * @subpackage  com_media
+ *
+ * @copyright   (C) 2021 Open Source Matters, Inc. <https://www.joomla.org>
+ * @license     GNU General Public License version 2 or later; see LICENSE.txt
+ */
+
+namespace Joomla\Component\Media\Administrator\Event;
+
+\defined('_JEXEC') or die;
+
+use Joomla\CMS\Event\AbstractImmutableEvent;
+
+/**
+ * Event to validate media items.
+ *
+ * @since  __DEPLOY_VERSION__
+ */
+abstract class AbstractMediaItemValidationEvent extends AbstractImmutableEvent
+{
+	/**
+	 * Validate $item to have all attributes with a valid type.
+	 *
+	 * Properties validated:
+	 * - type:          The type can be file or dir
+	 * - name:          The name of the item
+	 * - path:          The relative path to the root
+	 * - extension:     The file extension
+	 * - size:          The size of the file
+	 * - create_date:   The date created
+	 * - modified_date: The date modified
+	 * - mime_type:     The mime type
+	 * - width:         The width, when available
+	 * - height:        The height, when available
+	 *
+	 * Properties generated:
+	 * - created_date_formatted:  DATE_FORMAT_LC5 formatted string based on create_date
+	 * - modified_date_formatted: DATE_FORMAT_LC5 formatted string based on modified_date
+	 *
+	 * @param   \stdClass  $item  The item to set
+	 *
+	 * @return  void
+	 *
+	 * @since   __DEPLOY_VERSION__
+	 *
+	 * @throws \BadMethodCallException
+	 */
+	protected function validate(\stdClass $item): void
+	{
+		// Only "dir" or "file" is allowed
+		if (!isset($item->type) || ($item->type !== 'dir' && $item->type !== 'file'))
+		{
+			throw new \BadMethodCallException("Property 'type' of argument 'item' of event {$this->name} has a wrong item. Valid: 'dir' or 'file'");
+		}
+
+		// Non empty string
+		if (empty($item->name) || !is_string($item->name))
+		{
+			throw new \BadMethodCallException("Property 'name' of argument 'item' of event {$this->name} has a wrong item. Valid: non empty string");
+		}
+
+		// Non empty string
+		if (empty($item->path) || !is_string($item->path))
+		{
+			throw new \BadMethodCallException("Property 'path' of argument 'item' of event {$this->name} has a wrong item. Valid: non empty string");
+		}
+
+		// A string
+		if ($item->type === 'file' && (!isset($item->extension) || !is_string($item->extension)))
+		{
+			throw new \BadMethodCallException("Property 'extension' of argument 'item' of event {$this->name} has a wrong item. Valid: string");
+		}
+
+		// An empty string or an integer
+		if (!isset($item->size) ||
+			(!is_integer($item->size) && !is_string($item->size)) ||
+			(is_string($item->size) && $item->size !== '')
+		)
+		{
+			throw new \BadMethodCallException("Property 'size' of argument 'item' of event {$this->name} has a wrong item. Valid: empty string or integer");
+		}
+
+		// A string
+		if (!isset($item->mime_type) || !is_string($item->mime_type))
+		{
+			throw new \BadMethodCallException("Property 'mime_type' of argument 'item' of event {$this->name} has a wrong item. Valid: string");
+		}
+
+		// An integer
+		if (!isset($item->width) || !is_integer($item->width))
+		{
+			throw new \BadMethodCallException("Property 'width' of argument 'item' of event {$this->name} has a wrong item. Valid: integer");
+		}
+
+		// An integer
+		if (!isset($item->height) || !is_integer($item->height))
+		{
+			throw new \BadMethodCallException("Property 'height' of argument 'item' of event {$this->name} has a wrong item. Valid: integer");
+		}
+
+		// A string
+		if (!isset($item->create_date) || !is_string($item->create_date))
+		{
+			throw new \BadMethodCallException("Property 'create_date' of argument 'item' of event {$this->name} has a wrong item. Valid: string");
+		}
+
+		// A string
+		if (!isset($item->create_date_formatted) || !is_string($item->create_date_formatted))
+		{
+			throw new \BadMethodCallException("Property 'create_date_formatted' of argument 'item' of event {$this->name} has a wrong item. Valid: string");
+		}
+
+		// A string
+		if (!isset($item->modified_date) || !is_string($item->modified_date))
+		{
+			throw new \BadMethodCallException("Property 'modified_date' of argument 'item' of event {$this->name} has a wrong item. Valid: string");
+		}
+
+		// A string
+		if (!isset($item->modified_date_formatted) || !is_string($item->modified_date_formatted))
+		{
+			throw new \BadMethodCallException("Property 'modified_date_formatted' of argument 'item' of event {$this->name} has a wrong item. Valid: string");
+		}
+	}
+}

administrator/components/com_media/src/Event/FetchMediaItemEvent.php

@@ -0,0 +1,82 @@
+<?php
+/**
+ * @package     Joomla.Administrator
+ * @subpackage  com_media
+ *
+ * @copyright   (C) 2021 Open Source Matters, Inc. <https://www.joomla.org>
+ * @license     GNU General Public License version 2 or later; see LICENSE.txt
+ */
+
+namespace Joomla\Component\Media\Administrator\Event;
+
+\defined('_JEXEC') or die;
+
+/**
+ * Event object for fetch media item.
+ *
+ * @since  __DEPLOY_VERSION__
+ */
+final class FetchMediaItemEvent extends AbstractMediaItemValidationEvent
+{
+	/**
+	 * Constructor.
+	 *
+	 * @param   string  $name       The event name.
+	 * @param   array   $arguments  The event arguments.
+	 *
+	 * @throws  \BadMethodCallException
+	 *
+	 * @since  __DEPLOY_VERSION__
+	 */
+	public function __construct($name, array $arguments = array())
+	{
+		parent::__construct($name, $arguments);
+
+		// Check for required arguments
+		if (!\array_key_exists('item', $arguments) || !is_object($arguments['item']))
+		{
+			throw new \BadMethodCallException("Argument 'item' of event $name is not of the expected type");
+		}
+	}
+
+	/**
+	 * Validate $item to have all attributes with a valid type
+	 *
+	 * Validation based on \Joomla\Component\Media\Administrator\Adapter\AdapterInterface::getFile()
+	 *
+	 * Properties validated:
+	 * - type:          The type can be file or dir
+	 * - name:          The name of the item
+	 * - path:          The relative path to the root
+	 * - extension:     The file extension
+	 * - size:          The size of the file
+	 * - create_date:   The date created
+	 * - modified_date: The date modified
+	 * - mime_type:     The mime type
+	 * - width:         The width, when available
+	 * - height:        The height, when available
+	 *
+	 * Generation based on \Joomla\Plugin\Filesystem\Local\Adapter\LocalAdapter::getPathInformation()
+	 *
+	 * Properties generated:
+	 * - created_date_formatted:  DATE_FORMAT_LC5 formatted string based on create_date
+	 * - modified_date_formatted: DATE_FORMAT_LC5 formatted string based on modified_date
+	 *
+	 * @param   \stdClass  $item  The item to set
+	 *
+	 * @return \stdClass
+	 *
+	 * @since   __DEPLOY_VERSION__
+	 *
+	 * @throws \BadMethodCallException
+	 */
+	protected function setItem(\stdClass $item): \stdClass
+	{
+		// Make immutable object
+		$item = clone $item;
+
+		$this->validate($item);
+
+		return $item;
+	}
+}

administrator/components/com_media/src/Event/FetchMediaItemUrlEvent.php

@@ -0,0 +1,103 @@
+<?php
+/**
+ * @package     Joomla.Administrator
+ * @subpackage  com_media
+ *
+ * @copyright   (C) 2021 Open Source Matters, Inc. <https://www.joomla.org>
+ * @license     GNU General Public License version 2 or later; see LICENSE.txt
+ */
+
+namespace Joomla\Component\Media\Administrator\Event;
+
+\defined('_JEXEC') or die;
+
+use Joomla\CMS\Event\AbstractImmutableEvent;
+
+/**
+ * Event object to set an url.
+ *
+ * @since  __DEPLOY_VERSION__
+ */
+final class FetchMediaItemUrlEvent extends AbstractImmutableEvent
+{
+	/**
+	 * Constructor.
+	 *
+	 * @param   string  $name       The event name.
+	 * @param   array   $arguments  The event arguments.
+	 *
+	 * @throws  \BadMethodCallException
+	 *
+	 * @since  __DEPLOY_VERSION__
+	 */
+	public function __construct($name, array $arguments = array())
+	{
+		// Check for required arguments
+		if (!\array_key_exists('adapter', $arguments) || !is_string($arguments['adapter']))
+		{
+			throw new \BadMethodCallException("Argument 'adapter' of event $name is not of the expected type");
+		}
+
+		$this->arguments[$arguments['adapter']] = $arguments['adapter'];
+		unset($arguments['adapter']);
+
+		// Check for required arguments
+		if (!\array_key_exists('path', $arguments) || !is_string($arguments['path']))
+		{
+			throw new \BadMethodCallException("Argument 'path' of event $name is not of the expected type");
+		}
+
+		$this->arguments[$arguments['path']] = $arguments['path'];
+		unset($arguments['path']);
+
+		// Check for required arguments
+		if (!\array_key_exists('url', $arguments) || !is_string($arguments['url']))
+		{
+				throw new \BadMethodCallException("Argument 'url' of event $name is not of the expected type");
+		}
+
+		parent::__construct($name, $arguments);
+	}
+
+	/**
+	 * Validate $value to be a string
+	 *
+	 * @param   string  $value  The value to set
+	 *
+	 * @return string
+	 *
+	 * @since   __DEPLOY_VERSION__
+	 */
+	protected function setUrl(string $value): string
+	{
+		return $value;
+	}
+
+	/**
+	 * Forbid setting $path
+	 *
+	 * @param   string  $value  The value to set
+	 *
+	 * @since   __DEPLOY_VERSION__
+	 *
+	 * @throws \BadMethodCallException
+	 */
+	protected function setPath(string $value): string
+	{
+		throw new \BadMethodCallException('Cannot set the argument "path" of the immutable event ' . $this->name . '.');
+	}
+
+	/**
+	 * Forbid setting $path
+	 *
+	 * @param   string  $value  The value to set
+	 *
+	 * @since   __DEPLOY_VERSION__
+	 *
+	 * @throws \BadMethodCallException
+	 */
+	protected function setAdapter(string $value): string
+	{
+		throw new \BadMethodCallException('Cannot set the argument "adapter" of the immutable event ' . $this->name . '.');
+	}
+}