1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
|
---
layout: default
title: URI common interfaces and tools
---
Uri Interfaces
=======
This package contains an interface to represents URI objects according to [RFC 3986](http://tools.ietf.org/html/rfc3986).
System Requirements
-------
You need:
- **PHP >= 8.1** but the latest stable version of PHP is recommended
Install
--------
```
$ composer require league/uri-interfaces
```
Documentation
--------
### League\Uri\Contract\UriInterface
The `UriInterface` interface models generic URIs as specified in [RFC 3986](http://tools.ietf.org/html/rfc3986).
The interface provides methods for interacting with the various URI parts, which will obviate the need for repeated parsing of the URI.
It also specifies:
- a `__toString()` method for casting the modeled URI to its string representation.
- a `jsonSerialize()` method to improve interoperability with [WHATWG URL Living standard](https://url.spec.whatwg.org/)
#### Accessing URI properties
The `UriInterface` interface defines the following methods to access the URI string representation, its individual parts and components.
~~~php
<?php
public UriInterface::__toString():string
public UriInterface::jsonSerialize():string
public UriInterface::getScheme():?string
public UriInterface::getUserInfo():?string
public UriInterface::getHost():?string
public UriInterface::getPort():?int
public UriInterface::getAuthority():?string
public UriInterface::getPath():string
public UriInterface::getQuery():?string
public UriInterface::getFragment():?string
~~~
#### Modifying URI properties
The `Uri` interface defines the following modifying methods. these methods **must** be implemented such that they retain the internal state of the current instance and return an instance that contains the changed state.
Delimiter characters are not part of the URI component and **must not** be added to the modifying method submitted value. If present they will be treated as part of the URI component content.
**These methods will trigger a `League\Uri\Contract\UriException` exception if the resulting URI is not valid. The validation is scheme dependent.**
~~~php
<?php
public UriInterface::withScheme(?string $scheme): self
public UriInterface::withUserInfo(?string $user [, string $password = null]): self
public UriInterface::withHost(?string $host): self
public UriInterface::withPort(?int $port): self
public UriInterface::withPath(string $path): self
public UriInterface::withQuery(?string $query): self
public UriInterface::withFragment(?string $fragment): self
~~~
#### Relation with [PSR-7](http://www.php-fig.org/psr/psr-7/#3-5-psr-http-message-uriinterface)
This interface exposes the same methods as `Psr\Http\Message\UriInterface`. But, differs on the following keys:
- This interface does not require the `http` and `https` schemes to be supported.
- Setter and Getter component methods, with the exception of the path component, accept and can return the `null` value.
- If no scheme is present, you are not required to fallback to `http` and `https` schemes specific validation rules.
### League\Uri\Contract\UriComponentInterface
The `UriComponentInterface` interface models generic URI components as specified in [RFC 3986](http://tools.ietf.org/html/rfc3986). The interface provides methods for interacting with an URI component, which will obviate the need for repeated parsing of the URI component. It also specifies a `__toString()` method for casting the modeled URI component to its string representation.
#### Accessing URI properties
The `UriComponentInterface` interface defines the following methods to access the URI component content.
~~~php
<?php
public UriComponentInterface::getContent(): ?string
public UriComponentInterface::toString(): ?string
public UriComponentInterface::__toString(): string
public UriComponentInterface::getUriComponent(): ?string
public UriComponentInterface::jsonSerialize(): ?string
public UriComponentInterface::withContent(?string $content): self
~~~
### UriComponentInterface extended interfaces
Because each URI component has specific needs most have specialized interface which all extends the `UriComponentInterface` interface. The following interfaces also exist:
- `League\Uri\Contract\AuthorityInterface`
- `League\Uri\Contract\DataPathInterface`
- `League\Uri\Contract\DomainHostInterface`
- `League\Uri\Contract\FragmentInterface`
- `League\Uri\Contract\UserInfoInterface`
- `League\Uri\Contract\HostInterface`
- `League\Uri\Contract\IpHostInterface`
- `League\Uri\Contract\PathInterface`
- `League\Uri\Contract\PortInterface`
- `League\Uri\Contract\QueryInterface`
- `League\Uri\Contract\SegmentedPathInterface`
|
