عرض مصدر Laravel/collections

== مقدمة==
يوفر الصنف <code>Illuminate\Support\Collection</code> غلافًا ملائمًا و مساعدًا على العمل مع مصفوفات البيانات. مثلًا، تفقد الشيفرة الموالية إذ سنستعمل المساعد <code>collect</code> لإنشاء نسخة <code>Collection</code> جديدة من المصفوفة، ننفذ الدالة <code>strtoupper</code> مع كل عنصر، ثم نحذف كل العناصر الفارغة:<syntaxhighlight lang="php">
$collection = collect(['taylor', 'abigail', null])->map(function ($name) {
   return strtoupper($name);

}) ->reject(function ($name) {
   return empty($name);

});
</syntaxhighlight>كما ترى، تسمح الدالة بسلسلة توابعها لتنفيذِ تخطيطِ دقيق و التحكم في حجم المصفوفة قيد العمل. بشكل عام، المجموعات غير قابلة للتغيير، أي أن كل تابع <code>collect</code> يعيد نسخة من كائن مجموعة جديد تمامًا.
===إنشاء المجموعات===
كما ذُكر سابقًا، يعيد التابع المساعد <code>collect</code> نسخة من كائن <code>Illuminate\Support\Collection</code> جديد لكل مصفوفة. لذا، يمكننا إنشاء مجموعة بسهولة<syntaxhighlight lang="php">
$collection = collect([1, 2, 3]);
</syntaxhighlight>'''ملاحظة''': نتائج طلبات [[Laravel/eloquent|Eloquent]] تكون دائمًا على شكل كائن <code>Collection</code>.
===تمديد المجموعات===
المجموعات قابلة للتمديد، مما يسمح لك بإضافة توابع أخرى للصنف <code>Collection</code> في وقت التشغيل. مثلًا، الشيفرة التالية تضيف التابع <code>toUpper</code> إلى الصنف <code>Collection</code>:<syntaxhighlight lang="php">
use Illuminate\Support\Str;

Collection::macro('toUpper', function () {

   return $this->map(function ($value) {
       return Str::upper($value);
   });
});

$collection = collect(['first', 'second']);
$upper = $collection->toUpper();

// ['FIRST', 'SECOND']
</syntaxhighlight>في العادة، عليك ذكر الإضافات للصنف <code>Collection</code> في مزود الخدمات.
==التوابع المتاحة==
في بقية هذا التوثيق، سنناقش كل تابع متوافر في الصنف <code>Collection</code>. تذكر أنّ كل التوابع يمكن سلسلتها معًا لمعالجة المصفوفة بيسر. بالإضافة ألى ذلك، تقريبًا كل التوابع تعيد نسخة جديدة من الكائن <code>Collection</code> مما يحافظ على المجموعة الأصلية عند الحاجة:
===<code>()all</code>===
يعيد التابع المصفوفة المقصودة على شكل مجموعة:<syntaxhighlight lang="php">
collect([1, 2, 3])->all();
// [1, 2, 3]

</syntaxhighlight>
===<code>()average</code>===
اسم بديل للتابع <code>avg</code>.
===<code>()avg</code>===
يعيد التابع قيمة المتوسط الحسابي للمفتاح الممرّر:<syntaxhighlight lang="php">
$average = collect([['foo' => 10], ['foo' => 10], ['foo' => 20], ['foo' => 40]])->avg('foo');
// 20

$average = collect([1, 1, 2, 4])->avg();
// 2


</syntaxhighlight>
===<code>()chunk</code>===
يقسم التابع المجموعة لعدة مجموعات أصغر بحجم معين:<syntaxhighlight lang="php">
$collection = collect([1, 2, 3, 4, 5, 6, 7]);
$chunks = $collection->chunk(4);
$chunks->toArray();

// [[1, 2, 3, 4], [5, 6, 7]]


</syntaxhighlight>هذا التابع مفيد خاصة في الواجهات عند العمل مع نظام شبكي "grid" مثل <code>Bootstrap</code>. تخيل أنك تريد عرض مجموعة من نماذج [[Laravel/eloquent|Eloquent]] في شبكة:<syntaxhighlight lang="php">
@foreach ($products->chunk(3) as $chunk)

       @foreach ($chunk as $product)
{{$product->name }}
       @endforeach
@endforeach


</syntaxhighlight>
===<code>()collapse</code>===
يُسقط التابع مجموعة من المصفوفات في مجموعة واحدة ذات بعد واحد:<syntaxhighlight lang="php">
$collection = collect([[1, 2, 3], [4, 5, 6], [7, 8, 9]]);
$collapsed = $collection->collapse();
$collapsed->all();

// [1, 2, 3, 4, 5, 6, 7, 8, 9]


</syntaxhighlight>
===<code>()combine</code>===
يدمج التابع مفاتيح المجموعة مع قيم من مجموعة أو مصفوفة أخرى:<syntaxhighlight lang="php">
$collection = collect(['name', 'age']);
$combined = $collection->combine(['George', 29]);
$combined->all();

// ['name' => 'George', 'age' => 29]


</syntaxhighlight>
===<code>()concat</code>===
يضيف التابع المصفوفة الممررة أو قيم المجموعة المُمَرَّرة لآخر المجموعة:<syntaxhighlight lang="php">
$collection = collect(['John Doe']);
$concatenated = $collection->concat(['Jane Doe'])->concat(['name' => 'Johnny Doe']);
$concatenated->all();

// ['John Doe', 'Jane Doe', 'Johnny Doe']


</syntaxhighlight>
===<code>()contains</code>===
يحدد التابع إذا كانت المجموعة تحتوي على عنصرٍ محدِّد أم لا:<syntaxhighlight lang="php">
$collection = collect(['name' => 'Desk', 'price' => 100]);
$collection->contains('Desk');

// true

$collection->contains('New York');

// false


</syntaxhighlight>يمكنك أيضًا تمرير زوجٍ من المفتاح/القيمة إلى التابع الذي سيحدد إذا كان الثنائي موجودًا أم لا:<syntaxhighlight lang="php">
$collection = collect([

   ['product' => 'Desk', 'price' => 200],
   ['product' => 'Chair', 'price' => 100],
]);

$collection->contains('product', 'Bookcase');

// false


</syntaxhighlight>أخيرًا، يمكنك تمرير دالة رد نداء إلى التابع <code>contains</code> لتقوم بعملية التحقق من وجود القيمة بنفسك:<syntaxhighlight lang="php">
$collection = collect([1, 2, 3, 4, 5]);
$collection->contains(function ($value, $key) {

   return $value > 5;
});

// false


</syntaxhighlight>يقوم التابع بمقارنة بسيطة، أي أن سلسلة المحارف التي تحتوي على رقم تُعدّ مساويةً لعدد صحيحٍ بنفس القيمة الرقمية. استعمل التابع <code>containsStrict</code> لمقارنة أكثر صرامةً.
===<code>()containsStrict</code>===
نفس الوظيفة التابع لكنها تستعمل مقارنةً صارمةً (strict).
===<code>()count</code>===
يعيد التابع عدد عناصر المجموعة:<syntaxhighlight lang="php">
$collection = collect([1, 2, 3, 4]);
$collection->count();

// 4


</syntaxhighlight>
===<code>()crossJoin</code>===
يقوم التابع بوصل تقاطعي بين قيم المجموعة والمصفوفة الممرّرة، ويعيد جداءً ديكارتيًا بكل المبادلات الممكنة:<syntaxhighlight lang="php">
$collection = collect([1, 2]);
$matrix = $collection->crossJoin(['a', 'b']);
$matrix->all();

/*
    [
        [1, 'a'],
        [1, 'b'],
        [2, 'a'],
        [2, 'b'],
    ]
*/

$collection = collect([1, 2]);
$matrix = $collection->crossJoin(['a', 'b'], ['I', 'II']);
$matrix->all();

/*
    [
        [1, 'a', 'I'],
        [1, 'a', 'II'],
        [1, 'b', 'I'],
        [1, 'b', 'II'],
        [2, 'a', 'I'],
        [2, 'a', 'II'],
        [2, 'b', 'I'],
        [2, 'b', 'II'],
    ]
*/
</syntaxhighlight>
===<code>()dd</code>===
يطبع التابع عناصر المجموعة وينهي تنفيذ السكربت:<syntaxhighlight lang="php">
$collection = collect(['John Doe', 'Jane Doe']);
$collection->dd();

