Merge pull request codeigniter4#4727 from MGatner/publisher

Publisher Class

app/Config/Publisher.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace Config;
+
+use CodeIgniter\Config\Publisher as BasePublisher;
+
+/**
+ * Publisher Configuration
+ *
+ * Defines basic security restrictions for the Publisher class
+ * to prevent abuse by injecting malicious files into a project.
+ */
+class Publisher extends BasePublisher
+{
+	/**
+	 * A list of allowed destinations with a (pseudo-)regex
+	 * of allowed files for each destination.
+	 * Attempts to publish to directories not in this list will
+	 * result in a PublisherException. Files that do no fit the
+	 * pattern will cause copy/merge to fail.
+	 *
+	 * @var array<string,string>
+	 */
+	public $restrictions = [
+		ROOTPATH => '*',
+		FCPATH   => '#\.(?css|js|map|htm?|xml|json|webmanifest|tff|eot|woff?|gif|jpe?g|tiff?|png|webp|bmp|ico|svg)$#i',
+	];
+}

system/Commands/Utilities/Publish.php

@@ -0,0 +1,113 @@
+<?php
+
+/**
+ * This file is part of the CodeIgniter 4 framework.
+ *
+ * (c) CodeIgniter Foundation <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace CodeIgniter\Commands\Utilities;
+
+use CodeIgniter\CLI\BaseCommand;
+use CodeIgniter\CLI\CLI;
+use CodeIgniter\Publisher\Publisher;
+
+/**
+ * Discovers all Publisher classes from the "Publishers/" directory
+ * across namespaces. Executes `publish()` from each instance, parsing
+ * each result.
+ */
+class Publish extends BaseCommand
+{
+	/**
+	 * The group the command is lumped under
+	 * when listing commands.
+	 *
+	 * @var string
+	 */
+	protected $group = 'CodeIgniter';
+
+	/**
+	 * The Command's name
+	 *
+	 * @var string
+	 */
+	protected $name = 'publish';
+
+	/**
+	 * The Command's short description
+	 *
+	 * @var string
+	 */
+	protected $description = 'Discovers and executes all predefined Publisher classes.';
+
+	/**
+	 * The Command's usage
+	 *
+	 * @var string
+	 */
+	protected $usage = 'publish [<directory>]';
+
+	/**
+	 * The Command's arguments
+	 *
+	 * @var array<string, string>
+	 */
+	protected $arguments = [
+		'directory' => '[Optional] The directory to scan within each namespace. Default: "Publishers".',
+	];
+
+	/**
+	 * the Command's Options
+	 *
+	 * @var array
+	 */
+	protected $options = [];
+
+	//--------------------------------------------------------------------
+
+	/**
+	 * Displays the help for the spark cli script itself.
+	 *
+	 * @param array $params
+	 */
+	public function run(array $params)
+	{
+		$directory = array_shift($params) ?? 'Publishers';
+
+		if ([] === $publishers = Publisher::discover($directory))
+		{
+			CLI::write(lang('Publisher.publishMissing', [$directory]));
+			return;
+		}
+
+		foreach ($publishers as $publisher)
+		{
+			if ($publisher->publish())
+			{
+				CLI::write(lang('Publisher.publishSuccess', [
+					get_class($publisher),
+					count($publisher->getPublished()),
+					$publisher->getDestination(),
+				]), 'green');
+			}
+			else
+			{
+				CLI::error(lang('Publisher.publishFailure', [
+					get_class($publisher),
+					$publisher->getDestination(),
+				]), 'light_gray', 'red');
+
+				foreach ($publisher->getErrors() as $file => $exception)
+				{
+					CLI::write($file);
+					CLI::error($exception->getMessage());
+					CLI::newLine();
+				}
+			}
+		}
+	}
+}

system/Config/Publisher.php

