Code Monkey home page Code Monkey logo

url-parser's Introduction

URL-Parser

GitHub GitHub Workflow Status Codecov Packagist Packagist

A WHATWG URL spec compliant URL parser for working with URLs and their query strings.

This API offers 2 objects that you can use to help you work with URLs; URL and URLSearchParams.

Requirements

  • PHP >= 7.1
  • ext-json
  • ext-mbstring
  • brick/math
  • rowbot/idna

Installation

composer require rowbot/url

URL

The URL object is the primary object for working with a URL.

The URL constructor

URL(self|string $url[, self|string $base])

URL constructor throws

  • \Rowbot\URL\Exception\TypeError
    • When the URL parser determines that the given input is not a valid URL.
use Rowbot\URL\URL;

// Construct a new URL object.
$url = new URL('https://example.com/');

// Construct a new URL object using a relative URL, by also providing the constructor with the base URL.
$url = new URL('path/to/file.php?query=string', 'http://example.com');
echo $url->href; // Outputs: "http://example.com/path/to/file.php?query=string"

// You can also pass an existing URL object to either the $url or $base arguments.
$url = new URL('https://example.org:123');
$url1 = new URL('foo/bar/', $url);
echo $url1->href; // Outputs: "https://example.org:123/foo/bar/"

// Catch the error when URL parsing fails.
try {
    $url = new URL('http://2001::1]');
} catch (\Rowbot\URL\Exception\TypeError $e) {
    echo 'Invalid URL';
}

URL Members

Note: As a convience, both the __get() and __set() methods will throw an \InvalidArgumentException if you try to get or set an invalid property.

string URL::href

The href getter returns the serialization of the URL. The href setter will parse the entire string updating all the components of the URL with the new values. Providing an invalid URL will cause the setter to throw a \Rowbot\URL\TypeError.

readonly string URL::origin

The origin member is readonly. Its output is in the form of scheme://host:port. If a URL does not have a port, then that will be excluded from the output.

string URL::protocol

The protocol getter, also known as a scheme, returns the protocol of the URL, such as http, ftp, or ssh. The protocol setter is used to change the URLs protocol.

string URL::username

The username getter returns the username portion of the URL, or an empty string if the URL does not contain a username. The username setter changes the URLs username.

string URL::password

The password getter returns the password portion of the URL, or an empty string if the URL does not contain a password. The password setter changes the URLs password.

string URL::host

The host getter returns the combination of hostname and port. The output would look like hostname:port. If the URL does not have a port, then the port is not present in the output. The host setter allows you to change both the hostname and port at the same time.

string URL::hostname

The hostname getter returns the hostname of the URL. For example, the hostname of https://example.com:31 would be example.com. The hostname setter will change the hostname portion of the URL.

string URL::port

The port getter returns an integer as a string representing the URLs port. If the URL does not have a port, the empty string will be returned instead. The port setter updates the URLs port.

string URL::pathname

The pathname getter returns the URLs path. The pathname setter updates the URLs path.

string URL::search

The search getter returns the URLs query string. The search setter updates the URLs URLSearchParams list.

readonly URLSearchParams URL::searchParams

Returns the URLSearchParams object associated with this URL allowing you to modify the query parameters without having to clobber the entire query string. This will always return the same object.

string URL::hash

The hash getter, also known as a URLs fragment, returns the portion of the URL that follows the "#" character. The hash setter updates the portion of the URL that follows the "#".

string URL::toJSON()

Returns a JSON encoded string of the URL. Note that this method escapes forward slashes, which is not the default for PHPs json_encode(), but matches the default behavior of JavaScripts JSON.stringify(). If you wish to control the serialization, then pass the URL obect to the json_encode() function.

string URL::jsonSerialize()

The URL object implements the JsonSerializable interface allowing you to pass the object as a whole to the json_encode() function.

string URL::toString()

Returns the serialization of the URL.

string URL::__toString()

See URL::toString()

URLSearchParams

