تنزيل Fuse - تنزيل كود مصدر Fuse

الصمامات

مكتبة بحث غامضة لـ PHP

هذا هو منفذ PHP لمشروع Fuse.js الرائع ويهدف إلى توفير التوافق الكامل مع واجهة برمجة التطبيقات حيثما أمكن ذلك.

تحقق من العرض التوضيحي والأمثلة الخاصة بهم للحصول على فكرة جيدة عما تستطيع هذه المكتبة القيام به.

أحدث إصدار متوافق من Fuse.js: 7.0.0

جدول المحتويات:

تثبيت
الاستخدام
خيارات
طُرق
الاختلافات مع Fuse.js
تطوير

تثبيت

هذه الحزمة متاحة عبر الملحن. لإضافته إلى مشروعك، فقط قم بتشغيل:

composer require loilo/fuse

لاحظ أنه يلزم وجود PHP 7.4 على الأقل لاستخدام Fuse.

الاستخدام

فيما يلي مثال بسيط للاستخدام:

 <?php
require_once ' vendor/autoload.php ' ;

$ list = [
    [
        ' title ' => " Old Man's War " ,
        ' author ' => ' John Scalzi ' ,
    ],
    [
        ' title ' => ' The Lock Artist ' ,
        ' author ' => ' Steve Hamilton ' ,
    ],
    [
        ' title ' => ' HTML5 ' ,
        ' author ' => ' Remy Sharp ' ,
    ],
    [
        ' title ' => ' Right Ho Jeeves ' ,
        ' author ' => ' P.D Woodhouse ' ,
    ],
];

$ options = [
    ' keys ' => [ ' title ' , ' author ' ],
];

$ fuse = new  Fuse  Fuse ( $ list , $ options );

$ fuse -> search ( ' hamil ' );

يؤدي هذا إلى النتائج التالية (حيث يشير item كل نتيجة إلى الإدخال المطابق نفسه ويوفر refIndex موضع العنصر في $list الأصلية):

[
    [
        ' item ' => [
            ' title ' => ' The Lock Artist ' ,
            ' author ' => ' Steve Hamilton ' ,
        ],
        ' refIndex ' => 1 ,
    ],
    [
        ' item ' => [
            ' title ' => ' HTML5 ' ,
            ' author ' => ' Remy Sharp ' ,
        ],
        ' refIndex ' => 2 ,
    ],
];

خيارات

يحتوي Fuse على الكثير من الخيارات لتحسين بحثك:

الخيارات الأساسية

`isCaseSensitive`

النوع: bool
الافتراضي: false

يشير إلى ما إذا كانت المقارنات يجب أن تكون حساسة لحالة الأحرف.

`includeScore`

النوع: bool
الافتراضي: false

ما إذا كان ينبغي تضمين النتيجة في مجموعة النتائج. تشير الدرجة 0 إلى تطابق تام، بينما تشير الدرجة 1 إلى عدم تطابق كامل.

`includeMatches`

النوع: bool
الافتراضي: false

ما إذا كان ينبغي تضمين المطابقات في مجموعة النتائج. عندما true ، سيتضمن كل سجل في مجموعة النتائج مؤشرات الأحرف المطابقة. وبالتالي يمكن استخدامها لتسليط الضوء على الأغراض.

`minMatchCharLength`

النوع: int
الافتراضي: 1

سيتم إرجاع التطابقات التي يتجاوز طولها هذه القيمة فقط. (على سبيل المثال، إذا كنت تريد تجاهل تطابقات الأحرف الفردية في النتيجة، فاضبطها على 2 ).

`shouldSort`

النوع: bool
الافتراضي: true

ما إذا كان سيتم فرز قائمة النتائج حسب النتيجة.

`findAllMatches`

النوع: bool
الافتراضي: false

عندما يكون صحيحًا، ستستمر وظيفة المطابقة حتى نهاية نمط البحث حتى لو تم بالفعل العثور على تطابق كامل في السلسلة.

`keys`

