Version 5.0.0 beta 1

system/3rd_party/Pdp/DomainName.php

@@ -0,0 +1,123 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pdp;
+
+use Iterator;
+use IteratorAggregate;
+use Stringable;
+
+/**
+ * @see https://tools.ietf.org/html/rfc1034#section-3.5
+ * @see https://tools.ietf.org/html/rfc1123#section-2.1
+ * @see https://tools.ietf.org/html/rfc5890
+ *
+ * @extends IteratorAggregate<string>
+ */
+interface DomainName extends Host, IteratorAggregate
+{
+    /**
+     * Tells whether the current domain is in its ascii form.
+     */
+    public function isAscii(): bool;
+
+    /**
+     * Retrieves a single domain label.
+     *
+     * If $key is non-negative, the returned value will be the label at $key position from the start.
+     * If $key is negative, the returned value will be the label at $key position from the end.
+     *
+     * If no label is found the submitted $key the returned value will be null.
+     *
+     * @param int $key the label offset
+     */
+    public function label(int $key): ?string;
+
+    /**
+     * Returns the object labels.
+     *
+     * @return list<string>
+     */
+    public function labels(): array;
+
+    /**
+     * Returns the associated key for each label.
+     *
+     * If a value is specified only the keys associated with
+     * the given value will be returned
+     *
+     * @return list<int>
+     */
+    public function keys(?string $label = null): array;
+
+    /**
+     * The external iterator iterates over the DomainInterface labels
+     * from the right-most label to the left-most label.
+     *
+     * @return Iterator<string>
+     */
+    public function getIterator(): Iterator;
+
+    /**
+     * Prepends a label to the domain.
+     *
+     * @see ::withLabel
+     */
+    public function prepend(DomainNameProvider|Host|Stringable|string|int|null $label): self;
+
+    /**
+     * Appends a label to the domain.
+     *
+     * @see ::withLabel
+     */
+    public function append(DomainNameProvider|Host|Stringable|string|int|null $label): self;
+
+    /**
+     * Returns an instance with the specified label added at the specified key.
+     *
+     * This method MUST retain the state of the current instance, and return
+     * an instance that contains the new label
+     *
+     * If $key is non-negative, the added label will be the label at $key position from the start.
+     * If $key is negative, the added label will be the label at $key position from the end.
+     *
+     * @param DomainNameProvider|Host|Stringable|string|int|null $label a domain label
+     *
+     * @throws CannotProcessHost If the key is out of bounds
+     * @throws CannotProcessHost If the label is converted to the NULL value
+     */
+    public function withLabel(int $key, DomainNameProvider|Host|Stringable|string|int|null $label): self;
+
+    /**
+     * Returns an instance with the label at the specified key removed.
+     *
+     * This method MUST retain the state of the current instance, and return
+     * an instance without the specified label
+     *
+     * If $key is non-negative, the removed label will be the label at $key position from the start.
+     * If $key is negative, the removed label will be the label at $key position from the end.
+     *
+     *
+     * @throws CannotProcessHost If the key is out of bounds
+     */
+    public function withoutLabel(int ...$keys): self;
+
+    /**
+     * Returns an instance with all labels removed.
+     *
+     * This method MUST retain the state of the current instance, and return
+     * an instance that contains no label
+     */
+    public function clear(): self;
+
+    /**
+     * Extracts a slice of $length elements starting at position $offset from the Collection.
+     *
+     * This method MUST retain the state of the current instance, and return
+     * an instance that contains the selected slice.
+     *
+     * If $length is null it returns all elements from $offset to the end of the Domain.
+     */
+    public function slice(int $offset, ?int $length = null): self;
+}