josantonius/url

PHP library to access URL information.

v2.0.1 2022-09-29 21:29 UTC

Requires

• php: ^8.1

Requires (Dev)

• phpmd/phpmd: ^2.6
• phpunit/phpunit: ^9.5
• squizlabs/php_codesniffer: ^3.7

MIT

• Josantonius

• php
• path
• http
• url
• https
• parse
• uri

README

Translations: Español

PHP library to access URL information.

Provides an improved replacement for the access to the components of a URL offered by PHP's parse_url and pathinfo functions.

This library does not format the provided URL, it only makes it easier to access the components. For something more advanced you can use something like league/uri-components.

• Requirements
• Installation
• Available Classes
  • Url Class
• Usage
• Tests
• TODO
• Changelog
• Contribution
• Sponsor
• License

Requirements

• Operating System: Linux | Windows.

• PHP versions: 8.1 | 8.2.

Installation

The preferred way to install this extension is through Composer.

To install PHP URL library, simply:

composer require josantonius/url

The previous command will only install the necessary files, if you prefer to download the entire source code you can use:

composer require josantonius/url --prefer-source

You can also clone the complete repository with Git:

git clone https://github.com/josantonius/php-url.git

Available Classes

Url Class

Josantonius\Url\Url

Create a new instance:

/**
 * If no URL is provided, the URL of the current page will be generated.
 * 
 * The generated URL will exclude ports 80 and 443 and include the rest.
 */
public function __construct(null|string $url = null);

Gets authority:

/**
 * The authority, in "[user-info@][host][:port]" format.
 *
 * @var string URL authority or empty string.
 */
public readonly string $authority;

Gets the base URL:

/**
 * The base URL, in "[scheme:][//domain][:port]" format.
 *
 * @var string Base URL or empty string.
 */
public readonly string $base;

Gets the path basename:

/**
 * The path basename, in "[filename][.extension]" format.
 *
 * @var string URL path basename or empty string.
 */
public readonly string $basename;

Gets the path dirname:

/**
 * The path dirname, in "[dirname]" format.
 *
 * @var string URL path dirname or empty string.
 */
public readonly string $dirname;

Gets the path basename extension:

/**
 * The path basename extension, in "[extension]" format.
 *
 * @var string URL path basename extension or empty string.
 */
public readonly string $extension;

Gets the path filename:

/**
 * The path filename, in "[filename]" format.
 *
 * @var string URL path filename or empty string.
 */
public readonly string $filename;

Gets fragment:

/**
 * URL fragment in "[fragment]" format.
 *
 * @var string URL fragment or empty string.
 */
public readonly string $fragment;

Gets the full URL:

public readonly string $full;

Gets hashed fragment:

/**
 * URL hashed fragment in "[#fragment]" format.
 *
 * @var string URL hashed fragment or empty string.
 */
public readonly string $hash;

Gets host:

/**
 * URL host in "[subdomain.][domain][.tld]" format.
 *
 * @var string URL host or empty string.
 */
public readonly string $host;

Gets path:

/**
 * URL path in "[path]" format.
 *
 * @var string URL path or empty string.
 */
public readonly string $path;

Gets the query parameters:

/**
 * URL query parameters in array format.
 *
 * @var array<string, mixed> URL query parameters or empty string.
 */
public readonly array $parameters;

Gets password:

/**
 * URL password in "[password]" format.
 *
 * @var string URL password or empty string.
 */
public readonly string $password;

Gets port:

/**
 * URL port in "[port]" format.
 *
 * @var string URL port or empty string.
 */
public readonly int|string $port;

Gets scheme:

/**
 * URL scheme in "[scheme]" format.
 *
 * @var string URL scheme or empty string.
 */
public readonly string $scheme;

Gets path segments:

/**
 * URL path segments in array format.
 *
 * @var string[] URL path segments or empty string.
 */
public readonly array $segments;

Gets query:

/**
 * URL query in "[query]" format.
 *
 * @var string URL query or empty string.
 */
public readonly string $query;

Gets username:

/**
 * URL username in "[username]" format.
 *
 * @var string URL username or empty string.
 */
public readonly string $username;

Usage

Example of use for this library:

Create a new instance using the current URL

use Josantonius\Url\Url;

$url = new Url();

Create a new instance using custom URL

use Josantonius\Url\Url;

$url = new Url('https://domain.com');

Gets authority

use Josantonius\Url\Url;

$url = new Url(); // https://domain.com

$url->authority;  // "domain.com"


$url = new Url('https://user:[e-mail]:90/en/');

$url->authority; // "user:[e-mail]:90"


$url = new Url('https://user:[e-mail]/en/');

$url->authority; // "user:[e-mail]"


$url = new Url('https://sub.domain.com/en/');

$url->authority; // "sub.domain.com"

Gets base URL

use Josantonius\Url\Url;

$url = new Url(); // https://user:[e-mail]:80/en/

$url->base; // "https://domain.com"


$url = new Url('https://domain.com:80/?tag=bug');

$url->base; // "https://domain.com:80"


$url = new Url('https://domain.com/en/');

$url->base; // "https://domain.com"

Gets the path basename

use Josantonius\Url\Url;

$url = new Url(); // https://domain.com/search.php

$url->basename; // "search.php"


$url = new Url('https://domain.com/en/web/docs/search.php?tag=bug');

$url->basename; // "search.php"


$url = new Url('https://domain.com/en/web/docs?tag=bug');

$url->basename; // "docs"

Gets the path dirname

use Josantonius\Url\Url;

$url = new Url(); // https://domain.com/search.php

$url->dirname; // "/"


