Kit UrlParser
Version 2.2.0
UrlParser هي مكتبة PHP توفر محلل URL متوافقًا مع RFC 3986 ومكون URI متوافقًا مع PSR-7. الغرض من هذه المكتبة هو توفير محلل ينفذ بدقة مواصفات RFC على عكس الوظيفة المضمنة parse_url() ، والتي تختلف عن المواصفات في بعض الطرق الدقيقة.
هذه المكتبة لها غرضين رئيسيين. أول من قدم معلومات من عناوين URL التي تم تحليلها. ولتحقيق ذلك، تطبق المكتبة واجهة التعامل مع URI القياسية من PSR-7 وتوفر أيضًا طرقًا إضافية تسهل استرداد المعلومات شائعة الاستخدام من عناوين URL. والغرض الثاني هو السماح أيضًا بتعديل عناوين URL المذكورة باستخدام الواجهة من معيار PSR-7 بالإضافة إلى بعض الطرق الإضافية التي تجعل بعض المهام أكثر وضوحًا.
في حين أن هذه المكتبة مخصصة بشكل أساسي لتحليل عناوين URL، فإن التحليل يعتمد ببساطة على بناء جملة URI العام. وبالتالي، من الممكن استخدام هذه المكتبة للتحقق من صحة وتحليل أي أنواع أخرى من عناوين URI مقابل بناء الجملة العام. لا تقوم المكتبة بإجراء أي عملية تحقق محددة من صحة عناوين URL.
بالإضافة إلى الوضع الافتراضي المتوافق مع RFC 3986، توفر المكتبة أيضًا خيارات تسمح بتحليل عناوين URL التي تحتوي على أحرف UTF-8 في مكونات مختلفة لعنوان URL أثناء تحويلها إلى النسبة المئوية المناسبة المشفرة وتنسيقات IDN ascii.
وثائق واجهة برمجة التطبيقات متاحة على: http://kit.riimu.net/api/urlparser/
^1.0 )intl (دعم IDN المطلوب فقط) أسهل طريقة لتثبيت هذه المكتبة هي استخدام Composer للتعامل مع تبعياتك. لتثبيت هذه المكتبة عبر Composer، ما عليك سوى اتباع الخطوتين التاليتين:
احصل على composer.phar عن طريق تشغيل تثبيت سطر أوامر Composer في جذر مشروعك.
بمجرد تشغيل البرنامج النصي للتثبيت، يجب أن يكون لديك ملف composer.phar في جذر المشروع الخاص بك ويمكنك تشغيل الأمر التالي:
php composer.phar require "riimu/kit-urlparser:^2.1"
بعد تثبيت هذه المكتبة عبر Composer، يمكنك تحميل المكتبة عن طريق تضمين ملف vendor/autoload.php الذي تم إنشاؤه بواسطة Composer أثناء التثبيت.
إذا كنت على دراية بكيفية استخدام Composer، فيمكنك بدلاً من ذلك إضافة المكتبة باعتبارها تبعية عن طريق إضافة ملف composer.json التالي إلى مشروعك وتشغيل أمر composer install :
{
"require" : {
"riimu/kit-urlparser" : " ^2.1 "
}
} إذا كنت لا ترغب في استخدام Composer لتحميل المكتبة، فيمكنك أيضًا تنزيل المكتبة يدويًا عن طريق تنزيل أحدث إصدار واستخراج المجلد src إلى مشروعك. يمكنك بعد ذلك تضمين ملف src/autoload.php المتوفر لتحميل فئات المكتبة.
يرجى ملاحظة أن استخدام Composer سيؤدي أيضًا إلى تنزيل مكتبات PHP الأخرى المطلوبة تلقائيًا. إذا قمت بتثبيت هذه المكتبة يدويًا، فستحتاج أيضًا إلى إتاحة تلك المكتبات الأخرى المطلوبة.
يعد استخدام هذه المكتبة أمرًا سهلاً نسبيًا. توفر المكتبة فئة تحليل URL UriParser وفئة كائن ذات قيمة ثابتة Uri تمثل عنوان URL. لتحليل عنوان URL، يمكنك ببساطة توفير عنوان URL كسلسلة إلى الأسلوب parse() في UriParser الذي يُرجع مثيل Uri الذي تم إنشاؤه من عنوان URL الذي تم تحليله.
على سبيل المثال:
<?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' وبدلاً من ذلك، يمكنك فقط تخطي استخدام UriParser تمامًا وتوفير عنوان URL كمعلمة منشئة لـ Uri :
<?php
require ' vendor/autoload.php ' ;
$ uri = new Riimu Kit UrlParser Uri ( ' http://www.example.com ' );
echo $ uri -> getHost (); // Outputs 'www.example.com' يتمثل الاختلاف الرئيسي بين استخدام طريقة parse() والمنشئ في أن طريقة parse() ستعيد قيمة null إذا كان عنوان URL المقدم ليس عنوان url صالحًا، بينما سيطرح المُنشئ InvalidArgumentException .
لاسترداد أنواع مختلفة من المعلومات من عنوان URL، توفر فئة Uri طرقًا مختلفة ومتنوعة لمساعدتك. فيما يلي مثال بسيط كنظرة عامة على الطرق المختلفة المتاحة:
<?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'] يوفر مكون Uri أيضًا طرقًا مختلفة لتعديل عنوان URL، مما يسمح لك بإنشاء عناوين URL جديدة من مكونات منفصلة أو تعديل المكونات الموجودة. لاحظ أن مكون Uri هو كائن ذو قيمة غير قابلة للتغيير، مما يعني أن كل طريقة من طرق التعديل تقوم بإرجاع مثيل Uri جديد بدلاً من تعديل الموجود. فيما يلي مثال بسيط لإنشاء عنوان URL من مكوناته:
<?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 ; كما يتبين من المثال السابق، يوفر مكون Uri أيضًا طريقة __toString() التي توفر عنوان URL كسلسلة.
فيما يلي قائمة الأساليب التي يوفرها مكون Uri لاسترداد المعلومات من عنوان URL:
تقوم getScheme() بإرجاع المخطط من عنوان URL أو سلسلة فارغة إذا كان عنوان URL لا يحتوي على مخطط.
getAuthority() بإرجاع المكون من عنوان URL الذي يتكون من اسم المستخدم وكلمة المرور واسم المضيف والمنفذ بالتنسيق user-info@hostname:port
تقوم getUserInfo() بإرجاع المكون من عنوان URL الذي يحتوي على اسم المستخدم وكلمة المرور مفصولين بنقطتين.
تقوم getUsername() بإرجاع اسم المستخدم الذي تم فك تشفيره من عنوان URL أو سلسلة فارغة في حالة عدم وجود اسم مستخدم في عنوان URL.
يقوم getPassword() بإرجاع كلمة المرور التي تم فك تشفيرها من عنوان URL أو سلسلة فارغة في حالة عدم وجود كلمة مرور في عنوان URL.
getHost() بإرجاع اسم المضيف من عنوان URL أو سلسلة فارغة إذا كان عنوان URL لا يحتوي على مضيف.
تقوم getIpAddress() بإرجاع عنوان IP من المضيف، إذا كان المضيف عنوان IP. وإلا فإن هذه الطريقة ستعود null . إذا تم توفير عنوان IPv6، فسيتم إرجاع العنوان بدون الأقواس المحيطة به.
يقوم getTopLevelDomain() بإرجاع مجال المستوى الأعلى من المضيف. إذا لم يكن هناك مضيف أو كان المضيف عنوان IP، فسيتم إرجاع سلسلة فارغة بدلاً من ذلك.
getPort() بإرجاع المنفذ من عنوان URL أو null إذا لم يكن هناك منفذ موجود في عنوان url. ستقوم هذه الطريقة أيضًا بإرجاع قيمة null إذا كان المنفذ هو المنفذ القياسي للنظام الحالي (على سبيل المثال، 80 لـ http).
يقوم getStandardPort() بإرجاع المنفذ القياسي للنظام الحالي. إذا لم يكن هناك نظام أو كان المنفذ القياسي للنظام غير معروف، فسيتم إرجاع قيمة null بدلاً من ذلك.
يقوم getPath() بإرجاع المسار من عنوان URL أو سلسلة فارغة إذا لم يكن لعنوان URL مسار.
تقوم getPathSegments() بإرجاع مصفوفة من مقاطع المسار التي تم فك تشفيرها (أي المسار المقسم بواسطة كل شرطة مائلة للأمام). يتم تجاهل مقاطع المسار الفارغة ولا يتم تضمينها في المصفوفة التي تم إرجاعها.
يقوم getPathExtension() بإرجاع امتداد الملف من المسار أو سلسلة فارغة إذا لم يكن لعنوان URL مسار.
تقوم getQuery() بإرجاع سلسلة الاستعلام من عنوان URL أو سلسلة فارغة إذا كان عنوان URL لا يحتوي على سلسلة استعلام.
تقوم getQueryParameters() بتوزيع سلسلة الاستعلام من عنوان URL باستخدام الدالة parse_str() وإرجاع مصفوفة القيم التي تم تحليلها.
تقوم getFragment() بإرجاع الجزء من عنوان URL أو سلسلة فارغة إذا كان عنوان URL لا يحتوي على جزء.
__toString() تقوم بإرجاع عنوان URL كسلسلة.
يوفر مكون Uri طرقًا مختلفة يمكن استخدامها لتعديل عناوين URL وإنشاء عناوين جديدة. لاحظ أنه بما أن فئة Uri هي كائن ذو قيمة غير قابلة للتغيير، فإن كل طريقة تقوم بإرجاع مثيل جديد لـ Uri بدلاً من تعديل الموجود.
withScheme($scheme) يُرجع مثيلًا جديدًا بالمخطط المحدد. يمكن استخدام مخطط فارغ لإزالة المخطط من عنوان URL. لاحظ أنه يتم تطبيع أي مخطط مقدم إلى أحرف صغيرة.
withUserInfo($user, $password = null) يُرجع مثيلًا جديدًا باسم المستخدم وكلمة المرور المحددين. لاحظ أنه يتم تجاهل كلمة المرور ما لم يتم توفير اسم مستخدم. يمكن استخدام اسم مستخدم فارغ لإزالة اسم المستخدم وكلمة المرور من عنوان URL. سيتم ترميز أي حرف لا يمكن إدراجه في عنوان URL بمفرده بنسبة مئوية.
withHost($host) يُرجع مثيلًا جديدًا مع المضيف المحدد. يمكن استخدام مضيف فارغ لإزالة المضيف من عنوان URL. لاحظ أن هذه الطريقة لا تقبل أسماء النطاقات الدولية. لاحظ أن هذه الطريقة ستعمل أيضًا على تطبيع المضيف إلى أحرف صغيرة.
withPort($port) يُرجع مثيلًا جديدًا بالمنفذ المحدد. يمكن استخدام null لإزالة المنفذ من عنوان URL.
withPath($path) يُرجع مثيلًا جديدًا بالمسار المحدد. يمكن استخدام مسار فارغ لإزالة المسار من عنوان URL. لاحظ أن أي حرف ليس حرف مسار صالح سيتم ترميزه بنسبة مئوية في عنوان URL. ومع ذلك، لن يتم ترميز الأحرف المشفرة بنسبة مئوية موجودة بشكل مزدوج.
withPathSegments(array $segments) يُرجع مثيلًا جديدًا بالمسار الذي تم إنشاؤه من مجموعة مقاطع المسار. سيتم ترميز كافة أحرف المسار غير الصالحة في المقاطع بنسبة مئوية، بما في ذلك الشرطة المائلة للأمام والأحرف المشفرة بنسبة مئوية موجودة.
withQuery($query) يُرجع مثيلًا جديدًا بسلسلة الاستعلام المحددة. يمكن استخدام سلسلة استعلام فارغة لإزالة المسار من عنوان URL. لاحظ أن أي حرف ليس حرف سلسلة استعلام صالح سيتم ترميزه بنسبة مئوية في عنوان URL. ومع ذلك، لن يتم ترميز الأحرف المشفرة بنسبة مئوية موجودة بشكل مزدوج.
withQueryParameters(array $parameters) يُرجع مثيلًا جديدًا بسلسلة الاستعلام التي تم إنشاؤها من المعلمات المتوفرة باستخدام وظيفة http_build_query() . سيتم ترميز كافة أحرف سلسلة الاستعلام غير الصالحة في المعلمات بنسبة مئوية، بما في ذلك علامة العطف وعلامة المساواة والأحرف المشفرة بنسبة مئوية موجودة.
withFragment($fragment) تُرجع مثيلًا جديدًا بالجزء المحدد. يمكن استخدام سلسلة فارغة لإزالة الجزء من عنوان URL. لاحظ أن أي حرف ليس حرفًا مجزئًا صالحًا سيتم ترميزه بنسبة مئوية في عنوان URL. ومع ذلك، لن يتم ترميز الأحرف المشفرة بنسبة مئوية موجودة بشكل مزدوج.
بشكل افتراضي، توفر هذه المكتبة محللًا متوافقًا مع RFC 3986. لا تسمح مواصفات RFC باستخدام أحرف UTF-8 في اسم المجال أو أي أجزاء أخرى من عنوان URL. التمثيل الصحيح لها في عنوان URL هو استخدام معيار IDN لأسماء النطاقات والنسبة المئوية لترميز أحرف UTF-8 في أجزاء أخرى.
ومع ذلك، لمساعدتك في التعامل مع الأحرف المشفرة UTF-8، فإن العديد من الطرق في مكون Uri ستقوم تلقائيًا بتشفير أي أحرف لا يمكن إدراجها في عنوان URL بمفردها، بما في ذلك أحرف UTF-8. ومع ذلك، نظرًا للتعقيدات الموجودة، فإن طريقة withHost() لا تسمح بالأحرف المشفرة UTF-8.
افتراضيًا، لا يقوم المحلل اللغوي أيضًا بتحليل أي عناوين URL تتضمن أحرفًا مشفرة UTF-8 لأن ذلك سيكون مخالفًا لمواصفات RFC. ومع ذلك، يوفر المحلل اللغوي وضعي تحليل إضافيين يسمحان بهذه الأحرف كلما أمكن ذلك.
إذا كنت ترغب في تحليل عناوين URL التي قد تحتوي على أحرف UTF-8 في معلومات المستخدم (أي اسم المستخدم أو كلمة المرور) أو المسار أو الاستعلام أو مكونات جزء عنوان URL، فيمكنك ببساطة استخدام وضع التحليل UTF-8. على سبيل المثال:
<?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.htmlومع ذلك، تعد أحرف UTF-8 في اسم النطاق مشكلة أكثر تعقيدًا بعض الشيء. ومع ذلك، يوفر المحلل اللغوي دعمًا أوليًا لتحليل أسماء النطاقات هذه باستخدام وضع IDNA. على سبيل المثال:
<?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 لاحظ أن استخدام وضع التحليل هذا يتطلب تمكين ملحق PHP intl . يمكن أيضًا توفير وضع التحليل المناسب لمنشئ مكون Uri باستخدام معلمة المنشئ الثاني.
على الرغم من توفر الدعم لتحليل أحرف UTF-8 هذه، إلا أن هذه المكتبة لا توفر أي طرق للعمليات العكسية نظرًا لأن الغرض من هذه المكتبة هو التعامل مع عناوين URI المتوافقة مع RFC 3986.
نظرًا لأن مواصفات RFC 3986 تحدد بعض عناوين URL على أنها متكافئة على الرغم من وجود بعض الاختلافات الطفيفة، فإن هذه المكتبة تقوم ببعض التسوية البسيطة للقيم المقدمة. قد تواجه هذه الحالات، على سبيل المثال، عند تحليل عناوين URL المقدمة من قبل المستخدمين. أبرز عمليات التطبيع التي قد تواجهها هي كما يلي:
scheme host حساسة لحالة الأحرف. وبالتالي، سيتم دائمًا تطبيع هذه المكونات إلى أحرف صغيرة.getAuthority() و__ __toString() إذا كان المنفذ هو المنفذ القياسي للنظام الحالي.__toString() اعتمادًا على ما إذا كان عنوان URL يحتوي على مكون authority أم لا.userinfo نظرًا لحقيقة أن UriParser يعمل مع مواصفات PSR-7 التي لا توفر طريقة لتوفير اسم مستخدم أو كلمة مرور مشفرة. حقوق الطبع والنشر لهذه المكتبة (c) 2013-2022 محفوظة لـ Riikka Kalliomäki.
راجع الترخيص للحصول على معلومات الترخيص والنسخ.