النوع: array
تقصير: []

قائمة المفاتيح التي سيتم البحث فيها. وهذا يدعم المسارات المتداخلة والبحث الموزون والبحث في صفائف السلاسل والكائنات.

خيارات المطابقة الغامضة

`location`

النوع: int
الافتراضي: 0

يحدد تقريبًا مكان النموذج المتوقع العثور عليه في النص.

`threshold`

النوع: float
الافتراضي: 0.6

في أي نقطة تتخلى خوارزمية المطابقة؟ يتطلب الحد الأدنى 0.0 تطابقًا تامًا (لكل من الحروف والموقع)، أما الحد الأدنى 1.0 فسيطابق أي شيء.

`distance`

النوع: int
الافتراضي: 100

يحدد مدى قرب المطابقة من الموقع الغامض (المحدد حسب location ). إن مطابقة الحروف distance التي تبعد الأحرف عن الموقع الغامض ستعتبر عدم تطابق كامل. تتطلب distance 0 أن تكون المطابقة في location المحدد بالضبط. تتطلب المسافة 1000 تطابقًا تامًا ضمن 800 حرف من location سيتم العثور عليه باستخدام threshold 0.8 .

`ignoreLocation`

النوع: bool
الافتراضي: false

عندما يكون true ، سيتجاهل البحث location distance ، لذلك لن يهم مكان ظهور النمط في السلسلة.

نصيحة: تبحث الخيارات الافتراضية فقط في أول 60 حرفًا. يجب أن يكون هذا كافيًا إذا كان من المتوقع بشكل معقول أن تكون المطابقة ضمن هذا النطاق. لتعديل هذا السلوك، قم بتعيين المجموعة المناسبة من location أو threshold أو distance (أو ignoreLocation ).
لفهم كيفية عمل هذه الخيارات معًا بشكل أفضل، اقرأ عن نظرية تسجيل النقاط الخاصة بـ Fuse.js.

خيارات متقدمة

`useExtendedSearch`

النوع: bool
الافتراضي: false

عندما يكون true ، فإنه يتيح استخدام أوامر البحث المشابهة لنظام التشغيل Unix. انظر المثال.

`getFn`

النوع: callable
الافتراضي: المصدر

الوظيفة التي سيتم استخدامها لاسترداد قيمة الكائن في المسار المقدم. سيقوم الإعداد الافتراضي أيضًا بالبحث في المسارات المتداخلة.

`sortFn`

النوع: callable
الافتراضي: المصدر

الوظيفة المستخدمة لفرز كافة النتائج. سيتم الفرز الافتراضي حسب درجة الملاءمة التصاعدية والفهرس التصاعدي.

`ignoreFieldNorm`

النوع: bool
الافتراضي: false

عندما يكون true ، فإن حساب درجة الملاءمة (المستخدمة للفرز) سوف يتجاهل معيار طول الحقل.

تلميح: المرة الوحيدة التي يكون فيها من المنطقي تعيين ignoreFieldNorm على القيمة true هي عندما لا يهم عدد المصطلحات الموجودة، ولكن يهم فقط وجود مصطلح الاستعلام.

`fieldNormWeight`

النوع: float
الافتراضي: 1

يحدد مدى تأثير معيار طول المجال على التسجيل. القيمة 0 تعادل تجاهل معيار طول المجال. ستؤدي القيمة 0.5 إلى تقليل تأثير معيار طول المجال بشكل كبير، في حين أن القيمة 2.0 ستزيده بشكل كبير.

التكوين العالمي

يمكنك الوصول إلى القيم الافتراضية لجميع الخيارات المذكورة أعلاه ومعالجتها عبر طريقة config :

 // Get an associative array of all options listed above
Fuse :: config ();

// Merge associative array of options into default config
Fuse :: config ([ ' shouldSort ' => false ]);

// Get single default option
Fuse :: config ( ' shouldSort ' );

// Set single default option
Fuse :: config ( ' shouldSort ' , false );

طُرق

