README

Urling

🌐 Документация на русском → | Документація на українській →

⚙️ Installation

To install this library - run the command below in your terminal:

composer require ismaxim/urling

🧙 Usage

📖 Concept

Three major ideas

📗 1. Two modes to work with URL: parser mode & constructor mode.
📘 2. Accessing to concrete part of URL with using aliases (see ACCESSING TABLE, column Aliases).
📙 3. Base editors for processing complete URL and each part separately (see section Basic usage).

🚀 Start

# Url parser mode

use Urling\Urling;

$urling = new Urling("https://github.com/ismaxim/urling#start");

$url_part_values = [
    "protocol_value" => $urling->url->protocol->get(),
    "domain_value"   => $urling->url->domain->get(),
    "routes_value"   => $urling->url->routes->get(),
    "anchor_value"   => $urling->url->anchor->get(),
];

print_r($url_part_values);

/* 
    RESULT: 

    [
        "protocol_value" => "https",
        "domain_value"   => "github.com",
        "routes_value"   => "ismaxim/urling",
        "anchor_value"   => "start",
    ] 
*/

# Url constructor mode

use Urling\Urling;
        
$urling = new Urling();

$urling->url->construct([
    "protocol" => "https",
    "domain"   => "github.com",
    "routes"   => "ismaxim/urling",
    "anchor"   => "start",
]);

// Either you can set the value for each distinct part 
// in the url by accessing it directly, for example:

$urling->url->protocol->add("https");
$urling->url->domain->add("github.com");
$urling->url->routes->add("ismaxim/urling");
$urling->url->anchor->add("start");

print_r($urling->url->get());

/* 
    RESULT:
    
    "https://github.com/ismaxim/urling#start"
*/

🔑 Accessing

You can access to concrete URL part to parse it by using its basename (see ACCESSING TABLE, column Url Part) or ask for its alias (see ACCESSING TABLE, column Aliases) like:

$urling->url->scheme->... | $urling->url->protocol->... (other parts of url in a similar way).

ACCESSING TABLE

Url Part	Aliases	Parser
scheme	protocol	SchemeParser
user	username	UserParser
pass	password	PassParser
host	hostname, domain	HostParser
port		PortParser
path	routes	PathParser
query	params, attributes	QueryParser
fragment	anchor	FragmetParser

👶 Basic usage

Basic Editors - Base editor of URL and Base editor of part of URL cover almost all tasks: add, get, update or remove URL or values anywhere in it. Base Editors are "CRUDable" wrappers over the parse_url() function from native PHP, and according to this fact, they return and modify values in a similar way. The only significant difference is the syntax of calls when parsing a URL or its parts.

// Working with URL

$urling->url->add();
$urling->url->get();
$urling->url->update();
$urling->url->delete();

// Working with one of the URL parts

$urling->url->scheme->add();
$urling->url->scheme->get();
$urling->url->scheme->update();
$urling->url->scheme->delete();

// For example, let's imagine that the URL is: https://github.com/ismaxim/urling#basic-usage
// Then example workflow to parse this URL in part of "scheme" or "protocol" (see ACCESSING TABLE, column "Aliases") will seem to this:

$urling->url->scheme->get();          # returns "https" (state of URL: https://github.com/ismaxim/urling#basic-usage)
$urling->url->scheme->delete();       # returns null    (state of URL: github.com/ismaxim/urling#basic-usage)
$urling->url->scheme->add("ftp");     # returns "ftp"   (state of URL: ftp://github.com/ismaxim/urling#basic-usage)
$urling->url->scheme->update("smtp"); # returns "smtp"  (state of URL: smtp://github.com/ismaxim/urling#basic-usage)

// Work with other parts of URL can be done in a similar way.

🧔 Advanced usage

If you need to do something like add, get, update or delete the value of any part of the URL, but it's outside the scope of the base functionality, you can use one of the Base editors functions add, get, update or delete as a prefix with the name of a specific method as postfix appropriate for your task like:

(add, get, update, delete) + "SomeFunctionName" for the concrete task.

Note: Almost all functions will use that code convention permanently.

Examples:

getValueByName();
getNameValuePairs();
etc. ...

$urling->url->params->getValueByName();
$urling->url->params->getNameValuePairs();

🧪 Testing

Actually, all tests already automatically passed within CI build.

To test this library - run the command below in your terminal.

composer test

🤝 Contributing

If you have a problem that cannot be solved using this library, please write your solution and if you want to help other developers who also use this library (or if you want to keep your solution working after a new version is released, which will go to package manager dependencies) - create a pull-request. We will be happy to add your excellent code to the library!

🐞 Report any bugs or issues you find on the GitHub issues.

✨ Creating custom functional

You can extend the functionality of the library with your own code, making edits to solve your problems in the parser classes. There are two types of parser classes the first and the main is URL parser, but there are others as well, - URL parts parsers. For each part is separate own parser.

Using the library or examining docs you can notice the same or similar to this record:

$urling->url->params->get()

This entry might interpret the next way: "Hey, Urling, ask to the part 'params' on the current URL and return it value(this part)".

Basically extending functionality, you will work with a part of the URL almost all times and will processing or get the value for a specific part. To understand how to access to parser for needed part you can look at ACCESSING TABLE. You only need to match the url part and aliases sections with the parser section, and then go to the desired parser file and write the best code in the world!

📎 Credits

📃 License

The MIT License (MIT). Please see License File for more information.

ismaxim / urling

Maintainers

Details