/*
    Collection {
        #items: array:2 [
            0 => "John Doe"
            1 => "Jane Doe"
        ]
    }
*/
</syntaxhighlight>إذا لم ترد إنهاء السكربت، فاستعمل التابع <code>dump</code> بدلًا من <code>dd</code>.
===<code>()diff</code>===
يقارن التابع المجموعة بمجموعة أخرى أو بمصفوفة PHP عادية اعتمادًا على قيمها. يعيد هذا التابع قيم المجموعة الأصلية غير الموجودة في المجموعة الممرّرة:<syntaxhighlight lang="php">
$collection = collect([1, 2, 3, 4, 5]);
$diff = $collection->diff([2, 4, 6, 8]);
$diff->all();

// [1, 3, 5]


</syntaxhighlight>
===<code>()diffAssoc</code>===
يقارن التابع المجموعة بمجموعة أخرى أو بمصفوفة [[PHP]] بالاعتماد على المفاتيح والقيم. يعيد هذا التابع أزواج المفتاح/القيمة من المجموعة الأصلية غير الموجودة في المجموعة الممررة:<syntaxhighlight lang="php">
$collection = collect([

   'color' => 'orange',
   'type' => 'fruit',
   'remain' => 6
]);

$diff = $collection->diffAssoc([

   'color' => 'yellow',
   'type' => 'fruit',
   'remain' => 3,
   'used' => 6
]);

$diff->all();

// ['color' => 'orange', 'remain' => 6]


</syntaxhighlight>
===<code>()diffKeys</code>===
يقارن هذا التابع المجموعة بمجموعة أخرى أو بمصفوفة PHP بالإرتكاز على المفاتيح، يعيد هذا التابع أزواج المفتاح/القيمة من المجموعة الأصلية غير الموجودة في المجموعة الممرّرة:<syntaxhighlight lang="php">
$collection = collect([

   'one' => 10,
   'two' => 20,
   'three' => 30,
   'four' => 40,
   'five' => 50,
]);

$diff = $collection->diffKeys([

   'two' => 2,
   'four' => 4,
   'six' => 6,
   'eight' => 8,
]);

$diff->all();

// ['one' => 10, 'three' => 30, 'five' => 50] 


</syntaxhighlight>
===<code>()dump</code>===
يطبع التابع عناصر المجموعة:<syntaxhighlight lang="php">
$collection = collect(['John Doe', 'Jane Doe']);

$collection->dump();

/*

   Collection {
       #items: array:2 [
           0 => "John Doe"
           1 => "Jane Doe"
       ]
   }
*/

</syntaxhighlight>إذا أردت إيقاف تنفيذ السكربت بعد تفريغ المجموعة فاستعمل التابع <code>dd</code>.
===<code>()each</code>===
يكرّر التابع عناصر المجموعة واحدًا بواحد ويمرّرها لدالة رد نداء:<syntaxhighlight lang="php">
$collection->each(function ($item, $key) {

  //
});


</syntaxhighlight>إذا أردت إيقاف التكرار، أعد القيمة <code>false</code> من دالة رد النداء:<syntaxhighlight lang="php">
$collection->each(function ($item, $key) {

   if (/* شرط إيقاف */) {
       return false;
   }
});


</syntaxhighlight>
===<code>()eachSpread</code>===
يكرّّر التابع عناصر المجموعة ويمرّر كل عنصر متداخل لدالة رد النداء:<syntaxhighlight lang="php">
$collection = collect([['John Doe', 35], ['Jane Doe', 33]]);
$collection->eachSpread(function ($name, $age) {

  //
});

</syntaxhighlight>يمكنك إيقاف التكرار بإعادة القيمة <code>false</code> من دالة رد النداء.<syntaxhighlight lang="php">
$collection->eachSpread(function ($name, $age) {

   return false;
});


</syntaxhighlight>
===<code>()every</code>===
يمكن استعمال التابع للتأكد من أن كل عناصر المجموعة تحقق شرطًا معينًا:<syntaxhighlight lang="php">
collect([1, 2, 3, 4])->every(function ($value, $key) {

   return $value > 2;
});

// false


</syntaxhighlight>

=== <code>()except</code> ===
يعيد التابع كل عناصر المجموعة باستثناء العناصر بالمفاتيح المحدَّدة:<syntaxhighlight lang="php">
$collection = collect(['product_id' => 1, 'price' => 100, 'discount' => false]);
$filtered = $collection->except(['price', 'discount']);
$filtered->all();

// ['product_id' => 1]


</syntaxhighlight>لعكس وظيفة <code>except</code>، انظر التابع <code>only</code>.
===<code>()filter</code>===
يرشِّح التابع عناصر المجموعة ويُبقي فقط العناصر التي تحقق شرطًا معينًا:<syntaxhighlight lang="php">
$collection = collect([1, 2, 3, 4]);
$filtered = $collection->filter(function ($value, $key) {

   return $value > 2;
});

$filtered->all();

// [3, 4]


</syntaxhighlight>إذا لم توفّر نداء للتابع، يحذف <code>filter</code> كل العناصر المساوية للقيمة <code>false</code>:<syntaxhighlight lang="php">
$collection = collect([1, 2, 3, null, false, , 0, []]);
$collection->filter()->all();

// [1, 2, 3]


</syntaxhighlight>لعكس وظيفة <code>filter</code> انظر التابع <code>reject</code>.
===<code>()first</code>===
يرجع التابع العنصر الأول من المجموعة الذي يحقق شرطًا معينًا:<syntaxhighlight lang="php">
collect([1, 2, 3, 4])->first(function ($value, $key) {

   return $value > 2;
}); // 3


</syntaxhighlight>يمكنك أيضًا استدعاء التابع <code>first</code> دون معامل، وسيعيد العنصر الأول من المجموعة، وإذا كانت المجموعة فارغةً، فستعاد القيمة <code>null</code>:<syntaxhighlight lang="php">
collect([1, 2, 3, 4])->first();

// 1 


</syntaxhighlight>
===<code>()firstWhere</code>===
يعيد التابع العنصر الأول من المجموعة الموافق لزوج المفتاح/القيمة الممرّر:<syntaxhighlight lang="php">
$collection = collect([

   ['name' => 'Regena', 'age' => 12],
   ['name' => 'Linda', 'age' => 14],
   ['name' => 'Diego', 'age' => 23],
   ['name' => 'Linda', 'age' => 84],
]);

$collection->firstWhere('name', 'Linda');

// ['name' => 'Linda', 'age' => 14]


</syntaxhighlight>يمكن أيضًا استعمال التابع مع عامل مقارنة:<syntaxhighlight lang="php">
$collection->firstWhere('age', '>=', 18);

// ['name' => 'Diego', 'age' => 23]


</syntaxhighlight>
===<code>()flatMap</code>===
ينفذ التابع حلقة تكرار في المجموعة، فيمرر قيمة كل تكرار لنداء معين. يمكن للنداء تغيير العنصر وإرجاعه وبالتالي يكوّن مجموعةً جديدة من العناصر المغيَّرة. ثم تُسطَّح المجموعة حسب مستواها:<syntaxhighlight lang="php">
$collection = collect([

   ['name' => 'Sally'],
   ['school' => 'Arkansas'],
   ['age' => 28]
]);

$flattened = $collection->flatMap(function ($values) {

   return array_map('strtoupper', $values);
});

$flattened->all();

// ['name' => 'SALLY', 'school' => 'ARKANSAS', 'age' => '28'];


</syntaxhighlight>
===<code>()flatten</code>===
يُسطِّح التابع مجموعة متعددة الأبعاد لمجموعة ذات بعد واحد:<syntaxhighlight lang="php">
$collection = collect(['name' => 'taylor', 'languages' => ['php', 'javascript']]);
$flattened = $collection->flatten();
$flattened->all();

