Εργασία με URLs

Οι κλάσεις Url, UrlImmutable και UrlScript επιτρέπουν την εύκολη δημιουργία, ανάλυση και χειρισμό URLs.

→ Εγκατάσταση και απαιτήσεις

Url

Η κλάση Nette\Http\Url επιτρέπει την εύκολη εργασία με URLs και τα μεμονωμένα συστατικά τους, τα οποία αποτυπώνονται σε αυτό το διάγραμμα:

scheme  user  password  host   port    path        query  fragment
  |      |      |        |      |       |            |       |
/--\   /--\ /------\ /-------\ /--\/----------\ /--------\ /----\
http://john:xyz%2A12@nette.org:8080/en/download?name=param#footer
\______\__________________________/
    |               |
 hostUrl        authority

Η δημιουργία URLs είναι διαισθητική:

use Nette\Http\Url;

$url = new Url;
$url->setScheme('https')
	->setHost('localhost')
	->setPath('/edit')
	->setQueryParameter('foo', 'bar');

echo $url; // 'https://localhost/edit?foo=bar'

Μπορείτε επίσης να αναλύσετε ένα URL και να το χειριστείτε περαιτέρω:

$url = new Url(
	'http://john:xyz%2A12@nette.org:8080/en/download?name=param#footer',
);

Η κλάση Url υλοποιεί τη διεπαφή JsonSerializable και έχει μια μέθοδο __toString(), οπότε το αντικείμενο μπορεί να εκτυπωθεί ή να χρησιμοποιηθεί σε δεδομένα που περνούν στο json_encode().

echo $url;
echo json_encode([$url]);

Συστατικά URL

Για την επιστροφή ή την αλλαγή μεμονωμένων συστατικών του URL, είναι διαθέσιμες οι ακόλουθες μέθοδοι:

Προειδοποίηση: Όταν εργάζεστε με ένα URL που λαμβάνεται από ένα αίτημα HTTP, λάβετε υπόψη ότι δεν θα περιέχει το fragment, καθώς ο περιηγητής δεν το στέλνει στον διακομιστή.

Μπορούμε επίσης να εργαστούμε με μεμονωμένες παραμέτρους query χρησιμοποιώντας:

getDomain(int $level = 2): string

Επιστρέφει το δεξί ή το αριστερό τμήμα του host. Λειτουργεί ως εξής εάν ο host είναι www.nette.org:

isEqual(string|Url $anotherUrl): bool

Επαληθεύει εάν δύο URLs είναι πανομοιότυπα.

$url->isEqual('https://nette.org');

Url::isAbsolute(string $url): bool

Επαληθεύει εάν ένα URL είναι απόλυτο. Ένα URL θεωρείται απόλυτο εάν ξεκινά με ένα σχήμα (π.χ. http, https, ftp) ακολουθούμενο από άνω και κάτω τελεία.

Url::isAbsolute('https://nette.org');    // true
Url::isAbsolute('//nette.org');          // false

Url::removeDotSegments(string $path): string

Κανονικοποιεί τη διαδρομή σε ένα URL αφαιρώντας τα ειδικά τμήματα . και ... Η μέθοδος αφαιρεί τα περιττά στοιχεία διαδρομής με τον ίδιο τρόπο που το κάνουν οι περιηγητές ιστού.

Url::removeDotSegments('/path/../subtree/./file.txt');  // '/subtree/file.txt'
Url::removeDotSegments('/../foo/./bar');                // '/foo/bar'
Url::removeDotSegments('./today/../file.txt');          // 'file.txt'

UrlImmutable

Η κλάση Nette\Http\UrlImmutable είναι μια αμετάβλητη (immutable) εναλλακτική της κλάσης Url (παρόμοια με το πώς το DateTimeImmutable είναι η αμετάβλητη εναλλακτική του DateTime στην PHP). Αντί για setters, έχει τους λεγόμενους withers, οι οποίοι δεν αλλάζουν το αντικείμενο, αλλά επιστρέφουν νέες παρουσίες με την τροποποιημένη τιμή:

use Nette\Http\UrlImmutable;

$url = new UrlImmutable(
	'http://john:xyz%2A12@nette.org:8080/en/download?name=param#footer',
);

$newUrl = $url
	->withUser('')
	->withPassword('')
	->withPath('/cs/');

