Initial commit

kirby/src/Data/Data.php

@@ -0,0 +1,145 @@
+<?php
+
+namespace Kirby\Data;
+
+use Kirby\Exception\Exception;
+use Kirby\Filesystem\F;
+use Throwable;
+
+/**
+ * The `Data` class provides readers and
+ * writers for data. The class comes with
+ * handlers for `json`, `php`, `txt`, `xml`
+ * and `yaml` encoded data, but can be
+ * extended and customized.
+ *
+ * The read and write methods automatically
+ * detect which data handler to use in order
+ * to correctly encode and decode passed data.
+ *
+ * @package   Kirby
+ * @author    Bastian Allgeier <bastian@getkirby.com>
+ * @link      https://getkirby.com
+ * @copyright Bastian Allgeier
+ * @license   https://opensource.org/licenses/MIT
+ */
+class Data
+{
+	/**
+	 * Handler Type Aliases
+	 */
+	public static array $aliases = [
+		'md'    => 'txt',
+		'mdown' => 'txt',
+		'rss'   => 'xml',
+		'yml'   => 'yaml',
+	];
+
+	/**
+	 * All registered handlers
+	 */
+	public static array $handlers = [
+		'json' => Json::class,
+		'php'  => PHP::class,
+		'txt'  => Txt::class,
+		'xml'  => Xml::class,
+		'yaml' => Yaml::class
+	];
+
+	/**
+	 * Handler getter
+	 */
+	public static function handler(string $type): Handler
+	{
+		// normalize the type
+		$type = strtolower($type);
+
+		// find a handler or alias
+		$handler = static::$handlers[$type] ?? null;
+
+		if ($alias = static::$aliases[$type] ?? null) {
+			$handler ??= static::$handlers[$alias] ?? null;
+		}
+
+		if ($handler === null || class_exists($handler) === false) {
+			throw new Exception(
+				message: 'Missing handler for type: "' . $type . '"'
+			);
+		}
+
+		$handler = new $handler();
+
+		if ($handler instanceof Handler === false) {
+			throw new Exception(
+				message: 'Handler for type: "' . $type . '" needs to extend ' . Handler::class
+			);
+		}
+
+		return $handler;
+	}
+
+	/**
+	 * Decodes data with the specified handler
+	 */
+	public static function decode(
+		$string,
+		string $type,
+		bool $fail = true
+	): array {
+		try {
+			return static::handler($type)->decode($string);
+		} catch (Throwable $e) {
+			if ($fail === false) {
+				return [];
+			}
+
+			throw $e;
+		}
+	}
+
+	/**
+	 * Encodes data with the specified handler
+	 */
+	public static function encode($data, string $type): string
+	{
+		return static::handler($type)->encode($data);
+	}
+
+	/**
+	 * Reads data from a file;
+	 * the data handler is automatically chosen by
+	 * the extension if not specified
+	 */
+	public static function read(
+		string $file,
+		string|null $type = null,
+		bool $fail = true
+	): array {
+		try {
+			$type  ??= F::extension($file);
+			$handler = static::handler($type);
+			return $handler->read($file);
+		} catch (Throwable $e) {
+			if ($fail === false) {
+				return [];
+			}
+
+			throw $e;
+		}
+	}
+
+	/**
+	 * Writes data to a file;
+	 * the data handler is automatically chosen by
+	 * the extension if not specified
+	 */
+	public static function write(
+		string $file,
+		$data = [],
+		string|null $type = null
+	): bool {
+		$type  ??= F::extension($file);
+		$handler = static::handler($type);
+		return $handler->write($file, $data);
+	}
+}

kirby/src/Data/Handler.php

@@ -0,0 +1,56 @@
+<?php
+
+namespace Kirby\Data;
+
+use Kirby\Exception\Exception;
+use Kirby\Filesystem\F;
+
+/**
+ * Base handler abstract,
+ * which needs to be extended to
+ * create valid data handlers
+ *
+ * @package   Kirby Data
+ * @author    Bastian Allgeier <bastian@getkirby.com>
+ * @link      https://getkirby.com
+ * @copyright Bastian Allgeier
+ * @license   https://opensource.org/licenses/MIT
+ */
+abstract class Handler
+{
+	/**
+	 * Parses an encoded string and returns a multi-dimensional array
+	 *
+	 * @throws \Exception if the file can't be parsed
+	 */
+	abstract public static function decode($string): array;
+
+	/**
+	 * Converts an array to an encoded string
+	 */
+	abstract public static function encode($data): string;
+
+	/**
+	 * Reads data from a file
+	 */
+	public static function read(string $file): array
+	{
+		$contents = F::read($file);
+
+		if ($contents === false) {
+			throw new Exception(
+				message: 'The file "' . $file . '" does not exist or cannot be read'
+			);
+		}
+
+		return static::decode($contents);
+	}
+
+	/**
+	 * Writes data to a file
+	 */
+	public static function write(string $file, $data = []): bool
+	{
+		return F::write($file, static::encode($data));
+	}
+}

