https://github.com/kuria/url
Parsing, modifying and building URLs
https://github.com/kuria/url
php querystring url url-builder url-parser url-parsing
Last synced: 28 days ago
JSON representation
Parsing, modifying and building URLs
- Host: GitHub
- URL: https://github.com/kuria/url
- Owner: kuria
- License: mit
- Created: 2017-07-10T22:07:48.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2023-04-22T14:38:39.000Z (about 2 years ago)
- Last Synced: 2025-03-12T22:05:39.990Z (about 2 months ago)
- Topics: php, querystring, url, url-builder, url-parser, url-parsing
- Language: PHP
- Homepage:
- Size: 21.5 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.rst
- Changelog: CHANGELOG.rst
- License: LICENSE
Awesome Lists containing this project
README
Url
###
Parsing, modifying and building URLs.
.. image:: https://travis-ci.com/kuria/url.svg?branch=master
:target: https://travis-ci.com/kuria/url
.. contents::
:depth: 3
Features
********
- parsing URLs
- building relative and absolute URLs, including protocol-relative URLs
- getting, checking and setting individual URL components:
- scheme
- host
- port
- path
- query parameters
- fragment
Requirements
************
- PHP 7.1+
Usage
*****
Creating a new URL
==================
Create a new instance of ``Url`` and use constructor arguments or setters
to define the components:
.. code:: php
setScheme('http');
$url->setHost('example.com');
$url->setPath('/test');
// many more setters are available..
echo $url;
Output:
::
http://example.com/test
Parsing an URL
==============
.. code:: php
`_
component, which integrates with ``kuria/url``.
.. NOTE::
Parsing URLs that contain username and a password is supported, but these components are ignored.
Such URLs are deprecated according to RFC 3986.
Getting URL components
======================
.. code:: php
var_dump(
$url->getScheme(),
$url->getHost(),
$url->getFullHost(),
$url->getPort(),
$url->getPath(),
$url->getQuery(),
$url->getFragment()
);
// checking whether a certain component is defined
var_dump(
$url->hasScheme(),
$url->hasHost(),
$url->hasPort(),
$url->hasPath(),
$url->hasQuery(),
$url->hasFragment()
);
Output:
::
string(4) "http"
string(11) "example.com"
string(16) "example.com:8080"
int(8080)
string(5) "/test"
array(2) {
["foo"]=>
string(3) "bar"
["lorem"]=>
string(5) "ipsum"
}
string(8) "fragment"
bool(true)
bool(true)
bool(true)
bool(true)
bool(true)
bool(true)
Getting query parameters
========================
.. code:: php
has('foo'),
$url->has('nonexistent'),
$url->get('foo'),
$url->get('lorem'),
$url->get('nonexistent')
);
Output:
::
bool(true)
bool(false)
string(3) "bar"
array(2) {
[0]=>
string(5) "ipsum"
[1]=>
string(5) "dolor"
}
NULL
Manipulating query parameters
=============================
Setting a single parameter
--------------------------
.. code:: php
set('parameter', 'value');
Removing a single parameter
---------------------------
.. code:: php
remove('foo');
Setting multiple parameters
---------------------------
.. code:: php
add(['foo' => 'bar', 'lorem' => 'ipsum']);
Replacing all parameters
------------------------
.. code:: php
setQuery(['foo' => 'bar']);
Removing all parameters
-----------------------
.. code:: php
removeAll();
Building URLs
=============
Using ``build()`` or ``__toString()``
-------------------------------------
These methods will return an absolute or relative URL.
- if no host is specified, a relative URL will be returned
- if the host is specified, an absolute URL will be returned
(unless the `preferred format option `_ is set to relative)
.. code:: php
setPath('/test');
var_dump($url->build());
$url->setScheme('http');
$url->setHost('example.com');
var_dump($url->build());
Output:
::
string(5) "/test"
string(23) "http://example.com/test"
Specifying a preferred format
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
By default, ``build()`` and ``__toString()`` return an absolute URL if the host is specified.
This behavior can be changed by passing the ``$preferredFormat`` parameter to the constructor,
``Url::parse()`` or the ``setPreferredFormat()`` method.
- ``Url::RELATIVE`` - prefer generating a relative URL even if the host is specified
- ``Url::ABSOLUTE`` - prefer generating an absolute URL if a host is specified
.. code:: php
setPreferredFormat(Url::RELATIVE);
echo $url, "\n";
Output:
::
http://example.com/foo
/foo
Using ``buildAbsolute()``
-------------------------
This method will always return an absolute URL.
If the host is not defined, ``Kuria\Url\Exception\IncompleteUrlException``
will be thrown.
.. code:: php
setScheme('http');
$url->setHost('example.com');
$url->setPath('/test');
var_dump($url->buildAbsolute());
Output:
::
string(23) "http://example.com/test"
.. NOTE::
Building an absolute URL with undefined scheme will yield a protocol-relative URL.
Example: *//localhost/test*
Using ``buildRelative()``
-------------------------
This method will always return a relative URL regardless of whether the host
is defined or not.
.. code:: php
setScheme('http');
$url->setHost('example.com');
$url->setPath('/test');
var_dump($url->buildRelative());
Output:
::
string(5) "/test"