Merge pull request #3563 from paulbalandan/format-new

Refactor Format class

Author: MGatner

app/Config/Format.php

@@ -1,54 +1,59 @@
-<?php namespace Config;
+<?php
+
+namespace Config;
 
 use CodeIgniter\Config\BaseConfig;
 
 class Format extends BaseConfig
 {
-	/*
-	|--------------------------------------------------------------------------
-	| Available Response Formats
-	|--------------------------------------------------------------------------
-	|
-	| When you perform content negotiation with the request, these are the
-	| available formats that your application supports. This is currently
-	| only used with the API\ResponseTrait. A valid Formatter must exist
-	| for the specified format.
-	|
-	| These formats are only checked when the data passed to the respond()
-	| method is an array.
-	|
-	*/
+	/**
+	 * --------------------------------------------------------------------------
+	 * Available Response Formats
+	 * --------------------------------------------------------------------------
+	 *
+	 * When you perform content negotiation with the request, these are the
+	 * available formats that your application supports. This is currently
+	 * only used with the API\ResponseTrait. A valid Formatter must exist
+	 * for the specified format.
+	 *
+	 * These formats are only checked when the data passed to the respond()
+	 * method is an array.
+	 *
+	 * @var string[]
+	 */
 	public $supportedResponseFormats = [
 		'application/json',
 		'application/xml', // machine-readable XML
 		'text/xml', // human-readable XML
 	];
 
-	/*
-	|--------------------------------------------------------------------------
-	| Formatters
-	|--------------------------------------------------------------------------
-	|
-	| Lists the class to use to format responses with of a particular type.
-	| For each mime type, list the class that should be used. Formatters
-	| can be retrieved through the getFormatter() method.
-	|
-	*/
+	/**
+	 * --------------------------------------------------------------------------
+	 * Formatters
+	 * --------------------------------------------------------------------------
+	 *
+	 * Lists the class to use to format responses with of a particular type.
+	 * For each mime type, list the class that should be used. Formatters
+	 * can be retrieved through the getFormatter() method.
+	 *
+	 * @var array<string, string>
+	 */
 	public $formatters = [
-		'application/json' => \CodeIgniter\Format\JSONFormatter::class,
-		'application/xml'  => \CodeIgniter\Format\XMLFormatter::class,
-		'text/xml'         => \CodeIgniter\Format\XMLFormatter::class,
+		'application/json' => 'CodeIgniter\Format\JSONFormatter',
+		'application/xml'  => 'CodeIgniter\Format\XMLFormatter',
+		'text/xml'         => 'CodeIgniter\Format\XMLFormatter',
 	];
 
-	/*
-	|--------------------------------------------------------------------------
-	| Formatters Options
-	|--------------------------------------------------------------------------
-	|
-	| Additional Options to adjust default formatters behaviour.
-	| For each mime type, list the additional options that should be used.
-	|
-	*/
+	/**
+	 * --------------------------------------------------------------------------
+	 * Formatters Options
+	 * --------------------------------------------------------------------------
+	 *
+	 * Additional Options to adjust default formatters behaviour.
+	 * For each mime type, list the additional options that should be used.
+	 *
+	 * @var array<string, int>
+	 */
 	public $formatterOptions = [
 		'application/json' => JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES,
 		'application/xml'  => 0,
@@ -63,24 +68,11 @@ class Format extends BaseConfig
 	 * @param string $mime
 	 *
 	 * @return \CodeIgniter\Format\FormatterInterface
+	 *
+	 * @deprecated This is an alias of `\CodeIgniter\Format\Format::getFormatter`. Use that instead.
 	 */
 	public function getFormatter(string $mime)
 	{
-		if (! array_key_exists($mime, $this->formatters))
-		{
-			throw new \InvalidArgumentException('No Formatter defined for mime type: ' . $mime);
-		}
-
-		$class = $this->formatters[$mime];
-
-		if (! class_exists($class))
-		{
-			throw new \BadMethodCallException($class . ' is not a valid Formatter.');
-		}
-
-		return new $class();
+		return Services::format()->getFormatter($mime);
 	}
-
-	//--------------------------------------------------------------------
-
 }

system/API/ResponseTrait.php

@@ -40,7 +40,7 @@
 namespace CodeIgniter\API;
 
 use CodeIgniter\HTTP\Response;
-use Config\Format;
+use Config\Services;
 
 /**
  * Response trait.
@@ -102,6 +102,13 @@ trait ResponseTrait
 	 */
 	protected $format = 'json';
 
+	/**
+	 * Current Formatter instance. This is usually set by ResponseTrait::format
+	 *
+	 * @var \CodeIgniter\Format\FormatterInterface
+	 */
+	protected $formatter;
+
 	//--------------------------------------------------------------------
 
 	/**
@@ -123,7 +130,8 @@ public function respond($data = null, int $status = null, string $message = '')
 
 			// Create the output var here in case of $this->response([]);
 			$output = null;
-		} // If data is null but status provided, keep the output empty.
+		}
+		// If data is null but status provided, keep the output empty.
 		elseif ($data === null && is_numeric($status))
 		{
 			$output = null;
@@ -134,8 +142,7 @@ public function respond($data = null, int $status = null, string $message = '')
 			$output = $this->format($data);
 		}
 
-		return $this->response->setBody($output)
-						->setStatusCode($status, $message);
+		return $this->response->setBody($output)->setStatusCode($status, $message);
 	}
 
 	//--------------------------------------------------------------------
@@ -159,7 +166,7 @@ public function fail($messages, int $status = 400, string $code = null, string $
 
 		$response = [
 			'status'   => $status,
-			'error'    => $code === null ? $status : $code,
+			'error'    => $code ?? $status,
 			'messages' => $messages,
 		];
 
@@ -386,25 +393,25 @@ protected function format($data = null)
 			return $data;
 		}
 
-		$config = new Format();
-		$format = "application/$this->format";
+		$format = Services::format();
+		$mime   = "application/{$this->format}";
 
 		// Determine correct response type through content negotiation if not explicitly declared
 		if (empty($this->format) || ! in_array($this->format, ['json', 'xml'], true))
 		{
-			$format = $this->request->negotiate('media', $config->supportedResponseFormats, false);
+			$mime = $this->request->negotiate('media', $format->getConfig()->supportedResponseFormats, false);
 		}
 
-		$this->response->setContentType($format);
+		$this->response->setContentType($mime);
 
 		// if we don't have a formatter, make one
 		if (! isset($this->formatter))
 		{
 			// if no formatter, use the default
-			$this->formatter = $config->getFormatter($format); // @phpstan-ignore-line
+			$this->formatter = $format->getFormatter($mime);
 		}
 
-		if ($format !== 'application/json')
+		if ($mime !== 'application/json')
 		{
 			// Recursively convert objects into associative arrays
 			// Conversion not required for JSONFormatter

system/Config/Services.php

@@ -51,6 +51,7 @@
 use CodeIgniter\Encryption\EncrypterInterface;
 use CodeIgniter\Encryption\Encryption;
 use CodeIgniter\Filters\Filters;
+use CodeIgniter\Format\Format;
 use CodeIgniter\Honeypot\Honeypot;
 use CodeIgniter\HTTP\CLIRequest;
 use CodeIgniter\HTTP\CURLRequest;
@@ -83,6 +84,7 @@
 use Config\Email as EmailConfig;
 use Config\Encryption as EncryptionConfig;
 use Config\Exceptions as ExceptionsConfig;
+use Config\Format as FormatConfig;
 use Config\Filters as FiltersConfig;
 use Config\Honeypot as HoneypotConfig;
 use Config\Images;
@@ -311,6 +313,28 @@ public static function filters(FiltersConfig $config = null, bool $getShared = t
 
 	//--------------------------------------------------------------------
 
+	/**
+	 * The Format class is a convenient place to create Formatters.
+	 *
+	 * @param \Config\Format|null $config
+	 * @param boolean             $getShared
+	 *
+	 * @return \CodeIgniter\Format\Format
+	 */
+	public static function format(FormatConfig $config = null, bool $getShared = true)
+	{
+		if ($getShared)
+		{
+			return static::getSharedInstance('format', $config);
+		}
+
+		$config = $config ?? config('Format');
+
+		return new Format($config);
+	}
+
+	//--------------------------------------------------------------------
+
 	/**
 	 * The Honeypot provides a secret input on forms that bots should NOT
 	 * fill in, providing an additional safeguard when accepting user input.

system/Format/Exceptions/FormatException.php

@@ -1,22 +1,100 @@
-<?php namespace CodeIgniter\Format\Exceptions;
+<?php
+
+/**
+ * CodeIgniter
+ *
+ * An open source application development framework for PHP
+ *
+ * This content is released under the MIT License (MIT)
+ *
+ * Copyright (c) 2014-2019 British Columbia Institute of Technology
+ * Copyright (c) 2019-2020 CodeIgniter Foundation
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ * @package    CodeIgniter
+ * @author     CodeIgniter Dev Team
+ * @copyright  2019-2020 CodeIgniter Foundation
+ * @license    https://opensource.org/licenses/MIT	MIT License
+ * @link       https://codeigniter.com
+ * @since      Version 4.0.0
+ * @filesource
+ */
+
+namespace CodeIgniter\Format\Exceptions;
 
 use CodeIgniter\Exceptions\ExceptionInterface;
+use RuntimeException;
 
-class FormatException extends \RuntimeException implements ExceptionInterface
+/**
+ * FormatException
+ */
+class FormatException extends RuntimeException implements ExceptionInterface
 {
+	/**
+	 * Thrown when the instantiated class does not exist.
+	 *
+	 * @param string $class
+	 *
+	 * @return FormatException
+	 */
+	public static function forInvalidFormatter(string $class)
+	{
+		return new static(lang('Format.invalidFormatter', [$class]));
+	}
+
+	/**
+	 * Thrown in JSONFormatter when the json_encode produces
+	 * an error code other than JSON_ERROR_NONE and JSON_ERROR_RECURSION.
+	 *
+	 * @param string $error
+	 *
+	 * @return FormatException
+	 */
 	public static function forInvalidJSON(string $error = null)
 	{
 		return new static(lang('Format.invalidJSON', [$error]));
 	}
 
 	/**
-	 * This will never be thrown in travis-ci
+	 * Thrown when the supplied MIME type has no
+	 * defined Formatter class.
+	 *
+	 * @param string $mime
+	 *
+	 * @return FormatException
+	 */
+	public static function forInvalidMime(string $mime)
+	{
+		return new static(lang('Format.invalidMime', [$mime]));
+	}
+
+	/**
+	 * Thrown on XMLFormatter when the `simplexml` extension
+	 * is not installed.
+	 *
+	 * @return FormatException
 	 *
 	 * @codeCoverageIgnore
 	 */
 	public static function forMissingExtension()
 	{
 		return new static(lang('Format.missingExtension'));
 	}
-
 }