عرض مصدر PHP/array multisort

<noinclude>{{DISPLAYTITLE:<code>array_multisort()‎</code>}}</noinclude>
(PHP 4, PHP 5, PHP 7)

تُرتِّب الدالة <code>array_multisort()</code>‎ عدة مصفوفات أو المصفوفات متعددة الأبعاد.

== الوصف ==
<syntaxhighlight lang="php">
bool array_multisort ( array &$array1 [, mixed $array1_sort_order = SORT_ASC [, mixed$array1_sort_flags = SORT_REGULAR [, mixed $... ]]] )
</syntaxhighlight>يمكن استخدام الدالة <code>array_multisort()</code>‎ لترتيب عدة مصفوفات دفعةً واحدةً، أو بُعد واحد أو أكثر في حالة المصفوفة متعددة الأبعاد.

ويُحتَفَظ بالمفاتيح المقترنة من النوع <code>string</code>، ولكن ستُعاد فهرسة المفاتيح الرقمية.

ملاحظة: إذا تساوت مقارنة عنصرين في المصفوفة، فإن ترتيبهما النسبي في المصفوفة المُرتّبة يكون غير محدد.

== المعاملات ==

=== <code>array1</code> ===
المصفوفة المراد ترتيبها.

=== <code>array1_sort_order</code> ===
الوسيط المستخدم لترتيب المصفوفة السابقة. إما أن يكون <code>SORT_ASC</code> للترتيب التصاعدي أو <code>SORT_DESC</code> للترتيب التنازلي.

يمكن تبديل هذا الوسيط مع <code>array1_sort_flags</code> أو حذفه بالكامل، وفي هذه الحالة سيُفترض أنَّه <code>SORT_ASC</code> .

=== <code>array1_sort_flags</code> ===
وسيطٌ يُحدِّد خيارات ترتيب المصفوفة السابقة:

رايات (flags) أنواع الترتيب:
* <code>SORT_REGULAR</code>: مقارنة العناصر بشكل طبيعي (دون تغيير الأنواع).
* <code>SORT_NUMERIC</code>: مقارنة العناصر رقميًا.
* <code>SORT_STRING</code>: مقارنة العناصر كسلاسل نصية
* <code>SORT_LOCALE_STRING</code>: مقارنة العناصر كسلاسل نصية استنادًا إلى المحلية الحالية (current locale). ستستخدم هذه الدالة المحلية والتي يمكن تغييرها باستخدام الدالة [[PHP/setlocale|<code>setlocale()</code>‎]].
* <code>SORT_NATURAL</code>: مقارنة العناصر كسلاسل باستخدام الترتيب طبيعي مثل <code>[[PHP/natsort|natsort()‎]]</code>.
* <code>SORT_FLAG_CASE</code>: يمكن جمعه (باستخدام المعامل الثنائي OR) مع <code>SORT_STRING</code> أو <code>SORT_NATURAL</code> لترتيب السلاسل بطريقة غير حساسة لحالة الحرف
يمكن تبديل هذه الوسيط مع <code>array1_sort_order</code> أو حذفه بالكامل، وفي هذه الحالة سيُفترض أنَّه <code>SORT_REGULAR</code> .

=== <code>...</code> ===
المزيد من المصفوفات، يتبعها طريقة الترتيب والرايات اختياريًا. تُقارن فقط العناصر المقابلة للعناصر المكافئة في المصفوفات السابقة. وبعبارة أخرى ، فإن الترتيب معجمي.

== القيم المعادة ==
تُعيد الدالة <code>array_multisort()</code>‎  القيمة <code>TRUE</code> عند النجاح أو <code>FALSE</code> عند الفشل.

== سجل التغييرات ==
{| class="wikitable"
!الإصدار
!الوصف
|-
|5.4.0
|إضافة <code>SORT_NATURAL</code> و <code>SORT_FLAG_CASE</code> إلى <code>array1_sort_flags</code> كرايات ترتيب ممكنة.
|-
|5.3.0
|إضافة <code>SORT_LOCALE_STRING</code> إلى <code>array1_sort_flags</code> كرايات ترتيب ممكنة.
|}

== أمثلة ==
المثال 1: ترتيب عدة مصفوفات<syntaxhighlight lang="php">
<?php
$ar1 = array(10, 100, 100, 0);
$ar2 = array(1, 3, 2, 4);
array_multisort($ar1, $ar2);
var_dump($ar1);
var_dump($ar2);
?>
</syntaxhighlight>في هذا المثال، ستحتوي المصفوفة الأولى على 0، 10، 100، 100. وتحتوي المصفوفة الثانية على 4، 1، 2، 3. ورُتِّبت أيضًا عناصر المصفوفة الثانية بما يقابل العناصر المتطابقة في المصفوفة الأولى (100 و 100).<syntaxhighlight lang="php">
array(4) {
 [0]=> int(0)
 [1]=> int(10)
 [2]=> int(100)
 [3]=> int(100)
}
array(4) {
 [0]=> int(4)
 [1]=> int(1)
 [2]=> int(2)
 [3]=> int(3)
}
</syntaxhighlight>المثال 2: ترتيب مصفوفة متعددة الأبعاد<syntaxhighlight lang="php">
<?php
$ar = array(
      array("10", 11, 100, 100, "a"),
      array(  1,  2, "2",   3,   1)
     );
