Builder¶
Usage and Interface¶
Usage¶
Note
The classes found in the Builder can be used independently too. See the Quickstart link bellow.
Quickstart
The Builder class is mutable. It will accept an Immutable class of the corresponding scheme.
The usage is straight forward:
$ftpUrl = 'ftp://user:password@host:123/path';
$ftpImmutable = Scheme::ftp($ftpUrl);
$builder = Builder::ftp($ftpImmutable);
$builder->setUser('JohnDoe')
->setHost('example.com')
->setPassword('hunter2')
->setPort(987);
$builder->getPathBag()
->set(0, 'new path value')
->set(1, 'another path value');
echo $builder->raw(); // ftp://JohnDoe:hunter2@example.com:987/new path value/another path value/
echo $builder->encoded(); // ftp://JohnDoe:hunter2@example.com:987/new+path+value/another+path+value/
$url = 'https://john.doe@www.example.com:123/forum/questions/?tag=networking&order=newest#top';
$httpsImmutable = Scheme::https($url);
$builder = Builder::https($httpsImmutable);
...
$url = 'http://john.doe@www.example.com:123/forum/questions/?tag=networking&order=newest#top';
$httpImmutable = Scheme::http($url);
$builder = Builder::https($httpsImmutable);
...
$url = 'mailto:path@email.com,path2@email.com?to=email@example.com,email2@example.com&cc=email3@example.com,email4@example.com&bcc=email4@example.com,email5@example.com&subject=Hello&body=World';
$mailtoImmutable = Scheme::mailto($url);
$builder = Builder::https($mailtoImmutable);
...
The builder also contains bags for the query or path. Given that it can exist within the given scheme.
Some schemes don’t have a path or a query. For example the FTP scheme officially does not support a query, thus the Builder doesn’t support one either.
$ftpUrl = 'ftp://user:password@host:123/path';
$ftpImmutable = Scheme::ftp($ftpUrl);
$builder = Builder::ftp($ftpImmutable);
// Only path
$builder->getPathBag()->...;
Other types of urls will support both a path and a query bag.
$url = 'https://john.doe@www.example.com:123/forum/questions/?tag=networking&order=newest#top';
$httpsImmutable = Scheme::https($url);
$builder = Builder::https($httpsImmutable);
$builder->getPathBag()->...;
$builder->getQueryBag()->...;
Builder Interface¶
All builders implement the ImmutableSchemeInterface which has the following functions
// Returns all the components of the scheme including any bags in the form of an array
// Will always return an array, even if empty.
public function all(): array;
// Returns raw unaltered url
public function raw(): string
// Returns the scheme associated with the class instance
public function getScheme(): string;
// Builds the url either encoded or not
public function build(bool $urlEncode = false): string;
Note
The build function is an alias for raw() and encoded() with the $urlEncode specified as either true or false
Bags Interface¶
All mutable bags(query and path) implement the MutableBagsInterface which has the following functions
// Returns all the components of the query or path
public function all(): array;
// Returns the encoded query or path string
public function encoded(): string;
// Return the raw unaltered query or path
public function raw(): string;
// Checks weather a given bag or path has a certain key
public function has($key): bool;
// Returns a given key
public function get($key);
// Sets a new entry in the path or query
public function set($key, $value);
// Returns all the components of the query or path
public function all(): array;
Mailto¶
The mailto builder has a path and a query bag along side the default interface options
The mailto builder class does it’s best to keep in accordance with https://tools.ietf.org/html/rfc6068
The mailto immutable has no other functions except the default implementations and getters for the bags.
The query bag¶
The mailto scheme can have a query consisting of: to recipients, cc recipients, bcc recipients, body, and subject.
Besides the getter functions specified in the previous chapter the builder has the following functions available.
public function putInTo(string $value): self
public function putInCc(string $value): self
public function putInBcc(string $value): self
public function forgetFromTo($keyOrValue): self
public function forgetFromCc($keyOrValue): self
public function forgetFromBcc($keyOrValue): self
public function forgetTo(): self
public function forgetCc(): self
public function forgetBcc(): self
public function forgetSubject(): self
public function forgetBody(): self
public function toHas(string $value): bool
public function ccHas(string $value): bool
public function bccHas(string $value): bool
public function forgetAll(): self
// Returns only the specified class properties(in this case)
public function only(string ...$args): array
Note
Functions such as get and set in this particular case will search for a class property rather than a query component
$url
= 'mailto:path@email.com,path2@email.com?to=email@example.com,email2@example.com'.
'&cc=email3@example.com,email4@example.com'.
'&bcc=email4@example.com,email5@example.com'.
'&subject=Hello'.
'&body=World';
$mailto = Scheme::mailto($url);
$builder = Builder::mailto($mailto);
var_dump($builder->getQueryBag()->only('cc', 'bcc'));
...
Array
(
[cc] => Array
(
[0] => email3@example.com
[1] => email4@example.com
)
[bcc] => Array
(
[0] => email4@example.com
[1] => email5@example.com
)
)
$builder->getQueryBag()->forgetFromBcc('email5@example.com');
$builder->getQueryBag()->forgetFromBcc(0);
var_dump($builder->getQueryBag()->only('cc', 'bcc'));
...
Array
(
[cc] => Array
(
[0] => email3@example.com
[1] => email4@example.com
)
[bcc] => Array
(
)
)
The path bag¶
Much like the query bag, the path bag comes with its own functions
public function setPath(array $path): self
public function getPath(): array
public function append(string $value): self
public function prepend(string $value): self
public function putInBetween(string $value, string $first = null, string $last = null): self
public function putBefore(string $before, string $value) : self
public function first()
public function last()
public function putAfter(string $after, string $value): self
public function forget(string ...$args): self
public function forgetAll(): self
public function only(string ...$args): array
$url
= 'mailto:path@email.com,path2@email.com?to=email@example.com,email2@example.com'.
'&cc=email3@example.com,email4@example.com'.
'&bcc=email4@example.com,email5@example.com'.
'&subject=Hello'.
'&body=World';
$mailto = Scheme::mailto($url);
$builder = Builder::mailto($mailto);
$builder->getPathBag()->putInBetween('new_value@test.com', 'path@email.com');
var_dump($builder->getPathBag()->all());
...
Array
(
[0] => path@email.com
[1] => new_value@test.com
[2] => path2@email.com
)
$builder->getPathBag()->putAfter('new_value@test.com', 'after_new_value@test.com');
var_dump($builder->getPathBag()->all());
...
Array
(
[0] => path@email.com
[1] => new_value@test.com
[2] => after_new_value@test.com
[3] => path2@email.com
)
Http and Https¶
The http and https schemes have a path and a query bag along side the default interface options
The http and https scheme classes do their best to keep in accordance with https://tools.ietf.org/html/rfc3986
Note
Due to major similarities between the 2 schemes there is a single section dedicated to both.
HOWEVER each scheme has its own dedicated builder.
public function getAuthority(): string
public function getUser(): string
public function getPassword(): string
public function getHost(): string
public function getPort(): ?int
public function getFragment(): string
public function getQueryBag(): HttpImmutableQuery
public function getPathBag(): HttpImmutablePath
public function setUser(string $user): self
public function setPassword(string $password): self
public function setHost(string $host): self
public function setPort(int $port): self
public function setFragment(string $fragment): self
The query bag¶
Besides the default interface implementation the http/https mutable bags classes have the following functions
public function first(): ?array
public function last()
public function forget(string ...$args): self
public function forgetAll(): self
public function only(string ...$args): array
The path bag¶
Besides the default interface implementation the http/https bags bags classes have the following functions
public function getPath(): array
public function first(): ?string
public function last(): ?string
public function append(string $value): self
public function prepend(string $value): self
public function putInBetween(string $value, string $first = null, string $last = null): self
public function putBefore(string $before, string $value) : self
public function putAfter(string $after, string $value): self
public function forget(string ...$args): self
public function forgetAll(): self
public function only(string ...$args): array
Ftp¶
The ftp builder has only a path bag along side the default interface options
The ftp class does its best to keep in accordance with https://tools.ietf.org/html/rfc3986
Besides the default interface implementation the ftp mutable class has the following functions
public function getPathBag(): FtpMutablePath
public function getUser(): string
public function getPassword(): string
public function getHost(): string
public function getPort(): int
public function setUser(string $user): self
public function setPassword(string $password): self
public function setHost(string $host): self
public function setPort(int $port): self
The path bag¶
Besides the default interface implementation the ftp immutable bag class has the following functions
public function getPath(): array
public function first(): ?string
public function last()
public function append(string $value): self
public function prepend(string $value): self
public function putInBetween(string $value, string $first = null, string $last = null): self
public function putBefore(string $before, string $value) : self
public function putAfter(string $after, string $value): self
public function forget(string ...$args): self
public function forgetAll(): self
public function only(string ...$args): array