// ['taylor', 'php', 'javascript'];
</syntaxhighlight>يمكنك أيضًا تمرير معامل لضبط عمق التسطيح:<syntaxhighlight lang="php">
$collection = collect([

   'Apple' => [
       ['name' => 'iPhone 6S', 'brand' => 'Apple'],
   ],
   'Samsung' => [
       ['name' => 'Galaxy S7', 'brand' => 'Samsung']
   ],
]);

$products = $collection->flatten(1);
$products->values()->all();

/*

   [
       ['name' => 'iPhone 6S', 'brand' => 'Apple'],
       ['name' => 'Galaxy S7', 'brand' => 'Samsung'],
   ]

</syntaxhighlight>في هذا المثال، سيتسبب عدم توفير عمق في تسطيح المصفوفات الداخلية لتصبح النتيجة <code>['iPhone 6S', 'Apple', 'Galaxy S7', 'Samsung']</code>. مما يوفّر مستوى عمق يسمح بتحديد مستوى التداخل الذي سيتم تسطيحه.
===<code>()flip</code>===
يُبدِّل التابع المفتاح بقيمته:<syntaxhighlight lang="php">
$collection = collect(['name' => 'taylor', 'framework' => 'laravel']);
$flipped = $collection->flip();
$flipped->all();

// ['taylor' => 'name', 'laravel' => 'framework']
</syntaxhighlight>
===<code>()forget</code>===
يحذف التابع عنصرًا من المجموعة باستخدام مفتاحه:<syntaxhighlight lang="php">
$collection = collect(['name' => 'taylor', 'framework' => 'laravel']);
$collection->forget('name');
$collection->all();

// ['framework' => 'laravel']
</syntaxhighlight>'''تنبيه:''' على عكس جل توابع المجموعات، لا يعيد <code>forget</code> مجموعةً جديدةً بل يغيّر في المجموعة التي استدعي هذا التابع عليها.
===<code>()forPage</code>===
يعيد التابع مجموعة تحتوي العناصر الموجودة في رقم الصفحة الممرّر. يقبل التابع رقم صفحة كمعامل أول وعدد العناصر التي يجب إظهارها في الصفحة كمعامل ثاني:<syntaxhighlight lang="php">
$collection = collect([1, 2, 3, 4, 5, 6, 7, 8, 9]);
$chunk = $collection->forPage(2, 3);
$chunk->all();

// [4, 5, 6]

</syntaxhighlight>
===<code>()get</code>===
يعيد التابع قيمة العنصر ذي المفتاح المُمرَّر إلى التابع. إذا كان المفتاح غير موجود فستعاد القيمة <code>null</code>:<syntaxhighlight lang="php">
$collection = collect(['name' => 'taylor', 'framework' => 'laravel']);
$value = $collection->get('name');

// taylor


</syntaxhighlight>يمكنك تمرير قيمة أولية اختيارية كمعامل ثاني:<syntaxhighlight lang="php">
$collection = collect(['name' => 'taylor', 'framework' => 'laravel']);
$value = $collection->get('foo', 'default-value');

// default-value

</syntaxhighlight>يمكنك حتى تمرير دالة رد نداء. تُعاد القيمة المُعادة من دالة رد النداء في حال عدم وجود المفتاح:<syntaxhighlight lang="php">
$collection->get('email', function () {

   return 'default-value';
});

// default-value

</syntaxhighlight>
===<code>()groupBy</code>===
يُجمِّع التابع العناصر حسب قيمة المفتاح الممرّر إلى التابع:<syntaxhighlight lang="php">
$collection = collect([

   ['account_id' => 'account-x10', 'product' => 'Chair'],
   ['account_id' => 'account-x10', 'product' => 'Bookcase'],
   ['account_id' => 'account-x11', 'product' => 'Desk'],
]);

$grouped = $collection->groupBy('account_id');
$grouped->toArray();

/*
   [
       'account-x10' => [
           ['account_id' => 'account-x10', 'product' => 'Chair'],
           ['account_id' => 'account-x10', 'product' => 'Bookcase'],
       ],
       'account-x11' => [
           ['account_id' => 'account-x11', 'product' => 'Desk'],
      ],
   ]
*/

</syntaxhighlight>بدل تمرير سلسلة محارف <code>key</code>، يمكنك تمرير دالة رد نداء التي يجب أن تعيد القيمة التي تريد أن تكون مفتاح التجميع:<syntaxhighlight lang="php">
$grouped = $collection->groupBy(function ($item, $key) {

   return substr($item['account_id'], -3);
});

$grouped->toArray();

/*

   [
       'x10' => [
           ['account_id' => 'account-x10', 'product' => 'Chair'],
           ['account_id' => 'account-x10', 'product' => 'Bookcase'],
       ],
       'x11' => [
           ['account_id' => 'account-x11', 'product' => 'Desk'],
       ],
   ]
*/


</syntaxhighlight>يمكن تمرير عدة معايير تجميع كمصفوفة، يُطبّق كل عنصر من المصفوفة على مستوى العمق الملائم في مصفوفة متعددة الأبعاد:<syntaxhighlight lang="php">
$data = new Collection([

   10 => ['user' => 1, 'skill' => 1, 'roles' => ['Role_1', 'Role_3']],
   20 => ['user' => 2, 'skill' => 1, 'roles' => ['Role_1', 'Role_2']],
   30 => ['user' => 3, 'skill' => 2, 'roles' => ['Role_1']],
   40 => ['user' => 4, 'skill' => 2, 'roles' => ['Role_2']],
]);

$result = $data->groupBy([

   'skill',
   function ($item) {
       return $item['roles'];
   },
], $preserveKeys = true);

/* [

   1 => [
       'Role_1' => [
           10 => ['user' => 1, 'skill' => 1, 'roles' => ['Role_1', 'Role_3']],
           20 => ['user' => 2, 'skill' => 1, 'roles' => ['Role_1', 'Role_2']],
       ],
       'Role_2' => [
           20 => ['user' => 2, 'skill' => 1, 'roles' => ['Role_1', 'Role_2']],
       ],
       'Role_3' => [
           10 => ['user' => 1, 'skill' => 1, 'roles' => ['Role_1', 'Role_3']],
       ],
   ],
   2 => [
       'Role_1' => [
           30 => ['user' => 3, 'skill' => 2, 'roles' => ['Role_1']],
       ],
       'Role_2' => [
           40 => ['user' => 4, 'skill' => 2, 'roles' => ['Role_2']],
       ],
   ],
];

*/


</syntaxhighlight>
===<code>()has</code>===
يحدد التابع إذا كان المفتاح موجودًا في المجموعة أم لا:<syntaxhighlight lang="php">
$collection = collect(['account_id' => 1, 'product' => 'Desk']);
$collection->has('product');

// true


</syntaxhighlight>
===<code>()implode</code>===
يضم التابع عناصر المجموعة في سلسلة حرفية. تعتمد التوابع على نوع العناصر في المجموعة. إذا كانت المجموعة تحتوي مصفوفات أو كائنات، يجب تمرير مفتاح الخاصيات التي تريد ضمّها وعلامة الربط "glue" الذي تريد استعماله بين القيم:<syntaxhighlight lang="php">
$collection = collect([

   ['account_id' => 1, 'product' => 'Desk'],
   ['account_id' => 2, 'product' => 'Chair'],
]);

$collection->implode('product', ', ');

// Desk, Chair


</syntaxhighlight>إذا كانت المجموعة تحتوي سلاسل نصية أو قيمًا رقميةً بسيطةً، فمرّر علامة الربط فقط كمعامل إلى التابع:<syntaxhighlight lang="php">
collect([1, 2, 3, 4, 5])->implode('-');

// '1-2-3-4-5'


</syntaxhighlight>
===<code>()intersect</code>===
يحذف التابع أي قيمة في المجموعة الأصلية غير موجودة في المجموعة أو المصفوفة الممرّرة. تحافظ المجموعة النهائية على مفاتيح المجموعة الأصلية:<syntaxhighlight lang="php">
$collection = collect(['Desk', 'Sofa', 'Chair']);
$intersect = $collection->intersect(['Desk', 'Chair', 'Bookcase']);
$intersect->all();

// [0 => 'Desk', 2 => 'Chair']