The URLSearchParams object allows you to work with query strings when you don't need a full URL. The URLSearchParams object implements the Iterator interface so that you may iterate over the list of search parameters. The iterator will return an array containing exactly 2 items. The first item is the parameter name and the second item is the parameter value.

The URLSearchParams constructor

URLSearchParams([self|iterable<int|string, iterable<int|string, scalar|\Stringable>>|object|string $init])

URLSearchParams constructor throws

  • \Rowbot\URL\Exception\TypeError
    • When an iterable is passed and one if its values is not iterable.
    • When an iterable is passed and one of its values is not countable, such as an object that implements \Iterator, but not \Countable.
    • When an iterable is passed and one of its sequences does not contain exactly 2 items, such as an array that contains only 1 string.
use Rowbot\URL\URLSearchParams;

// Construct an empty list of search params.
$params = new URLSearchParams();

// Construct a new list from a query string. Remember that a leading "?" will be stripped.
$params = new URLSearchParams('?foo=bar');

// Construct a new list using an array of arrays containing strings. Alternatively, you could pass an
// object that implements the Traversable interface and whose iterator returns an array of arrays,
// with each array containing exactly 2 items.
$params = new URLSearchParams([
    ['foo', 'bar'],
    ['foo', 'bar'] // Duplicates are allowed!
    ['one', 'two']
]);

// Iterate over a URLSearchParams object.
foreach ($params as $index => $param) {
    if ($index > 0) {
        echo '&';
    }

    echo $param[0] . '=' . $param[1];
}

// Above loop prints "foo=bar&foo=bar&one=two".

// Construct a new list using an object
$obj = new \stdClass();
$obj->foo = 'bar';
$params = new URLSearchParams($obj);

// Copy an existing URLSearchParams object into a new one.
$params1 = new URLSearchParams($params);

URLSearchParams Members

void URLSearchParams::append(string $name, string $value)

Appends a new name-value pair to the list.

void URLSearchParams::delete(string $name)

Deletes all name-value pairs whose name is $name from the list.

string|null URLSearchParams::get(string $name)

Returns the value of the first name-value pair whose name is $name in the list or null if there are no name-value pairs whose name is $name in the list.

string[] URLSearchParams::getAll(string $name)

Returns a list of values of all name-value pairs whose name is $name, in list order, or the empty list if there are no name-value pairs whose name is $name in the list.

bool URLSearchParams::has(string $name)

Returns true if there is a name-value pair in the list, and false otherwise.

void URLSearchParams::set(string $name, string $value)

If the list contains name-value pairs whose name is $name, the first name-value pair in the list whose name is $name will have its value changed to $value and all others following it in the list will be removed. If the list does not contain a name-value pair whose name is $name then the new name-value pair will be appended to the list.

void URLSearchParams::sort()

Sorts the list of search params by comparing code units. The relative order of name-value pairs with the same name are preserved.

string URLSearchParams::toString()

Returns the serialization of the list of name-value pairs.

string URLSearchParams::__toString()

See URLSearchParams::toString()

url-parser's People

Contributors

nyamsprod avatar trowbotham avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar

url-parser's Issues

Outdated ICU

First up: I really love this library. After a long search it was exactly what I needed.

Unfortunately, there are hosters our there that offer php 7.1+ with an outdated ICU version, which causes the usage of certain IDN constants to fail. Would you be amendable to implementing a similar fix to this one?

Remove support for PHP5

@TRowbotham currently the parser still support PHP5 which will hit EOL at the end of the year. Do you plan on stopping PHP5 support anytime soon ?

Do you want to be notified when the parser encounters a validation error?

Basically, there are 3 questions here:

  1. Do you want to be notified when the parser encounters a validation error?
  2. Should there be a way to enable and disable validation error reporting?
  3. What would be the best way to convey the error information?

There are roughly 60 different places in the parser that currently call for a validation error to be reported. As far as I can tell, I have 3 options for reporting the error. I can use error_log(), trigger_error(), or I can push each error onto an array that can then be retrieved through a method added to the URL class. I am, of course, open to other ideas.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.