1<?php
2
3/**
4 * League.Uri (https://uri.thephpleague.com)
5 *
6 * (c) Ignace Nyamagana Butera <nyamsprod@gmail.com>
7 *
8 * For the full copyright and license information, please view the LICENSE
9 * file that was distributed with this source code.
10 */
11
12declare(strict_types=1);
13
14namespace League\Uri\Contracts;
15
16use League\Uri\Exceptions\IdnSupportMissing;
17use League\Uri\Exceptions\SyntaxError;
18
19interface UriComponentInterface extends \JsonSerializable
20{
21    /**
22     * Returns the instance content.
23     *
24     * If the instance is defined, the value returned MUST be encoded according to the
25     * selected encoding algorithm. In any case, the value MUST NOT double-encode any character
26     * depending on the selected encoding algorithm.
27     *
28     * To determine what characters to encode, please refer to RFC 3986, Sections 2 and 3.
29     * or RFC 3987 Section 3. By default the content is encoded according to RFC3986
30     *
31     * If the instance is not defined null is returned
32     */
33    public function getContent(): ?string;
34
35    /**
36     * Returns the instance string representation.
37     *
38     * If the instance is defined, the value returned MUST be percent-encoded,
39     * but MUST NOT double-encode any characters. To determine what characters
40     * to encode, please refer to RFC 3986, Sections 2 and 3.
41     *
42     * If the instance is not defined an empty string is returned
43     */
44    public function __toString(): string;
45
46    /**
47     * Returns the instance json representation.
48     *
49     * If the instance is defined, the value returned MUST be percent-encoded,
50     * but MUST NOT double-encode any characters. To determine what characters
51     * to encode, please refer to RFC 3986 or RFC 1738.
52     *
53     * If the instance is not defined null is returned
54     */
55    public function jsonSerialize(): ?string;
56
57    /**
58     * Returns the instance string representation with its optional URI delimiters.
59     *
60     * The value returned MUST be percent-encoded, but MUST NOT double-encode any
61     * characters. To determine what characters to encode, please refer to RFC 3986,
62     * Sections 2 and 3.
63     *
64     * If the instance is not defined an empty string is returned
65     */
66    public function getUriComponent(): string;
67
68    /**
69     * Returns an instance with the specified content.
70     *
71     * This method MUST retain the state of the current instance, and return
72     * an instance that contains the specified content.
73     *
74     * Users can provide both encoded and decoded content characters.
75     *
76     * A null value is equivalent to removing the component content.
77     *
78     *
79     * @param ?string $content
80     *
81     * @throws SyntaxError       for invalid component or transformations
82     *                           that would result in a object in invalid state.
83     * @throws IdnSupportMissing for component or transformations
84     *                           requiring IDN support when IDN support is not present
85     *                           or misconfigured.
86     */
87    public function withContent(?string $content): self;
88}
89