Add context builers

Author: mtarld

src/Symfony/Component/Serializer/CHANGELOG.md

@@ -1,6 +1,11 @@
 CHANGELOG
 =========
 
+6.1
+---
+
+ * Add the ability to create contexts using context builders.
+
 6.0
 ---
 

src/Symfony/Component/Serializer/Context/AbstractContextBuilder.php

@@ -0,0 +1,39 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Serializer\Context;
+
+/**
+ * @author Mathias Arlaud <[email protected]>
+ */
+abstract class AbstractContextBuilder
+{
+    private array $context;
+
+    final public function __construct(self|array $context = [])
+    {
+        if ($context instanceof self) {
+            $context = $context->toArray();
+        }
+
+        $this->context = $context;
+    }
+
+    final protected function with(string $key, mixed $value): static
+    {
+        return new static(array_merge($this->context, [$key => $value]));
+    }
+
+    public function toArray(): array
+    {
+        return $this->context;
+    }
+}

src/Symfony/Component/Serializer/Context/Encoder/CsvEncoderContextBuilder.php

@@ -0,0 +1,132 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Serializer\Context\Encoder;
+
+use Symfony\Component\Serializer\Context\AbstractContextBuilder;
+use Symfony\Component\Serializer\Encoder\CsvEncoder;
+use Symfony\Component\Serializer\Exception\InvalidArgumentException;
+
+/**
+ * A helper providing autocompletion for available CsvEncoder options.
+ *
+ * @author Mathias Arlaud <[email protected]>
+ */
+final class CsvEncoderContextBuilder extends AbstractContextBuilder
+{
+    /**
+     * Configures the column delimiter character.
+     *
+     * Must be a single character.
+     *
+     * @throws InvalidArgumentException
+     */
+    public function withDelimiter(?string $delimiter): static
+    {
+        if (null !== $delimiter && 1 !== \strlen($delimiter)) {
+            throw new InvalidArgumentException(sprintf('The "%s" delimiter must be a single character.', $delimiter));
+        }
+
+        return $this->with(CsvEncoder::DELIMITER_KEY, $delimiter);
+    }
+
+    /**
+     * Configures the field enclosure character.
+     *
+     * Must be a single character.
+     *
+     * @throws InvalidArgumentException
+     */
+    public function withEnclosure(?string $enclosure): static
+    {
+        if (null !== $enclosure && 1 !== \strlen($enclosure)) {
+            throw new InvalidArgumentException(sprintf('The "%s" enclosure must be a single character.', $enclosure));
+        }
+
+        return $this->with(CsvEncoder::ENCLOSURE_KEY, $enclosure);
+    }
+
+    /**
+     * Configures the escape character.
+     *
+     * Must be empty or a single character.
+     *
+     * @throws InvalidArgumentException
+     */
+    public function withEscapeChar(?string $escapeChar): static
+    {
+        if (null !== $escapeChar && \strlen($escapeChar) > 1) {
+            throw new InvalidArgumentException(sprintf('The "%s" escape character must be empty or a single character.', $escapeChar));
+        }
+
+        return $this->with(CsvEncoder::ESCAPE_CHAR_KEY, $escapeChar);
+    }
+
+    /**
+     * Configures the key separator when (un)flattening arrays.
+     */
+    public function withKeySeparator(?string $keySeparator): static
+    {
+        return $this->with(CsvEncoder::KEY_SEPARATOR_KEY, $keySeparator);
+    }
+
+    /**
+     * Configures the headers.
+     *
+     * @param list<mixed>|null $headers
+     */
+    public function withHeaders(?array $headers): static
+    {
+        return $this->with(CsvEncoder::HEADERS_KEY, $headers);
+    }
+
+    /**
+     * Configures whether formulas should be escaped.
+     */
+    public function withEscapedFormulas(?bool $escapedFormulas): static
+    {
+        return $this->with(CsvEncoder::ESCAPE_FORMULAS_KEY, $escapedFormulas);
+    }
+
+    /**
+     * Configures whether the decoded result should be considered as a collection
+     * or as a single element.
+     */
+    public function withAsCollection(?bool $asCollection): static
+    {
+        return $this->with(CsvEncoder::AS_COLLECTION_KEY, $asCollection);
+    }
+
+    /**
+     * Configures whether the input (or output) is containing (or will contain) headers.
+     */
+    public function withNoHeaders(?bool $noHeaders): static
+    {
+        return $this->with(CsvEncoder::NO_HEADERS_KEY, $noHeaders);
+    }
+
+    /**
+     * Configures the end of line characters.
+     */
+    public function withEndOfLine(?string $endOfLine): static
+    {
+        return $this->with(CsvEncoder::END_OF_LINE, $endOfLine);
+    }
+
+    /**
+     * Configures whether to add the UTF-8 Byte Order Mark (BOM)
+     * at the beginning of the encoded result or not.
+     */
+    public function withOutputUtf8Bom(?bool $outputUtf8Bom): static
+    {
+        return $this->with(CsvEncoder::OUTPUT_UTF8_BOM_KEY, $outputUtf8Bom);
+    }
+}

src/Symfony/Component/Serializer/Context/Encoder/JsonEncoderContextBuilder.php