@@ -0,0 +1,42 @@
+<?php
+
+/**
+ * This file is part of the CodeIgniter 4 framework.
+ *
+ * (c) CodeIgniter Foundation <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace CodeIgniter\Config;
+
+/**
+ * Publisher Configuration
+ *
+ * Defines basic security restrictions for the Publisher class
+ * to prevent abuse by injecting malicious files into a project.
+ */
+class Publisher extends BaseConfig
+{
+	/**
+	 * A list of allowed destinations with a (pseudo-)regex
+	 * of allowed files for each destination.
+	 * Attempts to publish to directories not in this list will
+	 * result in a PublisherException. Files that do no fit the
+	 * pattern will cause copy/merge to fail.
+	 *
+	 * @var array<string,string>
+	 */
+	public $restrictions = [
+		ROOTPATH => '*',
+		FCPATH   => '#\.(?css|js|map|htm?|xml|json|webmanifest|tff|eot|woff?|gif|jpe?g|tiff?|png|webp|bmp|ico|svg)$#i',
+	];
+
+	/**
+	 * Disables Registrars to prevent modules from altering the restrictions.
+	 */
+	final protected function registerProperties()
+	{
+	}
+}

system/Language/en/Publisher.php

@@ -0,0 +1,24 @@
+<?php
+
+/**
+ * This file is part of the CodeIgniter 4 framework.
+ *
+ * (c) CodeIgniter Foundation <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+// Publisher language settings
+return [
+	'collision'             => 'Publisher encountered an unexpected {0} while copying {1} to {2}.',
+	'expectedDirectory'     => 'Publisher::{0} expects a valid directory.',
+	'expectedFile'          => 'Publisher::{0} expects a valid file.',
+	'destinationNotAllowed' => 'Destination is not on the allowed list of Publisher directories: {0}',
+	'fileNotAllowed'        => '{0} fails the following restriction for {1}: {2}',
+
+	// Publish Command
+	'publishMissing'    => 'No Publisher classes detected in {0} across all namespaces.',
+	'publishSuccess'    => '{0} published {1} file(s) to {2}.',
+	'publishFailure'    => '{0} failed to publish to {1}!',
+];

system/Publisher/Exceptions/PublisherException.php

@@ -0,0 +1,75 @@
+<?php
+
+/**
+ * This file is part of the CodeIgniter 4 framework.
+ *
+ * (c) CodeIgniter Foundation <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace CodeIgniter\Publisher\Exceptions;
+
+use CodeIgniter\Exceptions\FrameworkException;
+
+/**
+ * Publisher Exception Class
+ *
+ * Handles exceptions related to actions taken by a Publisher.
+ */
+class PublisherException extends FrameworkException
+{
+	/**
+	 * Throws when a file should be overwritten yet cannot.
+	 *
+	 * @param string $from The source file
+	 * @param string $to   The destination file
+	 */
+	public static function forCollision(string $from, string $to)
+	{
+		return new static(lang('Publisher.collision', [filetype($to), $from, $to]));
+	}
+
+	/**
+	 * Throws when an object is expected to be a directory but is not or is missing.
+	 *
+	 * @param string $caller The method causing the exception
+	 */
+	public static function forExpectedDirectory(string $caller)
+	{
+		return new static(lang('Publisher.expectedDirectory', [$caller]));
+	}
+
+	/**
+	 * Throws when an object is expected to be a file but is not or is missing.
+	 *
+	 * @param string $caller The method causing the exception
+	 */
+	public static function forExpectedFile(string $caller)
+	{
+		return new static(lang('Publisher.expectedFile', [$caller]));
+	}
+
+	/**
+	 * Throws when given a destination that is not in the list of allowed directories.
+	 *
+	 * @param string $destination
+	 */
+	public static function forDestinationNotAllowed(string $destination)
+	{
+		return new static(lang('Publisher.destinationNotAllowed', [$destination]));
+	}
+
+	/**
+	 * Throws when a file fails to match the allowed pattern for its destination.
+	 *
+	 * @param string $file
+	 * @param string $directory
+	 * @param string $pattern
+	 */
+	public static function forFileNotAllowed(string $file, string $directory, string $pattern)
+	{
+		return new static(lang('Publisher.fileNotAllowed', [$file, $directory, $pattern]));
+	}
+}