$url = new Url('https://domain.com/en/web/docs/search.php?tag=bug');

$url->dirname; // "/en/web/docs"


$url = new Url('https://domain.com/en/web/docs?tag=bug');

$url->dirname; // "/en/web"

Gets the path basename extension

use Josantonius\Url\Url;

$url = new Url(); // https://domain.com/search.php

$url->extension; // "php"


$url = new Url('https://domain.com/en/web/docs/search.php?tag=bug');

$url->extension; // "php"


$url = new Url('https://domain.com/en/web/docs?tag=bug');

$url->extension; // ""

Gets the path filename

use Josantonius\Url\Url;

$url = new Url(); // https://domain.com/search.php

$url->filename; // "search"


$url = new Url('https://domain.com/en/web/docs/search.php?tag=bug');

$url->filename; // "search"


$url = new Url('https://domain.com/docs?tag=bug');

$url->filename; // "docs"

Gets fragment

use Josantonius\Url\Url;

$url = new Url(); // https://domain.com#top

$url->fragment; // "top"


$url = new Url('https://domain.com/en/web/docs#top');

$url->fragment; // "top"


$url = new Url('https://domain.com');

$url->fragment; // ""

Gets the full URL

use Josantonius\Url\Url;

$url = new Url(); // https://domain.com:80

$url->full;  // "https://domain.com"


$url = new Url('https://user:[e-mail]:90/en/');

$url->full; // "https://user:[e-mail]:90/en/"

Gets hashed fragment

use Josantonius\Url\Url;

$url = new Url(); // https://domain.com#top

$url->hash; // "#top"


$url = new Url('https://domain.com/en/web/docs#top');

$url->hash; // "#top"


$url = new Url('https://domain.com');

$url->hash; // ""

Gets host

use Josantonius\Url\Url;

$url = new Url(); // https://sub.domain.com

$url->host; // "sub.domain.com"


$url = new Url('https://sub.domain.com/en/web/docs#top');

$url->host; // "sub.domain.com"


$url = new Url('https://domain.com');

$url->host; // "domain.com"


$url = new Url('https://localhost');

$url->host; // "localhost"

Gets path

use Josantonius\Url\Url;

$url = new Url(); // https://domain.com/en

$url->path; // "/en/web/docs/search.php"


$url = new Url('https://domain.com/en/web/docs/search.php');

$url->path; // "/en/web/docs/search.php"


$url = new Url('https://domain.com/en/web/docs/');

$url->path; // "/en/web/docs/"


$url = new Url('https://domain.com/en?tag=bug');

$url->path; // "/en"


$url = new Url('https://domain.com?tag=bug');

$url->path; // ""

Gets the query parameters

use Josantonius\Url\Url;

$url = new Url(); // https://domain.com/en?tag=bug&order=asc#top

$url->parameters; // ["tag" => "bug", "order" => "asc"]


$url = new Url('https://domain.com/en/web/docs/search.php');

$url->parameters; // ""

Gets password

use Josantonius\Url\Url;

$url = new Url(); // https://:[e-mail]

$url->password; // "pass"


$url = new Url('https://user:[e-mail]');

$url->password; // "pass"


$url = new Url('https://[e-mail]');

$url->password; // ""

Gets port

use Josantonius\Url\Url;

$url = new Url(); // https://domain.com:90

$url->port; // 90


$url = new Url(); // https://domain.com:80

$url->port; // ""


$url = new Url(); // https://domain.com:443

$url->port; // ""


$url = new Url('https://domain.com:80/en/');

$url->port; // 80


$url = new Url('https://domain.com:443/en/');

$url->port; // 443


$url = new Url('https://domain.com/en/');

$url->port; // ""

Gets scheme

use Josantonius\Url\Url;

$url = new Url(); // http://domain.com

$url->scheme; // "http"


$url = new Url('https://domain.com');

$url->scheme; // "https"

Gets path segments

use Josantonius\Url\Url;

$url = new Url(); // https://domain.com?tag=bug

$url->segments; // []


$url = new Url('https://domain.com/en/web/docs/search.php');

$url->segments; // ['en', 'web', 'docs', 'search.php']

Gets query

use Josantonius\Url\Url;

$url = new Url(); // https://domain.com?tag=bug

$url->query; // "tag=bug"


$url = new Url('https://domain.com?tag=bug&order=asc#top');

$url->query; // "tag=bug&order=asc"

$url = new Url('https://domain.com');

$url->query; // ""

Gets username

use Josantonius\Url\Url;

$url = new Url(); // https://[e-mail]

$url->username; // "user"


$url = new Url('https://:[e-mail]');

$url->username; // ""


$url = new Url('https://user:[e-mail]');

$url->username; // "user"


$url = new Url('https://domain.com');

$url->username; // ""

Tests

To run tests you just need composer and to execute the following:

git clone https://github.com/josantonius/php-url.git

cd php-url

composer install

Run unit tests with PHPUnit:

composer phpunit

Run code standard tests with PHPCS:

composer phpcs

Run PHP Mess Detector tests to detect inconsistencies in code style:

composer phpmd

Run all previous tests:

composer tests

TODO

• Add new feature
• Improve tests
• Improve documentation
• Improve English translation in the README file
• Refactor code for disabled code style rules (see phpmd.xml and phpcs.xml)

Changelog

Detailed changes for each release are documented in the release notes.

Contribution

Please make sure to read the Contributing Guide, before making a pull request, start a discussion or report a issue.

Thanks to all contributors! ❤️

Sponsor

If this project helps you to reduce your development time, you can sponsor me to support my open source work 😊

License

This repository is licensed under the MIT License.

Copyright © 2017-present, Josantonius