kirby/src/Data/Json.php

@@ -0,0 +1,61 @@
+<?php
+
+namespace Kirby\Data;
+
+use Kirby\Exception\InvalidArgumentException;
+
+/**
+ * Simple Wrapper around json_encode and json_decode
+ *
+ * @package   Kirby Data
+ * @author    Bastian Allgeier <bastian@getkirby.com>
+ * @link      https://getkirby.com
+ * @copyright Bastian Allgeier
+ * @license   https://opensource.org/licenses/MIT
+ */
+class Json extends Handler
+{
+	/**
+	 * Converts an array to an encoded JSON string
+	 */
+	public static function encode($data, bool $pretty = false): string
+	{
+		$constants = JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE;
+
+		if ($pretty === true) {
+			$constants |= JSON_PRETTY_PRINT;
+		}
+
+		return json_encode($data, $constants);
+	}
+
+	/**
+	 * Parses an encoded JSON string and returns a multi-dimensional array
+	 */
+	public static function decode($string): array
+	{
+		if ($string === null || $string === '') {
+			return [];
+		}
+
+		if (is_array($string) === true) {
+			return $string;
+		}
+
+		if (is_string($string) === false) {
+			throw new InvalidArgumentException(
+				message: 'Invalid JSON data; please pass a string'
+			);
+		}
+
+		$result = json_decode($string, true);
+
+		if (is_array($result) === true) {
+			return $result;
+		}
+
+		throw new InvalidArgumentException(
+			message: 'JSON string is invalid'
+		);
+	}
+}

kirby/src/Data/PHP.php

@@ -0,0 +1,98 @@
+<?php
+
+namespace Kirby\Data;
+
+use Kirby\Exception\BadMethodCallException;
+use Kirby\Exception\Exception;
+use Kirby\Filesystem\F;
+
+/**
+ * Reader and write of PHP files with data in a returned array
+ *
+ * @package   Kirby Data
+ * @author    Bastian Allgeier <bastian@getkirby.com>
+ * @link      https://getkirby.com
+ * @copyright Bastian Allgeier
+ * @license   https://opensource.org/licenses/MIT
+ */
+class PHP extends Handler
+{
+	/**
+	 * Converts data to PHP file content
+	 *
+	 * @param string $indent For internal use only
+	 */
+	public static function encode($data, string $indent = ''): string
+	{
+		return match (gettype($data)) {
+			'array'   => static::encodeArray($data, $indent),
+			'boolean' => $data ? 'true' : 'false',
+			'integer',
+			'double'  => (string)$data,
+			default   => var_export($data, true)
+		};
+	}
+
+	/**
+	 * Converts an array to PHP file content
+	 */
+	protected static function encodeArray(array $data, string $indent): string
+	{
+		$indexed = array_is_list($data);
+		$lines   = [];
+
+		foreach ($data as $key => $value) {
+			$line = "$indent    ";
+
+			if ($indexed === false) {
+				$line .= static::encode($key) . ' => ';
+			}
+
+			$line .= static::encode($value, "$indent    ");
+
+			$lines[] =  $line;
+		}
+
+		return "[\n" . implode(",\n", $lines) . "\n" . $indent . ']';
+	}
+
+	/**
+	 * PHP strings shouldn't be decoded manually
+	 */
+	public static function decode($string): array
+	{
+		throw new BadMethodCallException(
+			message: 'The PHP::decode() method is not implemented'
+		);
+	}
+
+	/**
+	 * Reads data from a file
+	 */
+	public static function read(string $file): array
+	{
+		if (is_file($file) !== true) {
+			throw new Exception(
+				message: 'The file "' . $file . '" does not exist'
+			);
+		}
+
+		return (array)F::load($file, [], allowOutput: false);
+	}
+
+	/**
+	 * Creates a PHP file with the given data
+	 */
+	public static function write(string $file, $data = []): bool
+	{
+		$php = static::encode($data);
+		$php = "<?php\n\nreturn $php;";
+
+		if (F::write($file, $php) === true) {
+			F::invalidateOpcodeCache($file);
+			return true;
+		}
+
+		return false; // @codeCoverageIgnore
+	}
+}

kirby/src/Data/Txt.php

