172 lines
3.3 KiB
Markdown
172 lines
3.3 KiB
Markdown
# PHP Url
|
|
## Description
|
|
|
|
A simple library for interacting with URLs using an object-oriented approach.
|
|
|
|
Provides tools to build, modify, and parse URLs.
|
|
Can be used in API client classes or in dependency injection contexts.
|
|
|
|
Requires PHP 8.2 or higher.
|
|
|
|
* [Objects API](./docs/OBJECTS.md)
|
|
|
|
## Components
|
|
|
|
* **Builder** - URL instance builder
|
|
* **Facade** - Facade simplify usage
|
|
* **Parser** - Raw string url parser
|
|
* **Serializer** - URL instance serializer
|
|
* **Url** - URL instance representation
|
|
* **Util** - Inner utilities
|
|
|
|
#### Builders
|
|
|
|
* **HostRelative** - Builds a url relative to the hostname, setup scheme and port
|
|
* **ReplaceAttributes** - Builds new url instance with passed params replacement
|
|
|
|
#### Serializers
|
|
|
|
* **RFC3986** - Serializes url instance to RFC3986 string
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
composer require diffhead/php-url
|
|
composer test
|
|
```
|
|
|
|
## Usage
|
|
|
|
```php
|
|
use Diffhead\PHP\Url\Facade;
|
|
use Diffhead\PHP\Url\Dto\Replace;
|
|
|
|
/**
|
|
* @var \Diffhead\PHP\Url\Url $url
|
|
*/
|
|
$url = Facade::parse('www.google.com');
|
|
|
|
/**
|
|
* @var string
|
|
*/
|
|
$string = Facade::toRfc3986String($url);
|
|
|
|
/**
|
|
* Parameters are optionally.
|
|
* If null passed then will not
|
|
* be replaced.
|
|
*/
|
|
$dto = new Replace(
|
|
scheme: 'https',
|
|
hostname: 'www.github.com',
|
|
port: 443,
|
|
path: '/',
|
|
parameters: []
|
|
);
|
|
|
|
/**
|
|
* @var \Diffhead\PHP\Url\Url $replaced
|
|
*/
|
|
$replaced = Facade::replace($url, $dto);
|
|
```
|
|
|
|
#### Parsing URL
|
|
```php
|
|
use Diffhead\PHP\Url\Parser;
|
|
use Diffhead\PHP\Url\Exception\UrlNotContainsPort;
|
|
|
|
$parser = new Parser('ftp://localhost/some/entity?public=1');
|
|
|
|
/**
|
|
* @var string $scheme
|
|
*/
|
|
$scheme = $parser->getScheme();
|
|
|
|
/**
|
|
* @var string $hostname
|
|
*/
|
|
$hostname = $parser->getHostname();
|
|
|
|
/**
|
|
* @var int $port
|
|
*/
|
|
try {
|
|
$port = $parser->getPort();
|
|
} catch (UrlNotContainsPort $e) {
|
|
$port = 0;
|
|
}
|
|
|
|
/**
|
|
* @var string $path
|
|
*/
|
|
$path = $parser->getPath();
|
|
|
|
/**
|
|
* @var array{public:string}
|
|
*/
|
|
$query = $parser->getParameters();
|
|
```
|
|
|
|
#### Using with the DI container
|
|
```php
|
|
use Diffhead\PHP\Url\Builder;
|
|
use Diffhead\PHP\Url\Builder\HostRelative;
|
|
use Diffhead\PHP\Url\Port;
|
|
use Diffhead\PHP\Url\Scheme;
|
|
use Diffhead\PHP\Url\Serializer;
|
|
use Diffhead\PHP\Url\Serializer\RFC3986;
|
|
use GuzzleHttp\Client;
|
|
|
|
class Url
|
|
{
|
|
public function __construct(
|
|
private Builder $builder,
|
|
private Serializer $serializer
|
|
) {}
|
|
|
|
public function get(string $path, array $query = []): string
|
|
{
|
|
return $this->serializer->serialize(
|
|
$this->builder->build($path, $query)
|
|
);
|
|
}
|
|
}
|
|
|
|
class Client
|
|
{
|
|
public function __construct(
|
|
private Client $http,
|
|
private Url $url
|
|
) {}
|
|
|
|
public function items(FetchItemsRequest $request): FetchItemsResponse
|
|
{
|
|
$response = $this->http->post(
|
|
$this->url->get('/v1/things'),
|
|
$this->getJsonRequestOptions($request)
|
|
);
|
|
|
|
return FetchItemsResponse::fromArray(
|
|
json_decode((string) $response->getBody(), true)
|
|
);
|
|
}
|
|
}
|
|
|
|
/**
|
|
* @var \DI\Container $container
|
|
*/
|
|
$container->set(Url::class, function (): Url {
|
|
$domain = getenv('API_DOMAIN');
|
|
$scheme = Scheme::Https->value;
|
|
$port = Port::WebSecure->value;
|
|
|
|
$builder = new HostRelative($domain, $scheme, $port);
|
|
$serializer = new RFC3986();
|
|
|
|
return new Url($builder, $serializer);
|
|
});
|
|
|
|
|
|
$container->get(Client::class);
|
|
```
|