league/uri-interfaces

Common interfaces and classes for URI representation and interaction

Maintainers

Details

github.com/thephpleague/uri-interfaces

Homepage

Source

Issues

Forum

Documentation

Fund package maintenance!
nyamsprod

Installs: 28 487 971

Dependents: 8

Suggesters: 0

Security: 0

Stars: 352

Watchers: 5

Forks: 6

2.3.0 2021-06-28 04:27 UTC

Requires

  • php: ^7.2 || ^8.0
  • ext-json: *

Requires (Dev)

Suggests

  • ext-intl: to use the IDNA feature
  • symfony/intl: to use the IDNA feature via Symfony Polyfill

MIT 00e7e2943f76d8cb50c7dfdc2f6dee356e15e383

urlurirfc3986rfc3987

This package is auto-updated.

Last update: 2023-02-26 20:53:46 UTC

README

This package contains an interface to represents URI objects according to RFC 3986.

System Requirements

You need:

  • PHP >= 7.2 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. 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

Accessing URI properties

The UriInterface interface defines the following methods to access the URI string representation, its individual parts and components.

<?php

public UriInterface::__toString(void): string
public UriInterface::jsonSerialize(void): string
public UriInterface::getScheme(void): ?string
public UriInterface::getUserInfo(void): ?string
public UriInterface::getHost(void): ?string
public UriInterface::getPort(void): ?int
public UriInterface::getAuthority(void): ?string
public UriInterface::getPath(void): string
public UriInterface::getQuery(void): ?string
public UriInterface::getFragment(void): ?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

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

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. 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
public UriComponentInterface::value(): ?string
public UriComponentInterface::toString(): ?string
public UriComponentInterface::__toString(): string
public UriComponentInterface::getContent(): ?string
public UriComponentInterface::getUriComponent(): ?string
public UriComponentInterface::jsonSerialize(): ?string
  • UriComponentInterface::value() added since version 2.4.0;
  • UriComponentInterface::toString() added since version 2.4.0;
  • UriComponentInterface::getContent() is deprecated since version 2.4.0 and is replaced by UriComponentInterface::value();
  • UriComponentInterface::withContent() is deprecated since version 2.4.0 with no replacement;

Modifying URI properties

The UriComponentInterface interface defines the following modifying method. this method must be implemented such that it retains the internal state of the current instance and return an instance that contains the changed state.

<?php

public UriComponentInterface::withContent(?string $content): static

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

Contributing

⚠️ this is a sub-split, for development, pull requests and issues, visit: https://github.com/thephpleague/uri-src

License

The MIT License (MIT). Please see License File for more information.