تتوفر الطرق التالية في كل مثيل FuseFuse :

`search`

يبحث في مجموعة المستندات بأكملها، ويعيد قائمة نتائج البحث.

 public function search( mixed $ pattern , ? array $ options ): array

يمكن أن يكون $pattern واحدًا مما يلي:

خيط
طريق
استعلام موسع
الاستعلام المنطقي

$options :

limit (النوع: int ): يشير إلى الحد الأقصى لعدد نتائج البحث التي يتم إرجاعها.

`setCollection`

تعيين/استبدال المجموعة الكاملة من المستندات. إذا لم يتم توفير أي فهرس، فسيتم إنشاء واحد.

 public function setCollection( array $ docs , ?  Fuse  Core  FuseIndex $ index ): void

مثال:

 $ fruits = [ ' apple ' , ' orange ' ];
$ fuse = new Fuse ( $ fruits );

$ fuse -> setCollection ([ ' banana ' , ' pear ' ]);

`add`

إضافة مستند إلى المجموعة وتحديث الفهرس وفقًا لذلك.

 public function add( mixed $ doc ): void

مثال:

 $ fruits = [ ' apple ' , ' orange ' ];
$ fuse = new Fuse ( $ fruits );

$ fuse -> add ( ' banana ' );

sizeof ( $ fruits ); // => 3

`remove`

يزيل جميع المستندات من القائمة التي يُرجع المسند صحتها، ويعيد مصفوفة من المستندات التي تمت إزالتها. يتم استدعاء المسند باستخدام وسيطتين: ($doc, $index) .

 public function remove(? callable $ predicate ): array

مثال:

 $ fruits = [ ' apple ' , ' orange ' , ' banana ' , ' pear ' ];
$ fuse = new Fuse ( $ fruits );

$ results = $ fuse -> remove (fn( $ doc ) => $ doc === ' banana ' || $ doc === ' pear ' );
sizeof ( $ fuse -> getCollection ()); // => 2
$ results ; // => ['banana', 'pear']

`removeAt`

يزيل المستند في الفهرس المحدد.

 public function removeAt( int $ index ): void

مثال:

 $ fruits = [ ' apple ' , ' orange ' , ' banana ' , ' pear ' ];
$ fuse = new Fuse ( $ fruits );

$ fuse -> removeAt ( 1 );

$ fuse -> getCollection (); // => ['apple', 'banana', 'pear']

`getIndex`

إرجاع فهرس الصمامات الذي تم إنشاؤه.

 public function getIndex():  Fuse  Core  FuseIndex

مثال:

 $ fruits = [ ' apple ' , ' orange ' , ' banana ' , ' pear ' ];
$ fuse = new Fuse ( $ fruits );

$ fuse -> getIndex ()-> size (); // => 4

الفهرسة

تتوفر الطرق التالية في كل مثيل FuseFuse :

`Fuse::createIndex`

قم بإنشاء الفهرس مسبقًا من القائمة، وقم بتمريره مباشرةً إلى مثيل Fuse. إذا كانت القائمة كبيرة (إلى حد كبير)، فإنها تعمل على تسريع عملية إنشاء مثيل.

 public static function createIndex( array $ keys , array $ docs , array $ options = []):  Fuse  Core  FuseIndex

مثال:

 $ list = [ ... ]; // See the example from the 'Usage' section
$ options = [ ' keys ' => [ ' title ' , ' author.firstName ' ] ];

// Create the Fuse index
$ myIndex = Fuse :: createIndex ( $ options [ ' keys ' ], $ list );

// Initialize Fuse with the index
$ fuse = new Fuse ( $ list , $ options , $ myIndex );

`Fuse::parseIndex`

يوزع فهرس الصمامات المتسلسل JSON.

 public static function parseIndex( array $ data , array $ options = []):  Fuse  Core  FuseIndex

مثال:

 // (1) When the data is collected

$ list = [ ... ]; // See the example from the 'Usage' section
$ options = [ ' keys ' => [ ' title ' , ' author.firstName ' ] ];

