@wordpress/url
Version:
WordPress URL utilities.
420 lines (241 loc) • 9.41 kB
Markdown
# URL
A collection of utilities to manipulate URLs.
## Installation
Install the module
```bash
npm install @wordpress/url --save
```
_This package assumes that your code will run in an **ES2015+** environment. If you're using an environment that has limited or no support for ES2015+ such as lower versions of IE then using [core-js](https://github.com/zloirock/core-js) or [@babel/polyfill](https://babeljs.io/docs/en/next/babel-polyfill) will add support for these methods. Learn more about it in [Babel docs](https://babeljs.io/docs/en/next/caveats)._
## Usage
<!-- START TOKEN(Autogenerated API docs) -->
<a name="addQueryArgs" href="#addQueryArgs">#</a> **addQueryArgs**
Appends arguments as querystring to the provided URL. If the URL already
includes query arguments, the arguments are merged with (and take precedent
over) the existing set.
_Usage_
```js
const newURL = addQueryArgs( 'https://google.com', { q: 'test' } ); // https://google.com/?q=test
```
_Parameters_
- _url_ `[string]`: URL to which arguments should be appended. If omitted, only the resulting querystring is returned.
- _args_ `Object`: Query arguments to apply to URL.
_Returns_
- `string`: URL with arguments applied.
<a name="cleanForSlug" href="#cleanForSlug">#</a> **cleanForSlug**
Performs some basic cleanup of a string for use as a post slug.
This replicates some of what `sanitize_title()` does in WordPress core, but
is only designed to approximate what the slug will be.
Converts whitespace, periods, forward slashes and underscores to hyphens.
Converts Latin-1 Supplement and Latin Extended-A letters to basic Latin
letters. Removes combining diacritical marks. Converts remaining string
to lowercase. It does not touch octets, HTML entities, or other encoded
characters.
_Parameters_
- _string_ `string`: Title or slug to be processed.
_Returns_
- `string`: Processed string.
<a name="filterURLForDisplay" href="#filterURLForDisplay">#</a> **filterURLForDisplay**
Returns a URL for display.
_Usage_
```js
const displayUrl = filterURLForDisplay( 'https://www.wordpress.org/gutenberg/' ); // wordpress.org/gutenberg
```
_Parameters_
- _url_ `string`: Original URL.
_Returns_
- `string`: Displayed URL.
<a name="getAuthority" href="#getAuthority">#</a> **getAuthority**
Returns the authority part of the URL.
_Usage_
```js
const authority1 = getAuthority( 'https://wordpress.org/help/' ); // 'wordpress.org'
const authority2 = getAuthority( 'https://localhost:8080/test/' ); // 'localhost:8080'
```
_Parameters_
- _url_ `string`: The full URL.
_Returns_
- `(string|void)`: The authority part of the URL.
<a name="getFragment" href="#getFragment">#</a> **getFragment**
Returns the fragment part of the URL.
_Usage_
```js
const fragment1 = getFragment( 'http://localhost:8080/this/is/a/test?query=true#fragment' ); // '#fragment'
const fragment2 = getFragment( 'https://wordpress.org#another-fragment?query=true' ); // '#another-fragment'
```
_Parameters_
- _url_ `string`: The full URL
_Returns_
- `(string|void)`: The fragment part of the URL.
<a name="getPath" href="#getPath">#</a> **getPath**
Returns the path part of the URL.
_Usage_
```js
const path1 = getPath( 'http://localhost:8080/this/is/a/test?query=true' ); // 'this/is/a/test'
const path2 = getPath( 'https://wordpress.org/help/faq/' ); // 'help/faq'
```
_Parameters_
- _url_ `string`: The full URL.
_Returns_
- `(string|void)`: The path part of the URL.
<a name="getProtocol" href="#getProtocol">#</a> **getProtocol**
Returns the protocol part of the URL.
_Usage_
```js
const protocol1 = getProtocol( 'tel:012345678' ); // 'tel:'
const protocol2 = getProtocol( 'https://wordpress.org' ); // 'https:'
```
_Parameters_
- _url_ `string`: The full URL.
_Returns_
- `(string|void)`: The protocol part of the URL.
<a name="getQueryArg" href="#getQueryArg">#</a> **getQueryArg**
Returns a single query argument of the url
_Usage_
```js
const foo = getQueryArg( 'https://wordpress.org?foo=bar&bar=baz', 'foo' ); // bar
```
_Parameters_
- _url_ `string`: URL.
- _arg_ `string`: Query arg name.
_Returns_
- `(QueryArgParsed|undefined)`: Query arg value.
<a name="getQueryString" href="#getQueryString">#</a> **getQueryString**
Returns the query string part of the URL.
_Usage_
```js
const queryString = getQueryString( 'http://localhost:8080/this/is/a/test?query=true#fragment' ); // 'query=true'
```
_Parameters_
- _url_ `string`: The full URL.
_Returns_
- `(string|void)`: The query string part of the URL.
<a name="hasQueryArg" href="#hasQueryArg">#</a> **hasQueryArg**
Determines whether the URL contains a given query arg.
_Usage_
```js
const hasBar = hasQueryArg( 'https://wordpress.org?foo=bar&bar=baz', 'bar' ); // true
```
_Parameters_
- _url_ `string`: URL.
- _arg_ `string`: Query arg name.
_Returns_
- `boolean`: Whether or not the URL contains the query arg.
<a name="isEmail" href="#isEmail">#</a> **isEmail**
Determines whether the given string looks like an email.
_Usage_
```js
const isEmail = isEmail( 'hello@wordpress.org' ); // true
```
_Parameters_
- _email_ `string`: The string to scrutinise.
_Returns_
- `boolean`: Whether or not it looks like an email.
<a name="isURL" href="#isURL">#</a> **isURL**
Determines whether the given string looks like a URL.
_Related_
- <https://url.spec.whatwg.org/>
- <https://url.spec.whatwg.org/#valid-url-string>
_Usage_
```js
const isURL = isURL( 'https://wordpress.org' ); // true
```
_Parameters_
- _url_ `string`: The string to scrutinise.
_Returns_
- `boolean`: Whether or not it looks like a URL.
<a name="isValidAuthority" href="#isValidAuthority">#</a> **isValidAuthority**
Checks for invalid characters within the provided authority.
_Usage_
```js
const isValid = isValidAuthority( 'wordpress.org' ); // true
const isNotValid = isValidAuthority( 'wordpress#org' ); // false
```
_Parameters_
- _authority_ `string`: A string containing the URL authority.
_Returns_
- `boolean`: True if the argument contains a valid authority.
<a name="isValidFragment" href="#isValidFragment">#</a> **isValidFragment**
Checks for invalid characters within the provided fragment.
_Usage_
```js
const isValid = isValidFragment( '#valid-fragment' ); // true
const isNotValid = isValidFragment( '#invalid-#fragment' ); // false
```
_Parameters_
- _fragment_ `string`: The url fragment.
_Returns_
- `boolean`: True if the argument contains a valid fragment.
<a name="isValidPath" href="#isValidPath">#</a> **isValidPath**
Checks for invalid characters within the provided path.
_Usage_
```js
const isValid = isValidPath( 'test/path/' ); // true
const isNotValid = isValidPath( '/invalid?test/path/' ); // false
```
_Parameters_
- _path_ `string`: The URL path.
_Returns_
- `boolean`: True if the argument contains a valid path
<a name="isValidProtocol" href="#isValidProtocol">#</a> **isValidProtocol**
Tests if a url protocol is valid.
_Usage_
```js
const isValid = isValidProtocol( 'https:' ); // true
const isNotValid = isValidProtocol( 'https :' ); // false
```
_Parameters_
- _protocol_ `string`: The url protocol.
_Returns_
- `boolean`: True if the argument is a valid protocol (e.g. http\:, tel:).
<a name="isValidQueryString" href="#isValidQueryString">#</a> **isValidQueryString**
Checks for invalid characters within the provided query string.
_Usage_
```js
const isValid = isValidQueryString( 'query=true&another=false' ); // true
const isNotValid = isValidQueryString( 'query=true?another=false' ); // false
```
_Parameters_
- _queryString_ `string`: The query string.
_Returns_
- `boolean`: True if the argument contains a valid query string.
<a name="prependHTTP" href="#prependHTTP">#</a> **prependHTTP**
Prepends "http\://" to a url, if it looks like something that is meant to be a TLD.
_Usage_
```js
const actualURL = prependHTTP( 'wordpress.org' ); // http://wordpress.org
```
_Parameters_
- _url_ `string`: The URL to test.
_Returns_
- `string`: The updated URL.
<a name="removeQueryArgs" href="#removeQueryArgs">#</a> **removeQueryArgs**
Removes arguments from the query string of the url
_Usage_
```js
const newUrl = removeQueryArgs( 'https://wordpress.org?foo=bar&bar=baz&baz=foobar', 'foo', 'bar' ); // https://wordpress.org?baz=foobar
```
_Parameters_
- _url_ `string`: URL.
- _args_ `...string`: Query Args.
_Returns_
- `string`: Updated URL.
<a name="safeDecodeURI" href="#safeDecodeURI">#</a> **safeDecodeURI**
Safely decodes a URI with `decodeURI`. Returns the URI unmodified if
`decodeURI` throws an error.
_Usage_
```js
const badUri = safeDecodeURI( '%z' ); // does not throw an Error, simply returns '%z'
```
_Parameters_
- _uri_ `string`: URI to decode.
_Returns_
- `string`: Decoded URI if possible.
<a name="safeDecodeURIComponent" href="#safeDecodeURIComponent">#</a> **safeDecodeURIComponent**
Safely decodes a URI component with `decodeURIComponent`. Returns the URI component unmodified if
`decodeURIComponent` throws an error.
_Parameters_
- _uriComponent_ `string`: URI component to decode.
_Returns_
- `string`: Decoded URI component if possible.
<!-- END TOKEN(Autogenerated API docs) -->
<br/><br/><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>