@@ -0,0 +1,132 @@
+<?php
+
+namespace Kirby\Data;
+
+use Kirby\Exception\InvalidArgumentException;
+use Kirby\Toolkit\A;
+use Kirby\Toolkit\Str;
+
+/**
+ * Kirby Txt Data Handler
+ *
+ * @package   Kirby Data
+ * @author    Bastian Allgeier <bastian@getkirby.com>
+ * @link      https://getkirby.com
+ * @copyright Bastian Allgeier
+ * @license   https://opensource.org/licenses/MIT
+ */
+class Txt extends Handler
+{
+	/**
+	 * Converts an array to an encoded Kirby txt string
+	 */
+	public static function encode($data): string
+	{
+		$result = [];
+
+		foreach (A::wrap($data) as $key => $value) {
+			if (empty($key) === true || $value === null) {
+				continue;
+			}
+
+			$key          = Str::ucfirst(Str::slug($key));
+			$value        = static::encodeValue($value);
+			$result[$key] = static::encodeResult($key, $value);
+		}
+
+		return implode("\n\n----\n\n", $result);
+	}
+
+	/**
+	 * Helper for converting the value
+	 */
+	protected static function encodeValue(array|string|float $value): string
+	{
+		// avoid problems with certain values
+		$value = match (true) {
+			is_array($value) => Data::encode($value, 'yaml'),
+			is_float($value) => Str::float($value),
+			default          => $value
+		};
+
+		// escape accidental dividers within a field
+		$value = preg_replace('!(?<=\n|^)----!', '\\----', $value);
+
+		return $value;
+	}
+
+	/**
+	 * Helper for converting the key and value to the result string
+	 */
+	protected static function encodeResult(string $key, string $value): string
+	{
+		$value = trim($value);
+		$result = $key . ':';
+
+		$result .= match (preg_match('!\R!', $value)) {
+			// multi-line content
+			1 => "\n\n",
+			// single line content, just add space after colon
+			default => ' ',
+		};
+
+		$result .= $value;
+
+		return $result;
+	}
+
+	/**
+	 * Parses a Kirby txt string and returns a multi-dimensional array
+	 */
+	public static function decode($string): array
+	{
+		if ($string === null || $string === '') {
+			return [];
+		}
+
+		if (is_array($string) === true) {
+			return $string;
+		}
+
+		if (is_string($string) === false) {
+			throw new InvalidArgumentException(
+				message: 'Invalid TXT data; please pass a string'
+			);
+		}
+
+		// remove Unicode BOM at the beginning of the file
+		if (Str::startsWith($string, "\xEF\xBB\xBF") === true) {
+			$string = substr($string, 3);
+		}
+
+		// explode all fields by the line separator
+		$fields = preg_split('!\n----\s*\n*!', $string);
+
+		// start the data array
+		$data = [];
+
+		// loop through all fields and add them to the content
+		foreach ($fields as $field) {
+			if ($pos = strpos($field, ':')) {
+				$key = strtolower(trim(substr($field, 0, $pos)));
+				$key = str_replace(['-', ' '], '_', $key);
+
+				// Don't add fields with empty keys
+				if (empty($key) === true) {
+					continue;
+				}
+
+				$value = trim(substr($field, $pos + 1));
+
+				// unescape escaped dividers within a field
+				$data[$key] = preg_replace(
+					'!(?<=\n|^)\\\\----!',
+					'----',
+					$value
+				);
+			}
+		}
+
+		return $data;
+	}
+}

kirby/src/Data/Xml.php

@@ -0,0 +1,60 @@
+<?php
+
+namespace Kirby\Data;
+
+use Kirby\Exception\InvalidArgumentException;
+use Kirby\Toolkit\Xml as XmlConverter;
+
+/**
+ * Simple Wrapper around the XML parser of the Toolkit
+ *
+ * @package   Kirby Data
+ * @author    Lukas Bestle <lukas@getkirby.com>
+ * @link      https://getkirby.com
+ * @copyright Bastian Allgeier
+ * @license   https://opensource.org/licenses/MIT
+ */
+class Xml extends Handler
+{
+	/**
+	 * Converts an array to an encoded XML string
+	 */
+	public static function encode($data): string
+	{
+		return XmlConverter::create($data, 'data');
+	}
+
+	/**
+	 * Parses an encoded XML string and returns a multi-dimensional array
+	 */
+	public static function decode($string): array
+	{
+		if ($string === null || $string === '') {
+			return [];
+		}
+
+		if (is_array($string) === true) {
+			return $string;
+		}
+
+		if (is_string($string) === false) {
+			throw new InvalidArgumentException(
+				message: 'Invalid XML data; please pass a string'
+			);
+		}
+
+		$result = XmlConverter::parse($string);
+
+		if (is_array($result) === true) {
+			// remove the root's name if it is the default <data> to ensure that
+			// the decoded data is the same as the input to the encode() method
+			if ($result['@name'] === 'data') {
+				unset($result['@name']);
+			}
+
+			return $result;
+		}
+
+		throw new InvalidArgumentException(message: 'XML string is invalid');
+	}
+}