// Create the Fuse index
$ myIndex = Fuse :: createIndex ( $ options [ ' keys ' ], $ list );

// Serialize and save it
file_put_contents ( ' fuse-index.json ' , json_encode ( $ myIndex ));


// (2) When the search is needed

// Load and deserialize index to an array
$ fuseIndex = json_decode ( file_get_contents ( ' fuse-index.json ' ), true );
$ myIndex = Fuse :: parseIndex ( $ fuseIndex );

// Initialize Fuse with the index
$ fuse = new Fuse ( $ list , $ options , $ myIndex );

الاختلافات مع Fuse.js

	فيوز.js	PHP فيوز
الحصول على نسخة فيوز	`Fuse.version`	-
الوصول إلى التكوين العالمي	خاصية `Fuse.config`	`Fuse::config`
تعديل القائمة	يؤدي استخدام `fuse.add()` وما إلى ذلك إلى تعديل القائمة الأصلية التي تم تمريرها إلى مُنشئ `new Fuse` .	في PHP، المصفوفات هي نوع بيانات بدائي، مما يعني أن قائمتك الأصلية لن يتم تعديلها أبدًا بواسطة Fuse. لتلقي القائمة الحالية بعد إضافة/إزالة العناصر، يمكن استخدام الأسلوب `$fuse->getCollection()` .

تطوير

نطاق المشروع

يرجى ملاحظة أنني أسعى جاهداً لتحقيق تكافؤ الميزات مع Fuse.js، وبالتالي لن أضيف أي ميزات أو إصلاحات إلى منطق البحث التي لا تنعكس في Fuse.js نفسه.

إذا كانت لديك أية مشكلات تتعلق بنتائج البحث التي لا تمثل أخطاء واضحة في منفذ PHP هذا، وكنت تعرف JavaScript، فيرجى التحقق مما إذا كانت حالة الاستخدام الخاصة بك تعمل بشكل صحيح في العرض التوضيحي عبر الإنترنت لـ Fuse.js حيث أن هذا هو تطبيق Fuse الأساسي. إذا ظهرت المشكلة هناك أيضًا، فيرجى فتح مشكلة في الريبو الخاص بهم.

يثبت

لبدء التطوير على Fuse، تحتاج إلى git وPHP (≥ 7.4) وComposer.
نظرًا لأن الكود منسق باستخدام Prettier، فمن المستحسن أيضًا تثبيت Node.js/npm بالإضافة إلى استخدام محرر يدعم تنسيق Prettier.

استنساخ المستودع والقرص cd فيه:

git clone https://github.com/loilo/fuse.git
cd fuse

تثبيت تبعيات الملحن:

composer install

تثبيت تبعيات npm (اختياري ولكن يوصى به). هذا مطلوب فقط لتنسيق التعليمات البرمجية لأن تبعيات npm تتضمن مكونات Prettier الإضافية التي يستخدمها هذا المشروع.

 npm ci

ضمان الجودة

هناك أنواع مختلفة من عمليات التحقق من التعليمات البرمجية لهذا المشروع. يتم تشغيل كل هذه العناصر عند إرسال طلب سحب ولكن يمكن أيضًا تشغيلها محليًا:

يأمر	غاية	وصف
`vendor/bin/phpcs`	تحقق من نمط الكود	قم بتشغيل PHP_CodeSniffer للتحقق من أن كود مصدر Fuse يلتزم بنمط الترميز PSR-12.
`vendor/bin/psalm`	تحليل ثابت	قم بتشغيل Psalm على قاعدة التعليمات البرمجية لتجنب الأخطاء المتعلقة بالنوع وأنماط الترميز غير الآمنة.
`vendor/bin/phpunit`	التحقق من منطق البرنامج	قم بتشغيل جميع اختبارات PHPUnit من مجلد `test` .

المساهمة

قبل تقديم طلب السحب، يرجى إضافة الاختبارات ذات الصلة إلى مجلد test .

يوسع