</syntaxhighlight>
===<code>()intersectByKeys</code>===
يحذف التابع أي مفتاح من المجموعة الأصلية غير موجود في المجموعة أو المصفوفة الممرّرة:<syntaxhighlight lang="php">
$collection = collect([

   'serial' => 'UX301', 'type' => 'screen', 'year' => 2009
]);

$intersect = $collection->intersectByKeys([

   'reference' => 'UX404', 'type' => 'tab', 'year' => 2011
]);

$intersect->all();

// ['type' => 'screen', 'year' => 2009]


</syntaxhighlight>
===<code>()isEmpty</code>===
يعيد التابع القيمة <code>true</code> إذا كانت المجموعة فارغة وإلا فسيعيد <code>false</code>:<syntaxhighlight lang="php">
collect([])->isEmpty();

// true


</syntaxhighlight>
===<code>()isNotEmpty</code>===
يعيد التابع القيمة <code>true</code> إذا لم تكن المجموعة فارغة، وإلا فسيعيد <code>false</code>:<syntaxhighlight lang="php">
collect([])->isNotEmpty();

// false


</syntaxhighlight>
===<code>()keyBy</code>===
يضيف التابع مفاتيح للمجموعة، إذا وُجد أكثر من عنصر بنفس المفتاح، فسيضاف الأخير فقط إلى المجموعة الجديدة:<syntaxhighlight lang="php">
$collection = collect([

   ['product_id' => 'prod-100', 'name' => 'Desk'],
   ['product_id' => 'prod-200', 'name' => 'Chair'],
]);

$keyed = $collection->keyBy('product_id');

$keyed->all();

/*

   [
       'prod-100' => ['product_id' => 'prod-100', 'name' => 'Desk'],
       'prod-200' => ['product_id' => 'prod-200', 'name' => 'Chair'],
   ]
*/

</syntaxhighlight>يمكنك تمرير نداء للتابع. يجب أن يعيد النداء القيمة التي ستستعمل كمفتاح للمجموعة:<syntaxhighlight lang="php">
$keyed = $collection->keyBy(function ($item) {

   return strtoupper($item['product_id']);
});

$keyed->all();

/*

   [
       'PROD-100' => ['product_id' => 'prod-100', 'name' => 'Desk'],
       'PROD-200' => ['product_id' => 'prod-200', 'name' => 'Chair'],
   ]
*/

</syntaxhighlight>
===<code>()keys</code>===
يعيد التابع مجموعة متكونة من كل المفاتيح:<syntaxhighlight lang="php">
$collection = collect([

   'prod-100' => ['product_id' => 'prod-100', 'name' => 'Desk'],
   'prod-200' => ['product_id' => 'prod-200', 'name' => 'Chair'],
]);

$keys = $collection->keys();

$keys->all();

// ['prod-100', 'prod-200']


</syntaxhighlight>
===<code>()last</code>===
يعيد التابع العنصر الأخير الذي يحقق شرطًا معينًا. إذا كانت المجموعة فارغةً، فسيعيد التابع القيمة <code>null</code><syntaxhighlight lang="php">
: collect([1, 2, 3, 4])->last();

// 4


</syntaxhighlight>
===<code>()macro</code>===
يسمح التابع  بإضافة توابع للصنف <code>Collection</code> في وقت التشغيل. راجع التوثيق حول تمديد المجموعات لمزيد من المعلومات.
===<code>()make</code>===
يُنشِئ التابع  نسخة مجموعة جديدة. راجع قسم إنشاء المجموعات.
===<code>()map</code>===
يكرّر التابع عناصر المجموعة و يمرّر كل قيمة لدالة رد نداء معيّنة. يمكن لدالة رد اللنداء تغيير العنصر وإعادته، وبالتالي تكوين مجموعة جديدة من العناصر المغيّرة:<syntaxhighlight lang="php">
$collection = collect([1, 2, 3, 4, 5]);

$multiplied = $collection->map(function ($item, $key) {

   return $item * 2;
});

$multiplied->all();

// [2, 4, 6, 8, 10


</syntaxhighlight><u>تنبيه</u>: كأغلب توابع المجموعات، يعيد <code>map</code> مجموعة جديدة ولا يغير المجموعة الأصلية. إذا أردت تغيير المجموعة الأصلية فاستعمل التابع <code>transform</code>.
===<code>()mapInfo</code>===
يكرّر التابع المجموعة وينشِئ نسخةً جديدةً من صنف معين عبر تمرير القيمة للتابع الباني للصنف:<syntaxhighlight lang="php">
class Currency {

   /**
    * صناعة مثيل جديد.
    *
    * @param  string  $code
    * @return void
    */
   function __construct(string $code)
   {
       $this->code = $code;
   }
}

$collection = collect(['USD', 'EUR', 'GBP']);

$currencies = $collection->mapInto(Currency::class);

$currencies->all();

// [Currency('USD'), Currency('EUR'), Currency('GBP')]


</syntaxhighlight>
===<code>()mapSpread</code>===
يكرّر التابع عناصر المجموعة ويمرّر كل عنصر متداخل لدالة رد نداء. يمكن لدالة رد النداء تغيير العنصر وإعادته، وبالتالي تكوين مجموعة جديدة من العناصر المغيرة:<syntaxhighlight lang="php">
$collection = collect([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]);

$chunks = $collection->chunk(2);

$sequence = $chunks->mapSpread(function ($odd, $even) {

   return $odd + $even;
});

$sequence->all();

// [1, 5, 9, 13, 17]


</syntaxhighlight>
===<code>()mapToGroups</code>===
يُجمّع التابع  عناصر المجموعة باستخدام دالة رد النداء المعيّنة. تعيد دالة رد النداء مصفوفة تجميعية تحتوي زوج المفتاح/القيمة واحد، وبالتالي تكوين مجموعة من القيم المجمَّعة:<syntaxhighlight lang="php">
$collection = collect([

   [
       'name' => 'John Doe',
       'department' => 'Sales',
   ],
   [
       'name' => 'Jane Doe',
       'department' => 'Sales',
   ],
   [
       'name' => 'Johnny Doe',
       'department' => 'Marketing',
   ]
]);

$grouped = $collection->mapToGroups(function ($item, $key) {

   return [$item['department'] => $item['name']];
});

$grouped->toArray();

/*

   [
       'Sales' => ['John Doe', 'Jane Doe'],
       'Marketing' => ['Johhny Doe'],
   ]
*/
$grouped->get('Sales')->all();

// ['John Doe', 'Jane Doe']


</syntaxhighlight>
===<code>()mapWithKeys</code>===
يكرّر التابع المجموعة ويمرّر القيم لدالة رد نداء معيّنة. يعيد التابع مصفوفة تجميعية تحتوي زوج المفتاح/القيمة واحد:<syntaxhighlight lang="php">
$collection = collect([

   [
       'name' => 'John',
       'department' => 'Sales',
       'email' => 'john@example.com'
   ],
   [
       'name' => 'Jane',
       'department' => 'Marketing',
       'email' => 'jane@example.com'
   ]
]);

$keyed = $collection->mapWithKeys(function ($item) {

   return [$item['email'] => $item['name']];
});

$keyed->all();

/*

   [
       'john@example.com' => 'John',
       'jane@example.com' => 'Jane',
   ]
*/

</syntaxhighlight>
===<code>()max</code>===
يعيد التابع القيمة القصوى في لمفتاح معين:<syntaxhighlight lang="php">
$max = collect([['foo' => 10], ['foo' => 20]])->max('foo');

// 20 $max = collect([1, 2, 3, 4, 5])->max(); 
// 5


</syntaxhighlight>
===<code>()median</code>===
يعيد التابع القيمة الوسطية للمفتاح المعين:<syntaxhighlight lang="php">
$median = collect([['foo' => 10], ['foo' => 10], ['foo' => 20], ['foo' => 40]])->median('foo');

// 15

$median = collect([1, 1, 2, 4])->median();

// 1.5


</syntaxhighlight>
===<code>()merge</code>===
يدمج التابع المصفوفة أو المجموعة الممرّرة مع المجموعة الأصلية، تلغي القيم الممرّرة القيم الأصلية:<syntaxhighlight lang="php">
$collection = collect(['product_id' => 1, 'price' => 100]);
$merged = $collection->merge(['price' => 200, 'discount' => false]);
$merged->all();

