juststeveking / uri-builder

A simple URI builder in PHP that is slightly opinionated

URI Builder

A simple URI builder in PHP that is slightly opinionated

Purpose

The purpose of this package is to provide a fluent interface to build JSON:API compliant URI strings.

Usage

Using the built in parse_url in PHP will produce the following output:

[
    "scheme" => "https",
    "host" => "www.domain.com",
    "path" => "/api/v1/resource"
    "query" => "include=test,another&sort=-name",
]

This is fine for basic usage. To use this very opinionated package:

Building Pragmatically

$url = Uri::build()
           ->addScheme('https')
           ->addHost('www.domain.com')
           ->addPath('api/v1/resource')
           ->addQuery('include=test,another&sort=-name')
           ->addFragment('static-link-to-element');

Creating from a String

$url = Uri::fromString('https://www.domain.com/api/v1/resource?include=test,another&sort=-name')

Converting back to a String

$url = Uri::build()
           ->addScheme('https')
           ->addHost('www.domain.com')
           ->addPath('api/v1/resource')
           ->addQuery('include=test,another&sort=-name');

$string = $url->toString();

// optionally
echo (string) $url;

The toString method has an optional parameter which will allow you to urlencode the query parameters before returning the URI.

$url = Uri::build()
           ->addScheme('https')
           ->addHost('www.domain.com')
           ->addPath('api/v1/resource')
           ->addQuery('include=test,another&sort=-name');

$string = $url->toString(true)

Adding Query Parameters after creation

Creating query parameters after creation is pretty simple. You can pass through anything that isn't:

• An Object
• An Array

It has a helper option on the end of the function which will convert booleans to strings.

public function addQueryParam(string $key, $value, bool $covertBoolToString = false)

The following is how you use it:

$url = Uri::fromString('https://www.domain.com/api/v1/resource');
$url->addQueryParam('include', 'test,another,options')
    ->addQueryParam('published', true, true);

The output will be: https://www.domain.com/api/v1/resource?include=test,another,options&published=true

uri-builder's Issues

Call to undefined function Safe\parse_url()

After install the package and when i try to use the Uri::fromString() to my laravel project it throws me an error.

Call to undefined function Safe\parse_url()

I have to install composer require thecodingmachine/safe to remove the error

Add ability to append path instead of replace

Hi Steve,

is Ok to add this to the package? this makes it more easy to use while building "dynamic" urls:

    /**
     * Set the Uri Path.
     *
     * @param  null|string $path
     * @return self
     */
    public function appendToPath(string $path): self
    {
        $shouldPrefixSlash = str_ends_with(
            haystack: $this->path,
            needle: '/',
        ) === false && str_starts_with(
                haystack: $path,
                needle: '/',
            ) === false;

        $this->path .= $shouldPrefixSlash ? "/$path" : "$path";

        return $this;
    }

I've already tested this code.

Duplicated parse_url

Hi @JustSteveKing,

what is the reason that you are parsing fragment with parse_url($original) and not using already parsed uri on start?

Thank you :)