echo $newUrl; // 'http://john:xyz%2A12@nette.org:8080/cs/?name=param#footer'

Η κλάση UrlImmutable υλοποιεί τη διεπαφή JsonSerializable και έχει μια μέθοδο __toString(), οπότε το αντικείμενο μπορεί να εκτυπωθεί ή να χρησιμοποιηθεί σε δεδομένα που περνούν στο json_encode().

echo $url;
echo json_encode([$url]);

Συστατικά URL

Για την επιστροφή ή την αλλαγή μεμονωμένων συστατικών του URL, χρησιμοποιούνται οι ακόλουθες μέθοδοι:

Η μέθοδος withoutUserInfo() αφαιρεί τα user και password.

Μπορούμε επίσης να εργαστούμε με μεμονωμένες παραμέτρους query χρησιμοποιώντας:

getDomain(int $level = 2): string

Επιστρέφει το δεξί ή το αριστερό τμήμα του host. Λειτουργεί ως εξής εάν ο host είναι www.nette.org:

resolve(string $reference): UrlImmutable

Παράγει ένα απόλυτο URL με τον ίδιο τρόπο που ένας περιηγητής επεξεργάζεται συνδέσμους σε μια σελίδα HTML:

• εάν ο σύνδεσμος είναι ένα απόλυτο URL (περιέχει σχήμα), χρησιμοποιείται αμετάβλητος
• εάν ο σύνδεσμος ξεκινά με //, λαμβάνεται μόνο το σχήμα από το τρέχον URL
• εάν ο σύνδεσμος ξεκινά με /, δημιουργείται μια απόλυτη διαδρομή από τη ρίζα του domain
• σε άλλες περιπτώσεις, το URL δημιουργείται σχετικά με την τρέχουσα διαδρομή

$url = new UrlImmutable('https://example.com/path/page');
echo $url->resolve('../foo');           // 'https://example.com/foo'
echo $url->resolve('/bar');             // 'https://example.com/bar'
echo $url->resolve('sub/page.html');    // 'https://example.com/path/sub/page.html'

isEqual(string|Url $anotherUrl): bool

Επαληθεύει εάν δύο URLs είναι πανομοιότυπα.

$url->isEqual('https://nette.org');

UrlScript

Η κλάση Nette\Http\UrlScript είναι απόγονος του UrlImmutable και το επεκτείνει με πρόσθετα εικονικά συστατικά URL, όπως ο ριζικός κατάλογος του έργου κ.λπ. Όπως και η γονική κλάση, είναι ένα αμετάβλητο (immutable) αντικείμενο.

Το ακόλουθο διάγραμμα δείχνει τα συστατικά που αναγνωρίζει το UrlScript:

     baseUrl    basePath  relativePath  relativeUrl
        |          |        |               |
/---------------/-----\/--------\---------------------------\
http://nette.org/admin/script.php/pathinfo/?name=param#footer
                \_______________/\________/
                       |              |
                  scriptPath       pathInfo

• baseUrl είναι η βασική διεύθυνση URL της εφαρμογής, συμπεριλαμβανομένου του domain και του τμήματος της διαδρομής προς τον ριζικό κατάλογο της εφαρμογής
• basePath είναι το τμήμα της διαδρομής προς τον ριζικό κατάλογο της εφαρμογής
• scriptPath είναι η διαδρομή προς το τρέχον σενάριο
• relativePath είναι το όνομα του σεναρίου (και ενδεχομένως περαιτέρω τμήματα διαδρομής) σχετικά με το basePath
• relativeUrl είναι ολόκληρο το τμήμα του URL μετά το baseUrl, συμπεριλαμβανομένης της συμβολοσειράς query και του fragment.
• pathInfo είναι ένα τμήμα του URL που χρησιμοποιείται σπάνια σήμερα, μετά το όνομα του σεναρίου

Για την επιστροφή τμημάτων του URL, είναι διαθέσιμες οι ακόλουθες μέθοδοι:

Συνήθως δεν δημιουργούμε απευθείας αντικείμενα UrlScript, αλλά η μέθοδος Nette\Http\Request::getUrl() τα επιστρέφει με τα συστατικά ήδη σωστά ρυθμισμένα για το τρέχον αίτημα HTTP.