// ['product_id' => 1, 'price' => 200, 'discount' => false]


</syntaxhighlight>إذا كانت المفاتيح الممرّرة رقمية، تضاف القيم في آخر المجموعة:<syntaxhighlight lang="php">
$collection = collect(['Desk', 'Chair']);
$merged = $collection->merge(['Bookcase', 'Door']);
$merged->all();

// ['Desk', 'Chair', 'Bookcase', 'Door']


</syntaxhighlight>
===<code>()min</code>===
يعيد التابع القيمة الأصغر لمفتاح معين:<syntaxhighlight lang="php">
$min = collect([['foo' => 10], ['foo' => 20]])->min('foo');

// 10

$min = collect([1, 2, 3, 4, 5])->min();

// 1


</syntaxhighlight>
===<code>()mode</code>===
يعيد التابع قيمة المنوال لمفتاح معين:<syntaxhighlight lang="php">
$mode = collect([['foo' => 10], ['foo' => 10], ['foo' => 20], ['foo' => 40]])->mode('foo');

// [10]

$mode = collect([1, 1, 2, 4])->mode();

// [1]


</syntaxhighlight>
===<code>()nth</code>===
ينشِئ التابع مجموعةً جديدةً متكونةً من كل عنصر بعد n عناصر<syntaxhighlight lang="php">
$collection = collect(['a', 'b', 'c', 'd', 'e', 'f']);

$collection->nth(4);

// ['a', 'e']


</syntaxhighlight>يمكنك تمرير موضع البداية كمعامل ثاني:<syntaxhighlight lang="php">
$collection->nth(4, 1);

// ['b', 'f']


</syntaxhighlight>
===<code>()only</code>===
يعيد التابع العناصر في المجموعة ذات المفاتيح الممرّرة:<syntaxhighlight lang="php">
$collection->nth(4, 1);

// ['b', 'f']


</syntaxhighlight>لعكس وظيفة <code>only</code>، استعمل التابع <code>expect</code>.
===<code>()pad</code>===
يملأ التابع المصفوفة بالقيمة الممرّرة حتى تصل للحجم المحدد. يشبه هذا التابع دالة <code>array_pad</code> في PHP.<syntaxhighlight lang="php">
$collection = collect(['A', 'B', 'C']);
$filtered = $collection->pad(5, 0);
$filtered->all();

// ['A', 'B', 'C', 0, 0]

$filtered = $collection->pad(-5, 0);
$filtered->all();

// [0, 0, 'A', 'B', 'C']


</syntaxhighlight>
===<code>()partition</code>===
يمكن استعمال التابع مع الدالة <code>list</code> في PHP لتفريق العناصر التي تجتاز شرط صحة عن البقية:<syntaxhighlight lang="php">
$collection = collect([1, 2, 3, 4, 5, 6]);

list($underThree, $equalOrAboveThree) = $collection->partition(function ($i) {

   return $i < 3;
});

$underThree->all();

// [1, 2]

$equalOrAboveThree->all();

// [3, 4, 5, 6]


</syntaxhighlight>
===<code>pipe()‎</code>===
يمرّر التابع المجموعة لنداء معين ويعيد نتيجة دالة رد النداء:<syntaxhighlight lang="php">
$collection = collect([1, 2, 3]);

$piped = $collection->pipe(function ($collection) {

   return $collection->sum();
});

// 6


</syntaxhighlight>
===<code>()pluck</code>===
يسترجع التابع كل القيم من مفتاح ممرّر:<syntaxhighlight lang="php">
$collection = collect([

   ['product_id' => 'prod-100', 'name' => 'Desk'],
   ['product_id' => 'prod-200', 'name' => 'Chair'],
]);

$plucked = $collection->pluck('name');

$plucked->all();

// ['Desk', 'Chair']


</syntaxhighlight>يمكنك أيضا تحديد مفاتيح المجموعة الناتجة:<syntaxhighlight lang="php">
$plucked = $collection->pluck('name', 'product_id');

$plucked->all();

// ['prod-100' => 'Desk', 'prod-200' => 'Chair']


</syntaxhighlight>إذا وُجدت مفاتيح متشابهة، فسيضاف العنصر الأخير الموافق للمفتاح:<syntaxhighlight lang="php">
$collection = collect([

   ['brand' => 'Tesla',  'color' => 'red'],
   ['brand' => 'Pagani', 'color' => 'white'],
   ['brand' => 'Tesla',  'color' => 'black'],
   ['brand' => 'Pagani', 'color' => 'orange'],
]);

$plucked = $collection->pluck('color', 'brand');

$plucked->all();

// ['Tesla' => 'black', 'Pagani' => 'orange']


</syntaxhighlight>
===<code>()pop</code>===
يحذف التابع العنصر الأخير من المجموعة ويعيده:<syntaxhighlight lang="php">
$collection = collect([1, 2, 3, 4, 5]);

$collection->pop();

// 5

$collection->all();

// [1, 2, 3, 4]


</syntaxhighlight>
===<code>()prepend</code>===
يضيف التابع عناصر في أول المجموعة:<syntaxhighlight lang="php">
$collection = collect([1, 2, 3, 4, 5]);
$collection->prepend(0);
$collection->all();

// [0, 1, 2, 3, 4, 5]


</syntaxhighlight>يمكنك تمرير معامل ثاني لتحديد مفتاح العناصر المضافة:<syntaxhighlight lang="php">
$collection = collect(['one' => 1, 'two' => 2]);

$collection->prepend(0, 'zero');

$collection->all();

// ['zero' => 0, 'one' => 1, 'two' => 2]


</syntaxhighlight>
===<code>()pull</code>===
يحذف التابع عنصرًا من المجموعة ويعيده وذلك باستعمال مفتاحه:<syntaxhighlight lang="php">
$collection = collect(['product_id' => 'prod-100', 'name' => 'Desk']);

$collection->pull('name');

// 'Desk'

$collection->all();

// ['product_id' => 'prod-100']


</syntaxhighlight>
===<code>()push</code>===
يضيف التابع عنصرًا في آخر المجموعة:<syntaxhighlight lang="php">
$collection = collect([1, 2, 3, 4]);

$collection->push(5);

$collection->all();

// [1, 2, 3, 4, 5]


</syntaxhighlight>
===<code>()put</code>===
يضع التابع المفتاح والقيمة في المجموعة:<syntaxhighlight lang="php">
$collection = collect(['product_id' => 1, 'name' => 'Desk']);
$collection->put('price', 100);
$collection->all();

// ['product_id' => 1, 'name' => 'Desk', 'price' => 100]


</syntaxhighlight>
===<code>()random</code>===
يعيد التابع عنصرًا عشوائيًا من المجموعة:<syntaxhighlight lang="php">
$collection = collect([1, 2, 3, 4, 5]);
$collection->random();

// 4 - (retrieved randomly)


</syntaxhighlight>يمكنك اختيار تمرير عدد للتابع لتحديد عدد العناصر التي تريد إعادتها عشوائيًا. يعيد التابع مجموعة في حال تمرير عدد العناصر المطلوبة:<syntaxhighlight lang="php">
$random = $collection->random(3);

$random->all();

// [2, 4, 5] - (retrieved randomly)


</syntaxhighlight>إذا كان عدد العناصر في المجموعة أقل من المطلوب فسيُطلق التابع الاستثناء <code>InvalidArgumentException</code>.
===<code>()reduce</code>===
يقلص التابع المجموعة لعنصر واحد بتمرير نتيجة كل تكرار نداء للتكرار الموالي:<syntaxhighlight lang="php">
$collection = collect([1, 2, 3]);

$total = $collection->reduce(function ($carry, $item) {
   return $carry + $item;
});

// 6


</syntaxhighlight>قيمة <code>carry$</code> في التكرار الأول <code>null</code>، لكن بإمكانك تمرير قيمة الأولية يرجعها التابع بدل <code>null</code> كمعامل ثاني للتابع:<syntaxhighlight lang="php">
$collection->reduce(function ($carry, $item) {

   return $carry + $item;
}, 4);