kirby/src/Data/Yaml.php

@@ -0,0 +1,63 @@
+<?php
+
+namespace Kirby\Data;
+
+use Kirby\Cms\App;
+use Kirby\Exception\InvalidArgumentException;
+
+/**
+ * Simple Wrapper around the Symfony or Spyc YAML class
+ *
+ * @package   Kirby Data
+ * @author    Bastian Allgeier <bastian@getkirby.com>
+ * @link      https://getkirby.com
+ * @copyright Bastian Allgeier
+ * @license   https://opensource.org/licenses/MIT
+ */
+class Yaml extends Handler
+{
+	/**
+	 * Converts an array to an encoded YAML string
+	 */
+	public static function encode($data): string
+	{
+		return match (static::handler()) {
+			'symfony' => YamlSymfony::encode($data),
+			default   => YamlSpyc::encode($data),
+		};
+	}
+
+	/**
+	 * Parses an encoded YAML string and returns a multi-dimensional array
+	 */
+	public static function decode($string): array
+	{
+		if ($string === null || $string === '') {
+			return [];
+		}
+
+		if (is_array($string) === true) {
+			return $string;
+		}
+
+		if (is_string($string) === false) {
+			throw new InvalidArgumentException(
+				message: 'Invalid YAML data; please pass a string'
+			);
+		}
+
+		return match (static::handler()) {
+			'symfony' => YamlSymfony::decode($string),
+			default   => YamlSpyc::decode($string)
+		};
+	}
+
+	/**
+	 * Returns which YAML parser (`spyc` or `symfony`)
+	 * is configured to be used
+	 */
+	public static function handler(): string
+	{
+		return App::instance(null, true)?->option('yaml.handler') ?? 'spyc';
+	}
+}

kirby/src/Data/YamlSpyc.php

@@ -0,0 +1,43 @@
+<?php
+
+namespace Kirby\Data;
+
+use Kirby\Exception\InvalidArgumentException;
+use Spyc;
+
+/**
+ * Simple Wrapper around the Spyc YAML class
+ *
+ * @package   Kirby Data
+ * @author    Bastian Allgeier <bastian@getkirby.com>
+ * @link      https://getkirby.com
+ * @copyright Bastian Allgeier
+ * @license   https://opensource.org/licenses/MIT
+ */
+class YamlSpyc
+{
+	/**
+	 * Converts an array to an encoded YAML string
+	 */
+	public static function encode($data): string
+	{
+		// $data, $indent, $wordwrap, $no_opening_dashes
+		return Spyc::YAMLDump($data, false, false, true);
+	}
+
+	/**
+	 * Parses an encoded YAML string and returns a multi-dimensional array
+	 */
+	public static function decode($string): array
+	{
+		$result = Spyc::YAMLLoadString($string);
+
+		if (is_array($result) === true) {
+			return $result;
+		}
+
+		// apparently Spyc always returns an array, even for invalid YAML syntax
+		// so this Exception should currently never be thrown
+		throw new InvalidArgumentException(message: 'The YAML data cannot be parsed'); // @codeCoverageIgnore
+	}
+}

kirby/src/Data/YamlSymfony.php

@@ -0,0 +1,44 @@
+<?php
+
+namespace Kirby\Data;
+
+use Kirby\Cms\App;
+use Kirby\Toolkit\A;
+use Symfony\Component\Yaml\Yaml as Symfony;
+
+/**
+ * Simple Wrapper around the Symfony YAML class
+ *
+ * @package   Kirby Data
+ * @author    Nico Hoffmann <nico@getkirby.com>
+ * @link      https://getkirby.com
+ * @copyright Bastian Allgeier
+ * @license   https://opensource.org/licenses/MIT
+ */
+class YamlSymfony
+{
+	/**
+	 * Converts an array to an encoded YAML string
+	 */
+	public static function encode($data): string
+	{
+		$kirby  = App::instance(null, true);
+
+		return Symfony::dump(
+			$data,
+			$kirby?->option('yaml.params.inline') ?? 9999,
+			$kirby?->option('yaml.params.indent') ?? 2,
+			Symfony::DUMP_MULTI_LINE_LITERAL_BLOCK | Symfony::DUMP_EMPTY_ARRAY_AS_SEQUENCE
+		);
+	}
+
+	/**
+	 * Parses an encoded YAML string and returns a multi-dimensional array
+	 */
+	public static function decode($string): array
+	{
+		$result = Symfony::parse($string);
+		$result = A::wrap($result);
+		return $result;
+	}
+}