@@ -0,0 +1,65 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Serializer\Context\Encoder;
+
+use Symfony\Component\Serializer\Context\AbstractContextBuilder;
+use Symfony\Component\Serializer\Encoder\JsonDecode;
+use Symfony\Component\Serializer\Encoder\JsonEncode;
+
+/**
+ * A helper providing autocompletion for available JsonEncoder options.
+ *
+ * @author Mathias Arlaud <[email protected]>
+ */
+final class JsonEncoderContextBuilder extends AbstractContextBuilder
+{
+    /**
+     * Configures the json_encode flags bitmask.
+     *
+     * @see https://www.php.net/manual/en/json.constants.php
+     */
+    public function withEncodeOptions(?int $options): static
+    {
+        return $this->with(JsonEncode::OPTIONS, $options);
+    }
+
+    /**
+     * Configures the json_decode flags bitmask.
+     *
+     * @see https://www.php.net/manual/en/json.constants.php
+     */
+    public function withDecodeOptions(?int $options): static
+    {
+        return $this->with(JsonDecode::OPTIONS, $options);
+    }
+
+    /**
+     * Configures whether decoded objects will be given as
+     * associative arrays or as nested stdClass.
+     */
+    public function withAssociative(?bool $associative): static
+    {
+        return $this->with(JsonDecode::ASSOCIATIVE, $associative);
+    }
+
+    /**
+     * Configures the maximum recursion depth.
+     *
+     * Must be strictly positive.
+     *
+     * @param positive-int|null $recursionDepth
+     */
+    public function withRecursionDepth(?int $recursionDepth): static
+    {
+        return $this->with(JsonDecode::RECURSION_DEPTH, $recursionDepth);
+    }
+}

src/Symfony/Component/Serializer/Context/Encoder/XmlEncoderContextBuilder.php

@@ -0,0 +1,130 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Serializer\Context\Encoder;
+
+use Symfony\Component\Serializer\Context\AbstractContextBuilder;
+use Symfony\Component\Serializer\Encoder\XmlEncoder;
+
+/**
+ * A helper providing autocompletion for available XmlEncoder options.
+ *
+ * @author Mathias Arlaud <[email protected]>
+ */
+final class XmlEncoderContextBuilder extends AbstractContextBuilder
+{
+    /**
+     * Configures whether the decoded result should be considered as a collection
+     * or as a single element.
+     */
+    public function withAsCollection(?bool $asCollection): static
+    {
+        return $this->with(XmlEncoder::AS_COLLECTION, $asCollection);
+    }
+
+    /**
+     * Configures node types to ignore while decoding.
+     *
+     * @see https://www.php.net/manual/en/dom.constants.php
+     *
+     * @param list<int>|null $decoderIgnoredNodeTypes
+     */
+    public function withDecoderIgnoredNodeTypes(?array $decoderIgnoredNodeTypes): static
+    {
+        return $this->with(XmlEncoder::DECODER_IGNORED_NODE_TYPES, $decoderIgnoredNodeTypes);
+    }
+
+    /**
+     * Configures node types to ignore while encoding.
+     *
+     * @see https://www.php.net/manual/en/dom.constants.php
+     *
+     * @param list<int>|null $encoderIgnoredNodeTypes
+     */
+    public function withEncoderIgnoredNodeTypes(?array $encoderIgnoredNodeTypes): static
+    {
+        return $this->with(XmlEncoder::ENCODER_IGNORED_NODE_TYPES, $encoderIgnoredNodeTypes);
+    }
+
+    /**
+     * Configures the DOMDocument encoding.
+     *
+     * @see https://www.php.net/manual/en/class.domdocument.php#domdocument.props.encoding
+     */
+    public function withEncoding(?string $encoding): static
+    {
+        return $this->with(XmlEncoder::ENCODING, $encoding);
+    }
+
+    /**
+     * Configures whether to encode with indentation and extra space.
+     *
+     * @see https://php.net/manual/en/class.domdocument.php#domdocument.props.formatoutput
+     */
+    public function withFormatOutput(?bool $formatOutput): static
+    {
+        return $this->with(XmlEncoder::FORMAT_OUTPUT, $formatOutput);
+    }
+
+    /**
+     * Configures the DOMDocument::loadXml options bitmask.
+     *
+     * @see https://www.php.net/manual/en/libxml.constants.php
+     */
+    public function withLoadOptions(?int $loadOptions): static
+    {
+        return $this->with(XmlEncoder::LOAD_OPTIONS, $loadOptions);
+    }
+
+    /**
+     * Configures whether to keep empty nodes.
+     */
+    public function withRemoveEmptyTags(?bool $removeEmptyTags): static
+    {
+        return $this->with(XmlEncoder::REMOVE_EMPTY_TAGS, $removeEmptyTags);
+    }
+
+    /**
+     * Configures name of the root node.
+     */
+    public function withRootNodeName(?string $rootNodeName): static
+    {
+        return $this->with(XmlEncoder::ROOT_NODE_NAME, $rootNodeName);
+    }
+
+    /**
+     * Configures whether the document will be standalone.
+     *
+     * @see https://php.net/manual/en/class.domdocument.php#domdocument.props.xmlstandalone
+     */
+    public function withStandalone(?bool $standalone): static
+    {
+        return $this->with(XmlEncoder::STANDALONE, $standalone);
+    }
+
+    /**
+     * Configures whether casting numeric string attributes to integers or floats.
+     */
+    public function withTypeCastAttributes(?bool $typeCastAttributes): static
+    {
+        return $this->with(XmlEncoder::TYPE_CAST_ATTRIBUTES, $typeCastAttributes);
+    }
+
+    /**
+     * Configures the version number of the document.
+     *
+     * @see https://php.net/manual/en/class.domdocument.php#domdocument.props.xmlversion
+     */
+    public function withVersion(?string $version): static
+    {
+        return $this->with(XmlEncoder::VERSION, $version);
+    }
+}