// 10


</syntaxhighlight>
===<code>()reject</code>===
يُستعمل التابع لترشيح المجموعة باستعمال دالة رد نداء معينة. يجب أن تعيد دالة رد النداء القيمة <code>true</code> ليُحذف العنصر من المجموعة الناتجة:<syntaxhighlight lang="php">
$collection = collect([1, 2, 3, 4]);

$filtered = $collection->reject(function ($value, $key) {

   return $value > 2;
});

$filtered->all();

// [1, 2]


</syntaxhighlight>لعكس وظيفة <code>reject</code>، انظر التابع <code>filter</code>.
===<code>()reverse</code>===
يعكس التابع ترتيب عناصر المجموعة محافظًا على المفاتيح الأصلية:<syntaxhighlight lang="php">
$collection = collect(['a', 'b', 'c', 'd', 'e']);

$reversed = $collection->reverse();

$reversed->all();

/*

   [
       4 => 'e',
       3 => 'd',
       2 => 'c',
       1 => 'b',
       0 => 'a',
   ]
*/

</syntaxhighlight>
===<code>()search</code>===
يبحث التابع عن قيمة معينة ويعيد مفتاحها. إذا لم توجد القيمة المطلوبة فسيعيد التابع القيمة <code>false</code>:<syntaxhighlight lang="php">
$collection = collect([2, 4, 6, 8]);
$collection->search(4);

// 1


</syntaxhighlight>يقارن هذا التابع مقارنة غير صارمة أي أن سلسلةً نصيةً تحتوي على رقمٍ تعدّ مساويةً للقيمة الرقمية. لاستعمال مقارنة صارمة، مرّر <code>true</code> كمعامل ثاني إلى التابع:<syntaxhighlight lang="php">
$collection->search('4', true);

// false


</syntaxhighlight>بشكلٍ بديل، يمكنك تمرير دالة رد النداء الخاصة بك للبحث عن العنصر الأول الذي يحقق شرط الصحة الذي تحدّده:<syntaxhighlight lang="php">
$collection->search(function ($item, $key) {

   return $item > 5;
});

// 2


</syntaxhighlight>
===<code>()shift</code>===
يحذف التابع ويعيد العنصر الأول من المجموعة<syntaxhighlight lang="php">
$collection = collect([1, 2, 3, 4, 5]);

$collection->shift();

// 1

$collection->all();

// [2, 3, 4, 5]


</syntaxhighlight>
===<code>()shuffle</code>===
يخلط التابع العناصر عشوائيًا:<syntaxhighlight lang="php">
$collection = collect([1, 2, 3, 4, 5]);

$shuffled = $collection->shuffle();

$shuffled->all();

// [3, 2, 5, 1, 4] - (generated randomly) 


