Kit UrlParser
Version 2.2.0
UrlParser adalah pustaka PHP yang menyediakan pengurai URL yang sesuai dengan RFC 3986 dan komponen URI yang kompatibel dengan PSR-7. Tujuan dari perpustakaan ini adalah untuk menyediakan parser yang secara akurat mengimplementasikan spesifikasi RFC tidak seperti fungsi bawaan parse_url() , yang berbeda dari spesifikasi dalam beberapa hal yang halus.
Perpustakaan ini memiliki dua tujuan utama. Yang pertama memberikan informasi dari URL yang diurai. Untuk mencapai hal ini, perpustakaan mengimplementasikan antarmuka penanganan URI standar dari PSR-7 dan juga menyediakan metode tambahan yang memudahkan untuk mengambil informasi yang umum digunakan dari URL. Tujuan kedua adalah juga mengizinkan modifikasi URL tersebut menggunakan antarmuka dari standar PSR-7 selain beberapa metode tambahan yang membuat beberapa tugas lebih mudah.
Meskipun perpustakaan ini terutama ditujukan untuk penguraian URL, penguraiannya hanya didasarkan pada sintaksis URI umum. Dengan demikian, perpustakaan ini dapat digunakan untuk memvalidasi dan mengurai jenis URI lainnya terhadap sintaksis umum. Perpustakaan tidak melakukan validasi khusus skema apa pun untuk URL.
Selain mode default yang sesuai dengan RFC 3986, perpustakaan juga menawarkan opsi yang memungkinkan penguraian URL yang berisi karakter UTF-8 di berbagai komponen URL sambil mengonversinya ke format persen yang disandikan dan IDN ascii yang sesuai.
Dokumentasi API tersedia di: http://kit.riimu.net/api/urlparser/
^1.0 )intl (hanya diperlukan dukungan IDN) Cara termudah untuk menginstal perpustakaan ini adalah dengan menggunakan Komposer untuk menangani dependensi Anda. Untuk menginstal perpustakaan ini melalui Komposer, cukup ikuti dua langkah berikut:
Dapatkan composer.phar dengan menjalankan instalasi baris perintah Composer di root proyek Anda.
Setelah Anda menjalankan skrip instalasi, Anda harus memiliki file composer.phar di root proyek Anda dan Anda dapat menjalankan perintah berikut:
php composer.phar require "riimu/kit-urlparser:^2.1"
Setelah menginstal perpustakaan ini melalui Komposer, Anda dapat memuat perpustakaan dengan menyertakan file vendor/autoload.php yang dihasilkan oleh Komposer selama instalasi.
Jika Anda sudah familiar dengan cara menggunakan Composer, Anda dapat menambahkan perpustakaan sebagai dependensi dengan menambahkan file composer.json berikut ke proyek Anda dan menjalankan perintah composer install :
{
"require" : {
"riimu/kit-urlparser" : " ^2.1 "
}
} Jika Anda tidak ingin menggunakan Komposer untuk memuat pustaka, Anda juga dapat mengunduh pustaka secara manual dengan mengunduh rilis terbaru dan mengekstrak folder src ke proyek Anda. Anda kemudian dapat memasukkan file src/autoload.php yang disediakan untuk memuat kelas perpustakaan.
Harap dicatat bahwa menggunakan Komposer juga akan secara otomatis mengunduh pustaka PHP lain yang diperlukan. Jika Anda menginstal perpustakaan ini secara manual, Anda juga perlu menyediakan perpustakaan lain yang diperlukan tersebut.
Menggunakan perpustakaan ini relatif mudah. Pustaka menyediakan kelas penguraian URL UriParser dan kelas objek nilai tetap Uri yang mewakili URL. Untuk mengurai URL, Anda cukup memberikan URL sebagai string ke metode parse() di UriParser yang mengembalikan instance Uri yang telah dihasilkan dari URL yang diurai.
Misalnya:
<?php
require ' vendor/autoload.php ' ;
$ parser = new Riimu Kit UrlParser UriParser ();
$ uri = $ parser -> parse ( ' http://www.example.com ' );
echo $ uri -> getHost (); // Outputs 'www.example.com' Alternatifnya, Anda dapat melewatkan penggunaan UriParser sepenuhnya dan cukup memberikan URL sebagai parameter konstruktor ke Uri :
<?php
require ' vendor/autoload.php ' ;
$ uri = new Riimu Kit UrlParser Uri ( ' http://www.example.com ' );
echo $ uri -> getHost (); // Outputs 'www.example.com' Perbedaan utama antara penggunaan metode parse() dan konstruktor adalah metode parse() akan mengembalikan null jika URL yang diberikan bukan url yang valid, sedangkan konstruktor akan menampilkan InvalidArgumentException .
Untuk mengambil berbagai jenis informasi dari URL, kelas Uri menyediakan berbagai metode berbeda untuk membantu Anda. Berikut adalah contoh sederhana sebagai ikhtisar berbagai metode yang tersedia:
<?php
require ' vendor/autoload.php ' ;
$ parser = new Riimu Kit UrlParser UriParser ();
$ uri = $ parser -> parse ( ' http://jane:[email protected]:8080/site/index.php?action=login&prev=index#form ' );
echo $ uri -> getScheme () . PHP_EOL ; // outputs: http
echo $ uri -> getUsername () . PHP_EOL ; // outputs: jane
echo $ uri -> getPassword () . PHP_EOL ; // outputs: pass123
echo $ uri -> getHost () . PHP_EOL ; // outputs: www.example.com
echo $ uri -> getTopLevelDomain () . PHP_EOL ; // outputs: com
echo $ uri -> getPort () . PHP_EOL ; // outputs: 8080
echo $ uri -> getStandardPort () . PHP_EOL ; // outputs: 80
echo $ uri -> getPath () . PHP_EOL ; // outputs: /site/index.php
echo $ uri -> getPathExtension () . PHP_EOL ; // outputs: php
echo $ uri -> getQuery () . PHP_EOL ; // outputs: action=login&prev=index
echo $ uri -> getFragment () . PHP_EOL ; // outputs: form
print_r ( $ uri -> getPathSegments ()); // [0 => 'site', 1 => 'index.php']
print_r ( $ uri -> getQueryParameters ()); // ['action' => 'login', 'prev' => 'index'] Komponen Uri juga menyediakan berbagai metode untuk memodifikasi URL, yang memungkinkan Anda membuat URL baru dari komponen terpisah atau memodifikasi yang sudah ada. Perhatikan bahwa komponen Uri adalah objek nilai yang tidak dapat diubah, yang berarti bahwa setiap metode modifikasi akan mengembalikan instance Uri baru alih-alih memodifikasi instance Uri yang sudah ada. Berikut adalah contoh sederhana pembuatan URL dari komponennya:
<?php
require ' vendor/autoload.php ' ;
$ uri = ( new Riimu Kit UrlParser Uri ())
-> withScheme ( ' http ' )
-> withUserInfo ( ' jane ' , ' pass123 ' )
-> withHost ( ' www.example.com ' )
-> withPort ( 8080 )
-> withPath ( ' /site/index.php ' )
-> withQueryParameters ([ ' action ' => ' login ' , ' prev ' => ' index ' ])
-> withFragment ( ' form ' );
// Outputs: http://jane:[email protected]:8080/site/index.php?action=login&prev=index#form
echo $ uri ; Seperti terlihat pada contoh sebelumnya, komponen Uri juga menyediakan metode __toString() yang menyediakan URL sebagai string.
Berikut daftar metode yang disediakan komponen Uri untuk mengambil informasi dari URL:
getScheme() mengembalikan skema dari URL atau string kosong jika URL tidak memiliki skema.
getAuthority() mengembalikan komponen dari URL yang terdiri dari nama pengguna, kata sandi, nama host dan port dalam format user-info@hostname:port
getUserInfo() mengembalikan komponen dari URL yang berisi nama pengguna dan kata sandi yang dipisahkan oleh titik dua.
getUsername() mengembalikan nama pengguna yang didekodekan dari URL atau string kosong jika tidak ada nama pengguna di URL.
getPassword() mengembalikan kata sandi yang didekodekan dari URL atau string kosong jika tidak ada kata sandi di URL.
getHost() mengembalikan nama host dari URL atau string kosong jika URL tidak memiliki host.
getIpAddress() mengembalikan alamat IP dari host, jika host adalah alamat IP. Kalau tidak, metode ini akan mengembalikan null . Jika alamat IPv6 diberikan, alamat dikembalikan tanpa tanda kurung kurawal di sekitarnya.
getTopLevelDomain() mengembalikan domain tingkat teratas dari host. Jika tidak ada host atau host adalah alamat IP, string kosong akan dikembalikan.
getPort() mengembalikan port dari URL atau null jika tidak ada port di url. Metode ini juga akan mengembalikan null jika port tersebut adalah port standar untuk skema saat ini (misalnya 80 untuk http).
getStandardPort() mengembalikan port standar untuk skema saat ini. Jika tidak ada skema atau port standar untuk skema tersebut tidak diketahui, null akan dikembalikan.
getPath() mengembalikan jalur dari URL atau string kosong jika URL tidak memiliki jalur.
getPathSegments() mengembalikan array segmen jalur yang didekodekan (yaitu jalur yang dipisahkan oleh setiap garis miring). Segmen jalur yang kosong akan dibuang dan tidak disertakan dalam larik yang dikembalikan.
getPathExtension() mengembalikan ekstensi file dari jalur atau string kosong jika URL tidak memiliki jalur.
getQuery() mengembalikan string kueri dari URL atau string kosong jika URL tidak memiliki string kueri.
getQueryParameters() mem-parsing string kueri dari URL menggunakan fungsi parse_str() dan mengembalikan array nilai yang diurai.
getFragment() mengembalikan fragmen dari URL atau string kosong jika URL tidak memiliki fragmen.
__toString() mengembalikan URL sebagai string.
Komponen Uri menyediakan berbagai metode yang dapat digunakan untuk mengubah URL dan membuat URL baru. Perhatikan bahwa karena kelas Uri adalah objek nilai yang tidak dapat diubah, setiap metode mengembalikan instance Uri baru daripada memodifikasi instance Uri yang sudah ada.
withScheme($scheme) mengembalikan instance baru dengan skema yang diberikan. Skema kosong dapat digunakan untuk menghapus skema dari URL. Perhatikan bahwa skema apa pun yang disediakan dinormalisasi menjadi huruf kecil.
withUserInfo($user, $password = null) mengembalikan instance baru dengan nama pengguna dan kata sandi yang diberikan. Perhatikan bahwa kata sandi diabaikan kecuali nama pengguna diberikan. Nama pengguna yang kosong dapat digunakan untuk menghapus nama pengguna dan kata sandi dari URL. Karakter apa pun yang tidak dapat dimasukkan ke dalam URL dengan sendirinya akan dikodekan persen.
withHost($host) mengembalikan instance baru dengan host yang diberikan. Host kosong dapat digunakan untuk menghapus host dari URL. Perhatikan bahwa metode ini tidak menerima nama domain internasional. Perhatikan bahwa metode ini juga akan menormalkan host menjadi huruf kecil.
withPort($port) mengembalikan instance baru dengan port yang diberikan. null dapat digunakan untuk menghapus port dari URL.
withPath($path) mengembalikan instance baru dengan jalur yang diberikan. Jalur kosong dapat digunakan untuk menghapus jalur dari URL. Perhatikan bahwa karakter apa pun yang bukan karakter jalur yang valid akan dikodekan persennya dalam URL. Namun, persen karakter yang dikodekan tidak akan dikodekan ganda.
withPathSegments(array $segments) mengembalikan instance baru dengan jalur yang dibuat dari larik segmen jalur. Semua karakter jalur yang tidak valid dalam segmen akan diberi kode persen, termasuk garis miring dan karakter persen yang sudah ada.
withQuery($query) mengembalikan instance baru dengan string kueri yang diberikan. String kueri kosong dapat digunakan untuk menghapus jalur dari URL. Perhatikan bahwa karakter apa pun yang bukan karakter string kueri yang valid akan dikodekan persennya dalam URL. Namun, persen karakter yang dikodekan tidak akan dikodekan ganda.
withQueryParameters(array $parameters) mengembalikan instance baru dengan string kueri yang dibuat dari parameter yang disediakan menggunakan fungsi http_build_query() . Semua karakter string kueri yang tidak valid dalam parameter akan dikodekan persen, termasuk ampersand, tanda sama dengan, dan karakter persen yang dikodekan.
withFragment($fragment) mengembalikan instance baru dengan fragmen yang diberikan. String kosong dapat digunakan untuk menghapus fragmen dari URL. Perhatikan bahwa karakter apa pun yang bukan karakter fragmen yang valid akan dikodekan persennya dalam URL. Namun, persen karakter yang dikodekan tidak akan dikodekan ganda.
Secara default, perpustakaan ini menyediakan parser yang sesuai dengan RFC 3986. Spesifikasi RFC tidak mengizinkan penggunaan karakter UTF-8 pada nama domain atau bagian lain dari URL. Representasi yang benar untuk ini di URL adalah dengan menggunakan standar IDN untuk nama domain dan persen pengkodean karakter UTF-8 di bagian lain.
Namun, untuk membantu Anda menangani karakter yang dikodekan UTF-8, banyak metode dalam komponen Uri yang akan secara otomatis mengkodekan persen karakter apa pun yang tidak dapat dimasukkan ke dalam URL sendiri, termasuk karakter UTF-8. Namun, karena kerumitannya, metode withHost() tidak mengizinkan karakter yang dikodekan UTF-8.
Secara default, parser juga tidak mengurai URL apa pun yang menyertakan karakter berkode UTF-8 karena hal tersebut melanggar spesifikasi RFC. Namun, parser menyediakan dua mode parsing tambahan yang memungkinkan karakter ini bila memungkinkan.
Jika Anda ingin mengurai URL yang mungkin berisi karakter UTF-8 dalam informasi pengguna (yaitu nama pengguna atau kata sandi), jalur, kueri, atau komponen fragmen URL, Anda cukup menggunakan mode penguraian UTF-8. Misalnya:
<?php
require ' vendor/autoload.php ' ;
$ parser = new Riimu Kit UrlParser UriParser ();
$ parser -> setMode ( Riimu Kit UrlParser UriParser:: MODE_UTF8 );
$ uri = $ parser -> parse ( ' http://www.example.com/föö/bär.html ' );
echo $ uri -> getPath (); // Outputs: /f%C3%B6%C3%B6/b%C3%A4r.htmlNamun, karakter UTF-8 dalam nama domain merupakan masalah yang sedikit lebih rumit. Namun, parser menyediakan dukungan dasar untuk mengurai nama domain ini menggunakan mode IDNA. Misalnya:
<?php
require ' vendor/autoload.php ' ;
$ parser = new Riimu Kit UrlParser UriParser ();
$ parser -> setMode ( Riimu Kit UrlParser UriParser:: MODE_IDNA );
$ uri = $ parser -> parse ( ' http://www.fööbär.com ' );
echo $ uri -> getHost (); // Outputs: www.xn--fbr-rla2ga.com Perhatikan bahwa menggunakan mode parsing ini memerlukan ekstensi PHP intl untuk diaktifkan. Mode penguraian yang sesuai juga dapat diberikan ke konstruktor komponen Uri menggunakan parameter konstruktor kedua.
Meskipun dukungan untuk penguraian karakter UTF-8 ini tersedia, pustaka ini tidak menyediakan metode apa pun untuk operasi sebaliknya karena tujuan pustaka ini adalah menangani URI yang sesuai dengan RFC 3986.
Karena fakta bahwa spesifikasi RFC 3986 mendefinisikan beberapa URL sebagai setara meskipun memiliki sedikit perbedaan, perpustakaan ini melakukan normalisasi minimal terhadap nilai yang diberikan. Anda mungkin mengalami kejadian ini ketika, misalnya, mengurai URL yang disediakan oleh pengguna. Normalisasi paling menonjol yang mungkin Anda temui adalah sebagai berikut:
scheme dan komponen host dianggap tidak peka huruf besar-kecil. Dengan demikian, komponen ini akan selalu dinormalisasi menjadi huruf kecil.getAuthority() dan __toString() jika port tersebut adalah port standar untuk skema saat ini.__toString() dapat berubah bergantung pada apakah URL memiliki komponen authority atau tidak.userinfo mungkin berbeda karena fakta bahwa UriParser bekerja dengan spesifikasi PSR-7 yang tidak menyediakan cara untuk memberikan nama pengguna atau kata sandi yang disandikan. Perpustakaan ini adalah Hak Cipta (c) 2013-2022 Riikka Kalliomäki.
Lihat LISENSI untuk informasi lisensi dan penyalinan.