array_multisort($ar[0], SORT_ASC, SORT_STRING,
               $ar[1], SORT_NUMERIC, SORT_DESC);
var_dump($ar);
?>
</syntaxhighlight>ستتحول المصفوفة الأولى في هذا المثال، بعد الترتيب إلى "10" و 100 و 100 و 11 و "a" (رتِّبَت كسلاسل نصية بترتيب تصاعدي). وتحتوي الثانية على 1، 3، "2"، 2، 1 (مرتبة كأرقام، بترتيب تنازلي).<syntaxhighlight lang="php">
array(2) {
 [0]=> array(5) {
   [0]=> string(2) "10"
   [1]=> int(100)
   [2]=> int(100)
   [3]=> int(11)
   [4]=> string(1) "a"
 }
 [1]=> array(5) {
   [0]=> int(1)
   [1]=> int(3)
   [2]=> string(1) "2"
   [3]=> int(2)
   [4]=> int(1)
 }
}
</syntaxhighlight>المثال 3: ترتيب نتائج قاعدة بيانات

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

بيانات المثال:<syntaxhighlight lang="php">
volume | edition
-------+--------
    67 |       2
    86 |       1
    85 |       6
    98 |       2
    86 |       6
    67 |       7

</syntaxhighlight>يمكن تخزين البيانات السابقة في مصفوفة وليكن اسمها data، عادة ما نحصل على مثل هذه المصفوفات عن طريق حلقات التكرار مع استخدام <code>mysqli_fetch_assoc()‎</code>:<syntaxhighlight lang="php">
<?php
$data[] = array('volume' => 67, 'edition' => 2);
$data[] = array('volume' => 86, 'edition' => 1);
$data[] = array('volume' => 85, 'edition' => 6);
$data[] = array('volume' => 98, 'edition' => 2);
$data[] = array('volume' => 86, 'edition' => 6);
$data[] = array('volume' => 67, 'edition' => 7);
?>
</syntaxhighlight>سنرتِّب القيم في هذا المثال تنازليًا حسب الحجم (volume)، وحسب الإصدار (edition) تصاعديًا.

لدينا مصفوفة من الصفوف، ولكن تتطلب الدالة <code>array_multisort()‎</code> مصفوفةً من الأعمدة، لذلك نستخدم الشيفرة التالية للحصول على الأعمدة، ثم سنُجري الترتيب.<syntaxhighlight lang="php">
<?php
// الحصول على قائمة من الأعمدة
foreach ($data as $key => $row) {
   $volume[$key]  = $row['volume'];
   $edition[$key] = $row['edition'];
}
// ترتيب البيانات حسب الحجم تنازليًا، وحسب الإصدار تصاعديًا
// إضافة data$ كآخر وسيط للترتيب حسب المفتاح المشترك
array_multisort($volume, SORT_DESC, $edition, SORT_ASC, $data);
?>
</syntaxhighlight>ستبدو مجموعة البيانات بعد الترتيب الآن كما يلي:<syntaxhighlight lang="php">
volume | edition
-------+--------
    98 |       2
    86 |       1
    86 |       6
    85 |       6
    67 |       2
    67 |       7

</syntaxhighlight>المثال 4: ترتيب المصفوفات غير الحساس لحالة الأحرف

كلًا من <code>SORT_STRING</code> و <code>SORT_REGULAR</code> حساسيْن لحالة الأحرف، وتأتي السلاسل التي تبدأ بحرف كبير قبل السلاسل التي تبدأ بحرف صغير.

لتنفيذ ترتيب غير حساس لحالة الأحرف، فعلينا إجراء عملية الترتيب على نسخة أخرى من المصفوفة بعد تحويل أحرفها إلى الحالة الصغيرة..<syntaxhighlight lang="php">
<?php
$array = array('Alpha', 'atomic', 'Beta', 'bank');
$array_lowercase = array_map('strtolower', $array);
array_multisort($array_lowercase, SORT_ASC, SORT_STRING, $array);
print_r($array);
?>
</syntaxhighlight>سوف ينتج المثال أعلاه:<syntaxhighlight lang="php">
Array
(
   [0] => Alpha
   [1] => atomic
   [2] => bank
   [3] => Beta
)
</syntaxhighlight>

== انظر أيضًا ==
* الدالة <code>[[PHP/usort|usort()‎]]</code>: ترتيب مصفوفة باستخدام دالة مقارنة مُعرَّفة من طرف المستخدم.
* [[PHP/array Sorting|مقارنة بين دوال الترتيب الخاصة بالمصفوفات]].

== مصادر ==
* [http://php.net/manual/en/function.array-multisort.php صفحة الدالة array_multisort في توثيق PHP الرسمي.]

[[تصنيف:PHP]]
[[تصنيف:PHP Function]]
[[تصنيف:PHP Array]]