</syntaxhighlight>
===<code>()slice</code>===
يعيد التابع قطعة من المجموعة بدءًا من مكان محدّد:<syntaxhighlight lang="php">
$collection = collect([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
$slice = $collection->slice(4);
$slice->all();

// [5, 6, 7, 8, 9, 10]


</syntaxhighlight>إذا أردت تحديد حجم القطعة مرّر الحجم كمعامل ثاني للتابع:<syntaxhighlight lang="php">
$slice = $collection->slice(4, 2);

$slice->all();

// [5, 6]


</syntaxhighlight>تحافظ القطعة على المفاتيح الأصلية، إذا لم ترد الحفاظ عليها فاستخدم التابع <code>values</code> لإعادة تسميتها.
===<code>()sort</code>===
يُرتِّب التابع المجموعة. تحافظ المجموعة الناتجة على المفاتيح الأصلية لذا سنستعمل في المثال التابع <code>values</code> لإعادة تعيين المفاتيح لأعداد متتالية:<syntaxhighlight lang="php">
$collection = collect([5, 3, 1, 2, 4]);

$sorted = $collection->sort();

$sorted->values()->all();

// [1, 2, 3, 4, 5]


</syntaxhighlight>إذا احتجت ترتيبًا أكثر تعقيدًا، يمكنك تمرير دالة رد نداء للمنطق المتبع في طريقة الترتيب الخاصة بك. راجع توثيق الدالة <code>uasort</code> في PHP وهي طريقة الترتيب الذي يعتمدها التابع <code>sort</code> وراء الكواليس.

'''ملاحظة:''' إذا احتجت إلى ترتيب مجموعة مصفوفات متداخلة أو كائنات فراجع التابعين <code>sortBy</code> و <code>sortByDesc</code>.
===<code>()sortBy</code>===
يرتب التابع المجموعة حسب مفتاح ممرّر. تحافظ المجموعة المرتَّبة على المفاتيح الأصلية لذا في هذا المثال سنستعمل التابع values لإعادة تعيين المفاتيح لأعداد متتالية:<syntaxhighlight lang="php">
$collection = collect([

   ['name' => 'Desk', 'price' => 200],
   ['name' => 'Chair', 'price' => 100],
   ['name' => 'Bookcase', 'price' => 150],
]);

$sorted = $collection->sortBy('price');

$sorted->values()->all();

/*

   [
       ['name' => 'Chair', 'price' => 100],
       ['name' => 'Bookcase', 'price' => 150],
       ['name' => 'Desk', 'price' => 200],
   ]
*/

</syntaxhighlight>يمكنك تمرير دالة رد النداء الخاصة بك لتحديد طريقة الترتيب:<syntaxhighlight lang="php">
$collection = collect([

   ['name' => 'Desk', 'colors' => ['Black', 'Mahogany']],
   ['name' => 'Chair', 'colors' => ['Black']],
   ['name' => 'Bookcase', 'colors' => ['Red', 'Beige', 'Brown']],
]);

$sorted = $collection->sortBy(function ($product, $key) {

   return count($product['colors']);
});

$sorted->values()->all();

/*

   [
       ['name' => 'Chair', 'colors' => ['Black']],
       ['name' => 'Desk', 'colors' => ['Black', 'Mahogany']],
       ['name' => 'Bookcase', 'colors' => ['Red', 'Beige', 'Brown']],
   ]
*/

</syntaxhighlight>
===<code>()sortByDesc</code>===
هذا التابع شبيه بالتابع <code>sortBy</code> لكنه يرتب العناصر ترتيبًا معاكسًا.
===<code>()sortKeys</code>===
يرتب التابع المجموعة حسب مفاتيح المصفوفة المعالجة:<syntaxhighlight lang="php">
$collection = collect([

   'id' => 22345,
   'first' => 'John',
   'last' => 'Doe',
]);

$sorted = $collection->sortKeys();

$sorted->all();

/*

   [
       'first' => 'John',
       'id' => 22345,
       'last' => 'Doe',
   ]
*/

</syntaxhighlight>
===<code>()sortKeysDesc</code>===
هذا التابع شبيه بالتابع <code>sortKeys</code> لكنه يرتّب المجموعة ترتيبًا معاكسًا.
===<code>()splice</code>===
يحذف التابع ويعيد قطعةً من المجموعة بدءًا من موضع محدّد:<syntaxhighlight lang="php">
$collection = collect([1, 2, 3, 4, 5]);
$chunk = $collection->splice(2);
$chunk->all();

// [3, 4, 5]

$collection->all();

// [1, 2]


</syntaxhighlight>يمكنك تمرير معامل ثاني لتحديد حجم القطعة:<syntaxhighlight lang="php">
$collection = collect([1, 2, 3, 4, 5]);

$chunk = $collection->splice(2, 1);

$chunk->all();

// [3]

$collection->all();

// [1, 2, 4, 5]


</syntaxhighlight>يمكنك أيضًا تمرير معامل ثالث يحتوي عناصر جديدة لتعويض العناصر المحذوفة من المجموعة الأصلية:<syntaxhighlight lang="php">
$collection = collect([1, 2, 3, 4, 5]);
$chunk = $collection->splice(2, 1, [10, 11]);
$chunk->all();

// [3]

$collection->all();

// [1, 2, 10, 11, 4, 5]


</syntaxhighlight>
===<code>()split</code>===
يقسم التابع المجموعة لعدد ممرّر من المجموعات:<syntaxhighlight lang="php">
$collection = collect([1, 2, 3, 4, 5]);

$groups = $collection->split(3);

$groups->toArray();

// [[1, 2], [3, 4], [5]]


</syntaxhighlight>
===<code>()sum</code>===
يعيد التابع مجموع عناصر المجموعة:<syntaxhighlight lang="php">
collect([1, 2, 3, 4, 5])->sum();

// 15


</syntaxhighlight>إذا كانت المجموعة تحتوي مصفوفات متداخلة، يجب تمرير مفتاح لتحديد العناصر التي يجب جمعها:<syntaxhighlight lang="php">
$collection = collect([

   ['name' => 'JavaScript: The Good Parts', 'pages' => 176],
   ['name' => 'JavaScript: The Definitive Guide', 'pages' => 1096],
]);

$collection->sum('pages');

// 1272


</syntaxhighlight>يمكنك أيضًا تمرير دالة رد نداء خاصة بك لتحديد أي القيم ستُجمَع:<syntaxhighlight lang="php">
$collection = collect([

   ['name' => 'Chair', 'colors' => ['Black']],
   ['name' => 'Desk', 'colors' => ['Black', 'Mahogany']],
   ['name' => 'Bookcase', 'colors' => ['Red', 'Beige', 'Brown']],
]);

$collection->sum(function ($product) {

   return count($product['colors']);
});

// 6


</syntaxhighlight>
===<code>()take</code>===
يعيد التابع مجموعةً جديدةً ذاتُ عناصرٍ محددّة:<syntaxhighlight lang="php">
$collection = collect([0, 1, 2, 3, 4, 5]);
$chunk = $collection->take(3);
$chunk->all();

// [0, 1, 2]


</syntaxhighlight>يمكنك تمرير عدد سالب لأخذ عدد من العناصر من آخر المجموعة:<syntaxhighlight lang="php">
$collection = collect([0, 1, 2, 3, 4, 5]);

$chunk = $collection->take(-2);

$chunk->all();

// [4, 5]


</syntaxhighlight>
===<code>()tap</code>===
يمرّر التابع المجموعة لدالة رد نداء معيّنة. ويسمح لك بالدخول للمجموعة من نقطة محدّدة والقيام بعمل ما على العنصر دون المساس بالمجموعة ككل:<syntaxhighlight lang="php">
collect([2, 4, 3, 1, 5])

   ->sort()
   ->tap(function ($collection) {
       Log::debug('Values after sorting', $collection->values()->toArray());
   })
   ->shift();
// 1


</syntaxhighlight>
===<code>()times</code>===
يُنشِئ التابع الساكن مجموعة جديدة عبر استعمال دالة رد نداء عددًا محددًا من المرات:<syntaxhighlight lang="php">
$collection = Collection::times(10, function ($number) {

   return $number * 9;
});

$collection->all();

// [9, 18, 27, 36, 45, 54, 63, 72, 81, 90]


</syntaxhighlight>يكون هذا التابع مفيدًا عند استعماله مع المصانع لإنشاء نماذج Eloquent:<syntaxhighlight lang="php">
$categories = Collection::times(3, function ($number) {

   return factory(Category::class)->create(['name' => 'Category #'.$number]);
});

$categories->all();

/*

   [
       ['id' => 1, 'name' => 'Category #1'],
       ['id' => 2, 'name' => 'Category #2'],
       ['id' => 3, 'name' => 'Category #3'],
   ]
*/

</syntaxhighlight>
===<code>()toArray</code>===
يحوّل التابع المجموعة لمصفوفة PHP. إذا كانت مكوّنات المجموعة نماذج Eloquent، تتحوّل النماذج أيضا لمصفوفات:<syntaxhighlight lang="php">
$collection = collect(['name' => 'Desk', 'price' => 200]);

$collection->toArray();

/*

   [
       ['name' => 'Desk', 'price' => 200],
   ]
*/

</syntaxhighlight><u>تنبيه</u>: يحوّل <code>toArray</code> كل الكائنات المتداخلة في المجموعة لمصفوفات. إذا أردت الحصول على المصفوفة الخام استعمل التابع <code>all</code> بدلًا منه.
===<code>()toJson</code>===
يحوّل التابع <code>toJson</code> المجموعة لسلسلة <code>JSON</code>:<syntaxhighlight lang="php">
$collection = collect(['name' => 'Desk', 'price' => 200]);

$collection->toJson();

// '{"name":"Desk", "price":200}'


</syntaxhighlight>
===<code>()transform</code>===
يكرّر التابع <code>transform</code> عناصر المجموعة ويستعمل دالة رد نداء مع كل عنصر. يعوّض العناصر في المجموعة بنتائج النداءات:<syntaxhighlight lang="php">
$collection = collect([1, 2, 3, 4, 5]);

$collection->transform(function ($item, $key) {

   return $item * 2;
});

$collection->all();

// [2, 4, 6, 8, 10]


</syntaxhighlight><u>تنبيه</u>: على عكس أغلب توابع المجموعات، يغيّر التابع المجموعة الأصلية. إذا أردت إنشاء مجموعة جديدة فاستعمل التابع <code>map</code> بدلًا منه.
===<code>()union</code>===
يضيف التابع المصفوفة الممرّرة للمجموعة. إذا احتوت المصفوفة مفاتيح موجودة في المجموعة الأصلية، فستُفضَّل قيم المجموعة الأصلية:<syntaxhighlight lang="php">
$collection = collect([1 => ['a'], 2 => ['b']]);

$union = $collection->union([3 => ['c'], 1 => ['b']]);

$union->all();

// [1 => ['a'], 2 => ['b'], 3 => ['c']]


</syntaxhighlight>
===<code>()unique</code>===
يعيد التابع قيمة فريدة في المجموعة. تحتفظ مجموعة النتيجة بالمفاتيح الأصلية لذا في هذا المثال سنستعمل التابع <code>values</code> لإعادة تعيين المفاتيح لأعداد متتالية:<syntaxhighlight lang="php">
$collection = collect([1, 1, 2, 2, 3, 4, 2]);

$unique = $collection->unique();

$unique->values()->all();

// [1, 2, 3, 4]


</syntaxhighlight>عند العمل مع المصفوفات المتداخلة أو الكائنات، يمكن تحديد المفتاح المستعمل لتحديد الفرادة:<syntaxhighlight lang="php">
$collection = collect([

   ['name' => 'iPhone 6', 'brand' => 'Apple', 'type' => 'phone'],
   ['name' => 'iPhone 5', 'brand' => 'Apple', 'type' => 'phone'],
   ['name' => 'Apple Watch', 'brand' => 'Apple', 'type' => 'watch'],
   ['name' => 'Galaxy S6', 'brand' => 'Samsung', 'type' => 'phone'],
   ['name' => 'Galaxy Gear', 'brand' => 'Samsung', 'type' => 'watch'],
]);

$unique = $collection->unique('brand');

$unique->values()->all();

/*

   [
       ['name' => 'iPhone 6', 'brand' => 'Apple', 'type' => 'phone'],
       ['name' => 'Galaxy S6', 'brand' => 'Samsung', 'type' => 'phone'],
   ]
*/

</syntaxhighlight>يمكنك أيضا تمرير دالة رد النداء الخاصة بك لتحديد الفرادة:<syntaxhighlight lang="php">
$unique = $collection->unique(function ($item) {

   return $item['brand'].$item['type'];
});

$unique->values()->all();

/*

   [
       ['name' => 'iPhone 6', 'brand' => 'Apple', 'type' => 'phone'],
       ['name' => 'Apple Watch', 'brand' => 'Apple', 'type' => 'watch'],
       ['name' => 'Galaxy S6', 'brand' => 'Samsung', 'type' => 'phone'],
       ['name' => 'Galaxy Gear', 'brand' => 'Samsung', 'type' => 'watch'],
   ]
*/

</syntaxhighlight>يستعمل التابع مقارنة غير صارمة أي أن السلاسل النصية التي تحتوي رقمًا تعدّ مساويةً لعددٍ له القيمة الرقمية. استعمل التابع <code>uniqueStrict</code> لمقارنةٍ أكثر صرامةً.
===<code>()uniqueStrict</code>===
هذا التابع شبيه بالتابع <code>unique</code> لكنه يستعمل مقارنةً صارمةً.
===<code>()unless</code>===
ينفذ التابع دالة رد النداء الممرَّرة إلا في حالة كان المعامل الأول الممرّر <code>true</code>:<syntaxhighlight lang="php">
$collection = collect([1, 2, 3]);

$collection->unless(true, function ($collection) {

   return $collection->push(4);
});

$collection->unless(false, function ($collection) {

   return $collection->push(5);
});

$collection->all();

// [1, 2, 3, 5]


</syntaxhighlight>لعكس وظيفة التابع استعمل التابع <code>when</code>.
===<code>()unwrap</code>===
يعيد التابع عناصر المجموعة من القيم الممرّرة عند إمكانية التطبيق:<syntaxhighlight lang="php">
Collection::unwrap(collect('John Doe'));

// ['John Doe']

Collection::unwrap(['John Doe']);

// ['John Doe']

Collection::unwrap('John Doe');

// 'John Doe'


</syntaxhighlight>
===<code>()values</code>===
يعيد التابع مجموعةً جديدةً مع إعادة ضبط المفاتيح لأعداد متتالية:<syntaxhighlight lang="php">
Collection::unwrap(collect('John Doe'));

// ['John Doe']

Collection::unwrap(['John Doe']);

// ['John Doe']

Collection::unwrap('John Doe');

// 'John Doe'


</syntaxhighlight>
===<code>()when</code>===
ينفذّ التابع النداء الممرّر عندما تكون قيمة المعامل الأول <code>true</code>:<syntaxhighlight lang="php">
$collection = collect([1, 2, 3]);
$collection->when(true, function ($collection) {

   return $collection->push(4);
});

$collection->when(false, function ($collection) {

   return $collection->push(5);
});

$collection->all();

// [1, 2, 3, 4]


</syntaxhighlight>لعكس وظيفة <code>when</code> استعمل التابع <code>unless</code>.
===<code>()where</code>===
يرشِّح التابع المجموعة عبر الزوج المفتاح/القيمة الممرّر:<syntaxhighlight lang="php">
$collection = collect([

   ['product' => 'Desk', 'price' => 200],
   ['product' => 'Chair', 'price' => 100],
   ['product' => 'Bookcase', 'price' => 150],
   ['product' => 'Door', 'price' => 100],
]);

$filtered = $collection->where('price', 100);

$filtered->all();

/*

   [
       ['product' => 'Chair', 'price' => 100],
       ['product' => 'Door', 'price' => 100],
   ]
*/

</syntaxhighlight>يستعمل التابع مقارنة غير صارمة أي أن السلاسل النصية التي تحتوي رقمًا تعدّ مساويةً لعدد بنفس القيمة الرقمية. استعمل التابع <code>whereStrict</code> لمقارنةٍ أكثر صرامةً.
===<code>()whereStrict</code>===
يشبه هذا التابع عمل <code>where</code> لكنه يستعمل مقارنةً صارمةً.
===<code>()whereIn</code>===
يرشِّح التابع المجموعة عبر الزوج المفتاح\القيمة المحتواة في المصفوفة الممرّرة:<syntaxhighlight lang="php">
$collection = collect([

   ['product' => 'Desk', 'price' => 200],
   ['product' => 'Chair', 'price' => 100],
   ['product' => 'Bookcase', 'price' => 150],
   ['product' => 'Door', 'price' => 100],
]);

$filtered = $collection->whereIn('price', [150, 200]);

$filtered->all();

/*

   [
       ['product' => 'Bookcase', 'price' => 150],
       ['product' => 'Desk', 'price' => 200],
   ]
*/

</syntaxhighlight>يستعمل التابع مقارنة غير صارمة أي أن السلاسل النصية التي تحتوي رقمًا تعدّ مساويةً لعددٍ بنفس القيمة الرقمية. استعمل التابع <code>whereInStrict</code> لمقارنةٍ أكثر صرامةً.
===<code>()whereInStrict</code>===
يشبه هذا التابع عمل <code>whereIn</code> لكنه يستعمل مقارنةً صارمة.
===<code>()whereInstanceOf</code>===
يرشِّح التابع المجموعة حسب صنف ممرّر:<syntaxhighlight lang="php">
$collection = collect([

   new User,
   new User,
   new Post,
]);

return $collection->whereInstanceOf(User::class);


</syntaxhighlight>
===<code>()whereNotIn</code>===
يرشِّح التابع المجموعة حسب زوج المفتاح/القيمة غير مجموعة في المصفوفة الممرّرة:<syntaxhighlight lang="php">
$collection = collect([

   ['product' => 'Desk', 'price' => 200],
   ['product' => 'Chair', 'price' => 100],
   ['product' => 'Bookcase', 'price' => 150],
   ['product' => 'Door', 'price' => 100],
]);

$filtered = $collection->whereNotIn('price', [150, 200]);

$filtered->all();

/*

   [
       ['product' => 'Chair', 'price' => 100],
       ['product' => 'Door', 'price' => 100],
   ]
*/

</syntaxhighlight>يستعمل التابع مقارنة غير صارمة أي أن السلاسل النصية التي تحتوي رقمًا تعدّ مساويةً لعددٍ بنفس القيمة الرقمية. استعمل التابع <code>whereNotInStrict</code> لمقارنةٍ أكثر صرامة.
===<code>()whereNotInStrict</code>===
يشبه هذا التابع عمل <code>whereNotIn</code> لكنه يستعمل مقارنةً صارمةً.
===<code>()wrap</code>===
يغلِّف التابع الثابت القيمة في مجموعة عند تطبيقه:<syntaxhighlight lang="php">
$collection = Collection::wrap('John Doe');

$collection->all();

// ['John Doe']

$collection = Collection::wrap(['John Doe']);

$collection->all();

// ['John Doe']

$collection = Collection::wrap(collect('John Doe'));

$collection->all();

// ['John Doe']


</syntaxhighlight>
===<code>()zip</code>===
يدمج التابع <code>zip</code> قيم المصفوفات الممرّرة في المواضع المناسبة:<syntaxhighlight lang="php">
$collection = collect(['Chair', 'Desk']);

$zipped = $collection->zip([100, 200]);

$zipped->all();

// [['Chair', 100], ['Desk', 200]]


</syntaxhighlight>
==الرسائل ذات الترتيب العالي==
توفّر المجموعات دعمًا للرسائل ذات الترتيب العالي (higher order messages)، وهي طرق مختصرة لتنفيذ أعمال شائعة على المجموعات. التوابع التي توفر رسائل ذات ترتيب عالي هي: <code>average</code> و <code>avg</code> و <code>contains</code> و <code>each</code> و <code>every</code> و <code>filter</code> و <code>first</code> و <code>flatMap</code> و <code>groupBy</code> و <code>keyBy</code> و <code>map</code> و <code>max</code> و <code>min</code> و <code>partition</code> و <code>reject</code> و <code>sortBy</code> و <code>sortByDesc</code> و <code>sum</code> و <code>unique</code>.

يمكن الوصول لكل رسالة ذات ترتيب عالي كخاصية ديناميكية لكائن المجموعة. مثلًا، لنستعمل رسائل التابع <code>each</code> لنداء تابع مع كل عنصر في المجموعة:<syntaxhighlight lang="php">
$users = User::where('votes', '>', 500)->get();

$users->each->markAsVip();


</syntaxhighlight>بنفس الطريقة، يمكن استعمال رسائل <code>sum</code> لجمع أصوات (votes) مجموعة مستخدمين:<syntaxhighlight lang="php">
$users = User::where('group', 'Development')->get();

return $users->sum->votes;


</syntaxhighlight>
==مصادر==
*[https://laravel.com/docs/5.6/collections صفحة Collections في توثيق Laravel الرسمي.]<noinclude>{{DISPLAYTITLE:المجموعات (Collections) في Laravel}}</noinclude>
[[تصنيف:Laravel|{{SUBPAGENAME}}]]
[[تصنيف:Laravel Digging deeper|{{SUBPAGENAME}}]]