Laravel/collections

مقدمة

يوفر الصنف Illuminate\Support\Collection غلافًا ملائمًا و مساعدًا على العمل مع مصفوفات البيانات. مثلًا، تفقد الشيفرة الموالية إذ سنستعمل المساعد collect لإنشاء نسخة Collection جديدة من المصفوفة، ننفذ الدالة strtoupper مع كل عنصر، ثم نحذف كل العناصر الفارغة:

$collection = collect(['taylor', 'abigail', null])->map(function ($name) {
   return strtoupper($name);

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

});

كما ترى، تسمح الدالة بسلسلة توابعها لتنفيذِ تخطيطِ دقيق و التحكم في حجم المصفوفة قيد العمل. بشكل عام، المجموعات غير قابلة للتغيير، أي أن كل تابع collect يعيد نسخة من كائن مجموعة جديد تمامًا.

إنشاء المجموعات

كما ذُكر سابقًا، يعيد التابع المساعد collect نسخة من كائن Illuminate\Support\Collection جديد لكل مصفوفة. لذا، يمكننا إنشاء مجموعة بسهولة

$collection = collect([1, 2, 3]);

ملاحظة: نتائج طلبات Eloquent تكون دائمًا على شكل كائن Collection.

تمديد المجموعات

المجموعات قابلة للتمديد، مما يسمح لك بإضافة توابع أخرى للصنف Collection في وقت التشغيل. مثلًا، الشيفرة التالية تضيف التابع toUpper إلى الصنف Collection:

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']

في العادة، عليك ذكر الإضافات للصنف Collection في مزود الخدمات.

التوابع المتاحة

في بقية هذا التوثيق، سنناقش كل تابع متوافر في الصنف Collection. تذكر أنّ كل التوابع يمكن سلسلتها معًا لمعالجة المصفوفة بيسر. بالإضافة ألى ذلك، تقريبًا كل التوابع تعيد نسخة جديدة من الكائن Collection مما يحافظ على المجموعة الأصلية عند الحاجة:

• all
• isEmpty
• shuffle
• average
• isNotEmpty
• slice
• avg
• keyBy
• sort
• chunk
• keys
• sortBy
• collase
• last
• sortByDesc
• combine
• macro
• sortKeys
• concat
• make
• sortKeysDesc
• contains
• map
• splice
• containsStrict
• mapinto
• slpit
• count
• mapSpread
• sum
• crossJoin
• mapToGroups
• take
• dd
• mapWithKeys
• tap
• diff
• max
• times
• diffAssoc
• median
• toArray
• diffKeys
• merge
• toJson
• dump
• min
• transform
• each
• mode
• union
• eachSpread
• nth
• unique
• every
• only
• uniqueStrict
• except
• pad
• unless
• filter
• partition
• unwrap
• first
• pipe
• values
• firstWhere
• pluck
• when
• flatMap
• pop
• where
• flatten
• prepend
• whereStrict
• flip
• pull
• whereIn
• forget
• push
• whereInStrict
• forPage
• put
• whereInstanceOf
• get
• random
• whereNotin
• groupBy
• reduce
• whereNotinStrict
• has
• reject
• wrap
• implode
• reverse
• zip
• intersect

• search
• intersectByKeys

• shift

لائحة التوابع

()all

يعيد التابع all المصفوفة المقصودة على شكل مجموعة:

collect([1, 2, 3])->all();
// [1, 2, 3]

()average

اسم بديل للتابع avg.

()avg

يعيد التابع avg قيمة المتوسط الحسابي للمفتاح الممرّر:

$average = collect([['foo' => 10], ['foo' => 10], ['foo' => 20], ['foo' => 40]])->avg('foo');
// 20

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

()chunk

يقسم التابع chunk المجموعة لعدة مجموعات أصغر بحجم معين:

$collection = collect([1, 2, 3, 4, 5, 6, 7]);
$chunks = $collection->chunk(4);
$chunks->toArray();

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

هذا التابع مفيد خاصة في الواجهات عند العمل مع نظام شبكي "grid" مثل Bootstrap. تخيل أنك تريد عرض مجموعة من نماذج Eloquent في شبكة:

@foreach ($products->chunk(3) as $chunk)

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

()collapse

يُسقط التابع collapse مجموعة من المصفوفات في مجموعة واحدة ذات بعد واحد:

$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]

()combine

يدمج التابع combine مفاتيح المجموعة مع قيم من مجموعة أو مصفوفة أخرى:

$collection = collect(['name', 'age']);
$combined = $collection->combine(['George', 29]);
$combined->all();

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

()concat

يضيف التابع concat المصفوفة الممررة أو قيم المجموعة المُمَرَّرة لآخر المجموعة:

$collection = collect(['John Doe']);
$concatenated = $collection->concat(['Jane Doe'])->concat(['name' => 'Johnny Doe']);
$concatenated->all();

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

()contains

يحدد التابع contains إذا كانت المجموعة تحتوي على عنصرٍ محدِّد أم لا:

$collection = collect(['name' => 'Desk', 'price' => 100]);
$collection->contains('Desk');

// true

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

// false

يمكنك أيضًا تمرير زوجٍ من المفتاح/القيمة إلى التابع الذي سيحدد إذا كان الثنائي موجودًا أم لا:

$collection = collect([

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

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

// false

أخيرًا، يمكنك تمرير دالة رد نداء إلى التابع contains لتقوم بعملية التحقق من وجود القيمة بنفسك:

$collection = collect([1, 2, 3, 4, 5]);
$collection->contains(function ($value, $key) {

   return $value > 5;
});

// false

يقوم التابع بمقارنة بسيطة، أي أن سلسلة المحارف التي تحتوي على رقم تُعدّ مساويةً لعدد صحيحٍ بنفس القيمة الرقمية. استعمل التابع containsStrict لمقارنة أكثر صرامةً.

()containsStrict

نفس الوظيفة التابع contains لكنها تستعمل مقارنةً صارمةً (strict).

()count

يعيد التابع count عدد عناصر المجموعة:

$collection = collect([1, 2, 3, 4]);
$collection->count();

// 4

()crossJoin

يقوم التابع بوصل تقاطعي بين قيم المجموعة والمصفوفة الممرّرة، ويعيد جداءً ديكارتيًا بكل المبادلات الممكنة:

$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'],
    ]
*/

()dd

يطبع التابع dd عناصر المجموعة وينهي تنفيذ السكربت:

$collection = collect(['John Doe', 'Jane Doe']);

$collection->dd();

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

إذا لم ترد إنهاء السكربت، فاستعمل التابع dump بدلًا من dd.

()diff

يقارن التابع diff المجموعة بمجموعة أخرى أو بمصفوفة PHP عادية اعتمادًا على قيمها. يعيد هذا التابع قيم المجموعة الأصلية غير الموجودة في المجموعة الممرّرة:

$collection = collect([1, 2, 3, 4, 5]);
$diff = $collection->diff([2, 4, 6, 8]);
$diff->all();

// [1, 3, 5]

()diffAssoc

يقارن التابع diffAssoc المجموعة بمجموعة أخرى أو بمصفوفة 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]

()diffKeys

يقارن هذا التابع المجموعة بمجموعة أخرى أو بمصفوفة 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]

()dump

يطبع التابع dump عناصر المجموعة:

$collection = collect(['John Doe', 'Jane Doe']);

$collection->dump();

/*

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

إذا أردت إيقاف تنفيذ السكربت بعد تفريغ المجموعة فاستعمل التابع dd.

()each

يكرّر التابع each عناصر المجموعة واحدًا بواحد ويمرّرها لدالة رد نداء:

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

  //
});

إذا أردت إيقاف التكرار، أعد القيمة false من دالة رد النداء:

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

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

()eachSpread

يكرّّر التابع eachSpread عناصر المجموعة ويمرّر كل عنصر متداخل لدالة رد النداء:

$collection = collect([['John Doe', 35], ['Jane Doe', 33]]);

$collection->eachSpread(function ($name, $age) {

  //
});

يمكنك إيقاف التكرار بإعادة القيمة false من دالة رد النداء.

$collection->eachSpread(function ($name, $age) {

   return false;
});

()every

يمكن استعمال التابع every للتأكد من أن كل عناصر المجموعة تحقق شرطًا معينًا:

collect([1, 2, 3, 4])->every(function ($value, $key) {

   return $value > 2;
});

// false

()except

يعيد التابع except كل عناصر المجموعة باستثناء العناصر بالمفاتيح المحدَّدة:

$collection = collect(['product_id' => 1, 'price' => 100, 'discount' => false]);
$filtered = $collection->except(['price', 'discount']);
$filtered->all();

// ['product_id' => 1]

لعكس وظيفة except، انظر التابع only.

()filter

يرشِّح التابع filter عناصر المجموعة ويُبقي فقط العناصر التي تحقق شرطًا معينًا:

$collection = collect([1, 2, 3, 4]);
$filtered = $collection->filter(function ($value, $key) {

   return $value > 2;
});

$filtered->all();

// [3, 4]

إذا لم توفّر نداء للتابع، يحذف filter كل العناصر المساوية للقيمة false:

$collection = collect([1, 2, 3, null, false, , 0, []]);
$collection->filter()->all();

// [1, 2, 3]

لعكس وظيفة filter انظر التابع reject.

()first

يرجع التابع first العنصر الأول من المجموعة الذي يحقق شرطًا معينًا:

collect([1, 2, 3, 4])->first(function ($value, $key) {

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

يمكنك أيضًا استدعاء التابع first دون معامل، وسيعيد العنصر الأول من المجموعة، وإذا كانت المجموعة فارغةً، فستعاد القيمة null:

collect([1, 2, 3, 4])->first();

// 1

()firstWhere

يعيد التابع firstWhere العنصر الأول من المجموعة الموافق لزوج المفتاح/القيمة الممرّر:

$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]

يمكن أيضًا استعمال التابع مع عامل مقارنة:

$collection->firstWhere('age', '>=', 18);

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

()flatMap

ينفذ التابع flatMap حلقة تكرار في المجموعة، فيمرر قيمة كل تكرار لنداء معين. يمكن للنداء تغيير العنصر وإرجاعه وبالتالي يكوّن مجموعةً جديدة من العناصر المغيَّرة. ثم تُسطَّح المجموعة حسب مستواها:

$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'];

()flatten

يُسطِّح التابع flatten مجموعة متعددة الأبعاد لمجموعة ذات بعد واحد:

$collection = collect(['name' => 'taylor', 'languages' => ['php', 'javascript']]);
$flattened = $collection->flatten();
$flattened->all();

// ['taylor', 'php', 'javascript'];

يمكنك أيضًا تمرير معامل لضبط عمق التسطيح:

$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'],
   ]

في هذا المثال، سيتسبب عدم توفير عمق في تسطيح المصفوفات الداخلية لتصبح النتيجة ['iPhone 6S', 'Apple', 'Galaxy S7', 'Samsung']. مما يوفّر مستوى عمق يسمح بتحديد مستوى التداخل الذي سيتم تسطيحه.

()flip

يُبدِّل التابع flip المفتاح بقيمته:

$collection = collect(['name' => 'taylor', 'framework' => 'laravel']);
$flipped = $collection->flip();
$flipped->all();

// ['taylor' => 'name', 'laravel' => 'framework']

()forget

يحذف التابع forget عنصرًا من المجموعة باستخدام مفتاحه:

$collection = collect(['name' => 'taylor', 'framework' => 'laravel']);
$collection->forget('name');
$collection->all();

// ['framework' => 'laravel']

تنبيه: على عكس جل توابع المجموعات، لا يعيد forget مجموعةً جديدةً بل يغيّر في المجموعة التي استدعي هذا التابع عليها.

()forPage

يعيد التابع forPage مجموعة تحتوي العناصر الموجودة في رقم الصفحة الممرّر. يقبل التابع رقم صفحة كمعامل أول وعدد العناصر التي يجب إظهارها في الصفحة كمعامل ثاني:

$collection = collect([1, 2, 3, 4, 5, 6, 7, 8, 9]);
$chunk = $collection->forPage(2, 3);
$chunk->all();

// [4, 5, 6]

()get

يعيد التابع get قيمة العنصر ذي المفتاح المُمرَّر إلى التابع. إذا كان المفتاح غير موجود فستعاد القيمة null:

$collection = collect(['name' => 'taylor', 'framework' => 'laravel']);
$value = $collection->get('name');

// taylor

يمكنك تمرير قيمة أولية اختيارية كمعامل ثاني:

$collection = collect(['name' => 'taylor', 'framework' => 'laravel']);
$value = $collection->get('foo', 'default-value');

// default-value

يمكنك حتى تمرير دالة رد نداء. تُعاد القيمة المُعادة من دالة رد النداء في حال عدم وجود المفتاح:

$collection->get('email', function () {

   return 'default-value';
});

// default-value

()groupBy

يُجمِّع التابع groupBy العناصر حسب قيمة المفتاح الممرّر إلى التابع:

$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'],
      ],
   ]
*/

بدل تمرير سلسلة محارف key، يمكنك تمرير دالة رد نداء التي يجب أن تعيد القيمة التي تريد أن تكون مفتاح التجميع:

$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'],
       ],
   ]
*/

يمكن تمرير عدة معايير تجميع كمصفوفة، يُطبّق كل عنصر من المصفوفة على مستوى العمق الملائم في مصفوفة متعددة الأبعاد:

$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']],
       ],
   ],
];

*/

()has

يحدد التابع has إذا كان المفتاح موجودًا في المجموعة أم لا:

$collection = collect(['account_id' => 1, 'product' => 'Desk']);
$collection->has('product');

// true

()implode

يضم التابع implode عناصر المجموعة في سلسلة حرفية. تعتمد التوابع على نوع العناصر في المجموعة. إذا كانت المجموعة تحتوي مصفوفات أو كائنات، يجب تمرير مفتاح الخاصيات التي تريد ضمّها وعلامة الربط "glue" الذي تريد استعماله بين القيم:

$collection = collect([

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

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

// Desk, Chair

إذا كانت المجموعة تحتوي سلاسل نصية أو قيمًا رقميةً بسيطةً، فمرّر علامة الربط فقط كمعامل إلى التابع:

collect([1, 2, 3, 4, 5])->implode('-');

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

()intersect

يحذف التابع intersect أي قيمة في المجموعة الأصلية غير موجودة في المجموعة أو المصفوفة الممرّرة. تحافظ المجموعة النهائية على مفاتيح المجموعة الأصلية:

$collection = collect(['Desk', 'Sofa', 'Chair']);
$intersect = $collection->intersect(['Desk', 'Chair', 'Bookcase']);
$intersect->all();

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

()intersectByKeys

يحذف التابع أي مفتاح من المجموعة الأصلية غير موجود في المجموعة أو المصفوفة الممرّرة:

$collection = collect([

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

$intersect = $collection->intersectByKeys([

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

$intersect->all();

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

()isEmpty

يعيد التابع isEmpty القيمة true إذا كانت المجموعة فارغة وإلا فسيعيد false:

collect([])->isEmpty();

// true

()isNotEmpty

يعيد التابع isNotEmpty القيمة true إذا لم تكن المجموعة فارغة، وإلا فسيعيد false:

collect([])->isNotEmpty();

// false

()keyBy

يضيف التابع keyBy مفاتيح للمجموعة، إذا وُجد أكثر من عنصر بنفس المفتاح، فسيضاف الأخير فقط إلى المجموعة الجديدة:

$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'],
   ]
*/

يمكنك تمرير نداء للتابع. يجب أن يعيد النداء القيمة التي ستستعمل كمفتاح للمجموعة:

$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'],
   ]
*/

()keys

يعيد التابع مجموعة متكونة من كل المفاتيح:

$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']

()last

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

: collect([1, 2, 3, 4])->last();

// 4

()macro

يسمح التابع الثابت macro بإضافة توابع للصنف Collection في وقت التشغيل. راجع التوثيق حول تمديد المجموعات لمزيد من المعلومات.

()make

يُنشِئ التابع الساكن make نسخة مجموعة جديدة. راجع قسم إنشاء المجموعات.

()map

يكرّر التابع عناصر المجموعة و يمرّر كل قيمة لدالة رد نداء معيّنة. يمكن لدالة رد اللنداء تغيير العنصر وإعادته، وبالتالي تكوين مجموعة جديدة من العناصر المغيّرة:

$collection = collect([1, 2, 3, 4, 5]);

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

   return $item * 2;
});

$multiplied->all();

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

تنبيه: كأغلب توابع المجموعات، يعيد map مجموعة جديدة ولا يغير المجموعة الأصلية. إذا أردت تغيير المجموعة الأصلية فاستعمل التابع transform.

()mapInfo

يكرّر التابع mapInfo المجموعة وينشِئ نسخةً جديدةً من صنف معين عبر تمرير القيمة للتابع الباني للصنف:

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')]

()mapSpread

يكرّر التابع عناصر المجموعة ويمرّر كل عنصر متداخل لدالة رد نداء. يمكن لدالة رد النداء تغيير العنصر وإعادته، وبالتالي تكوين مجموعة جديدة من العناصر المغيرة:

$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]

()mapToGroups

يُجمّع التابع mapToGroups عناصر المجموعة باستخدام دالة رد النداء المعيّنة. تعيد دالة رد النداء مصفوفة تجميعية تحتوي زوج المفتاح/القيمة واحد، وبالتالي تكوين مجموعة من القيم المجمَّعة:

$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']

()mapWithKeys

يكرّر التابع mapWithKeys المجموعة ويمرّر القيم لدالة رد نداء معيّنة. يعيد التابع مصفوفة تجميعية تحتوي زوج المفتاح/القيمة واحد:

$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',
   ]
*/

()max

يعيد التابع القيمة القصوى في لمفتاح معين:

$max = collect([['foo' => 10], ['foo' => 20]])->max('foo');

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

()median

يعيد التابع median القيمة الوسطية للمفتاح المعين:

$median = collect([['foo' => 10], ['foo' => 10], ['foo' => 20], ['foo' => 40]])->median('foo');

// 15

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

// 1.5

()merge

يدمج التابع merge المصفوفة أو المجموعة الممرّرة مع المجموعة الأصلية، تلغي القيم الممرّرة القيم الأصلية:

$collection = collect(['product_id' => 1, 'price' => 100]);

$merged = $collection->merge(['price' => 200, 'discount' => false]);

$merged->all();

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

إذا كانت المفاتيح الممرّرة رقمية، تضاف القيم في آخر المجموعة:

$collection = collect(['Desk', 'Chair']);

$merged = $collection->merge(['Bookcase', 'Door']);

$merged->all();

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

()min

يعيد التابع min القيمة الأصغر لمفتاح معين:

$min = collect([['foo' => 10], ['foo' => 20]])->min('foo');

// 10

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

// 1

()mode

يعيد التابع قيمة المنوال لمفتاح معين:

$mode = collect([['foo' => 10], ['foo' => 10], ['foo' => 20], ['foo' => 40]])->mode('foo');

// [10]

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

// [1]

()nth

ينشِئ التابع nth مجموعةً جديدةً متكونةً من كل عنصر بعد n عناصر

$collection = collect(['a', 'b', 'c', 'd', 'e', 'f']);

$collection->nth(4);

// ['a', 'e']

يمكنك تمرير موضع البداية كمعامل ثاني:

$collection->nth(4, 1);

// ['b', 'f']

()only

يعيد التابع only العناصر في المجموعة ذات المفاتيح الممرّرة:

$collection->nth(4, 1);

// ['b', 'f']

لعكس وظيفة only، استعمل التابع expect.

()pad

يملأ التابع pad المصفوفة بالقيمة الممرّرة حتى تصل للحجم المحدد. يشبه هذا التابع دالة array_pad في 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']

()partition

يمكن استعمال التابع partition مع الدالة list في 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]

pipe()‎

يمرّر التابع pipe المجموعة لنداء معين ويعيد نتيجة دالة رد النداء:

$collection = collect([1, 2, 3]);

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

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

// 6

()pluck

يسترجع التابع pluck كل القيم من مفتاح ممرّر:

$collection = collect([

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

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

$plucked->all();

// ['Desk', 'Chair']

يمكنك أيضا تحديد مفاتيح المجموعة الناتجة:

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

$plucked->all();

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

إذا وُجدت مفاتيح متشابهة، فسيضاف العنصر الأخير الموافق للمفتاح:

$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']

()pop

يحذف التابع pop العنصر الأخير من المجموعة ويعيده:

$collection = collect([1, 2, 3, 4, 5]);

$collection->pop();

// 5

$collection->all();

// [1, 2, 3, 4]

()prepend

يضيف التابع prepend عناصر في أول المجموعة:

$collection = collect([1, 2, 3, 4, 5]);

$collection->prepend(0);

$collection->all();

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

يمكنك تمرير معامل ثاني لتحديد مفتاح العناصر المضافة:

$collection = collect(['one' => 1, 'two' => 2]);

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

$collection->all();

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

()pull

يحذف التابع pull عنصرًا من المجموعة ويعيده وذلك باستعمال مفتاحه:

$collection = collect(['product_id' => 'prod-100', 'name' => 'Desk']);

$collection->pull('name');

// 'Desk'

$collection->all();

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

()push

يضيف التابع عنصرًا في آخر المجموعة:

$collection = collect([1, 2, 3, 4]);

$collection->push(5);

$collection->all();

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

()put

يضع التابع put المفتاح والقيمة في المجموعة:

$collection = collect(['product_id' => 1, 'name' => 'Desk']);

$collection->put('price', 100);

$collection->all();

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

()random

يعيد التابع عنصرًا عشوائيًا من المجموعة:

$collection = collect([1, 2, 3, 4, 5]);

$collection->random();

// 4 - (retrieved randomly)

يمكنك اختيار تمرير عدد للتابع لتحديد عدد العناصر التي تريد إعادتها عشوائيًا. يعيد التابع مجموعة في حال تمرير عدد العناصر المطلوبة:

$random = $collection->random(3);

$random->all();

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

إذا كان عدد العناصر في المجموعة أقل من المطلوب فسيُطلق التابع الاستثناء InvalidArgumentException.

()reduce

يقلص التابع المجموعة لعنصر واحد بتمرير نتيجة كل تكرار نداء للتكرار الموالي:

$collection = collect([1, 2, 3]);

$total = $collection->reduce(function ($carry, $item) {

   return $carry + $item;
});

// 6

قيمة carry$ في التكرار الأول null، لكن بإمكانك تمرير قيمة الأولية يرجعها التابع بدل null كمعامل ثاني للتابع:

$collection->reduce(function ($carry, $item) {

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

// 10

()reject

يُستعمل التابع reject لترشيح المجموعة باستعمال دالة رد نداء معينة. يجب أن تعيد دالة رد النداء القيمة true ليُحذف العنصر من المجموعة الناتجة:

$collection = collect([1, 2, 3, 4]);

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

   return $value > 2;
});

$filtered->all();

// [1, 2]

لعكس وظيفة reject، انظر التابع filter.

()reverse

يعكس التابع ترتيب عناصر المجموعة محافظًا على المفاتيح الأصلية:

$collection = collect(['a', 'b', 'c', 'd', 'e']);

$reversed = $collection->reverse();

$reversed->all();

/*

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

()search

يبحث التابع عن قيمة معينة ويعيد مفتاحها. إذا لم توجد القيمة المطلوبة فسيعيد التابع القيمة false:

$collection = collect([2, 4, 6, 8]);

$collection->search(4);

// 1

يقارن هذا التابع مقارنة غير صارمة أي أن سلسلةً نصيةً تحتوي على رقمٍ تعدّ مساويةً للقيمة الرقمية. لاستعمال مقارنة صارمة، مرّر true كمعامل ثاني إلى التابع:

$collection->search('4', true);

// false

بشكلٍ بديل، يمكنك تمرير دالة رد النداء الخاصة بك للبحث عن العنصر الأول الذي يحقق شرط الصحة الذي تحدّده:

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

   return $item > 5;
});

// 2

()shift

يحذف التابع ويعيد العنصر الأول من المجموعة

$collection = collect([1, 2, 3, 4, 5]);

$collection->shift();

// 1

$collection->all();

// [2, 3, 4, 5]

()shuffle

يخلط التابع العناصر عشوائيًا:

$collection = collect([1, 2, 3, 4, 5]);

$shuffled = $collection->shuffle();

$shuffled->all();

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

()slice

يعيد التابع قطعة من المجموعة بدءًا من مكان محدّد:

$collection = collect([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);

$slice = $collection->slice(4);

$slice->all();

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

إذا أردت تحديد حجم القطعة مرّر الحجم كمعامل ثاني للتابع:

$slice = $collection->slice(4, 2);

$slice->all();

// [5, 6]

تحافظ القطعة على المفاتيح الأصلية، إذا لم ترد الحفاظ عليها فاستخدم التابع values لإعادة تسميتها.

()sort

يُرتِّب التابع sort المجموعة. تحافظ المجموعة الناتجة على المفاتيح الأصلية لذا سنستعمل في المثال التابع values لإعادة تعيين المفاتيح لأعداد متتالية:

$collection = collect([5, 3, 1, 2, 4]);

$sorted = $collection->sort();

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

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

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

ملاحظة: إذا احتجت إلى ترتيب مجموعة مصفوفات متداخلة أو كائنات فراجع التابعين sortBy و sortByDesc.

()sortBy

يرتب التابع المجموعة حسب مفتاح ممرّر. تحافظ المجموعة المرتَّبة على المفاتيح الأصلية لذا في هذا المثال سنستعمل التابع values لإعادة تعيين المفاتيح لأعداد متتالية:

$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],
   ]
*/

يمكنك تمرير دالة رد النداء الخاصة بك لتحديد طريقة الترتيب:

$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']],
   ]
*/

()sortByDesc

هذا التابع شبيه بالتابع sortBy لكنه يرتب العناصر ترتيبًا معاكسًا.

()sortKeys

يرتب التابع المجموعة حسب مفاتيح المصفوفة المعالجة:

$collection = collect([

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

$sorted = $collection->sortKeys();

$sorted->all();

/*

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

()sortKeysDesc

هذا التابع شبيه بالتابع sortKeys لكنه يرتّب المجموعة ترتيبًا معاكسًا.

()splice

يحذف التابع splice ويعيد قطعةً من المجموعة بدءًا من موضع محدّد:

$collection = collect([1, 2, 3, 4, 5]);

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

$chunk->all();

// [3, 4, 5]

$collection->all();

// [1, 2]

يمكنك تمرير معامل ثاني لتحديد حجم القطعة:

$collection = collect([1, 2, 3, 4, 5]);

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

$chunk->all();

// [3]

$collection->all();

// [1, 2, 4, 5]

يمكنك أيضًا تمرير معامل ثالث يحتوي عناصر جديدة لتعويض العناصر المحذوفة من المجموعة الأصلية:

$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]

()split

يقسم التابع المجموعة لعدد ممرّر من المجموعات:

$collection = collect([1, 2, 3, 4, 5]);

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

$groups->toArray();

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

()sum

يعيد التابع مجموع عناصر المجموعة:

collect([1, 2, 3, 4, 5])->sum();

// 15

إذا كانت المجموعة تحتوي مصفوفات متداخلة، يجب تمرير مفتاح لتحديد العناصر التي يجب جمعها:

$collection = collect([

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

$collection->sum('pages');

// 1272

يمكنك أيضًا تمرير دالة رد نداء خاصة بك لتحديد أي القيم ستُجمَع:

$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

()take

يعيد التابع take مجموعةً جديدةً ذاتُ عناصرٍ محددّة:

$collection = collect([0, 1, 2, 3, 4, 5]);

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

$chunk->all();

// [0, 1, 2]

يمكنك تمرير عدد سالب لأخذ عدد من العناصر من آخر المجموعة:

$collection = collect([0, 1, 2, 3, 4, 5]);

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

$chunk->all();

// [4, 5]

()tap

يمرّر التابع tap المجموعة لدالة رد نداء معيّنة. ويسمح لك بالدخول للمجموعة من نقطة محدّدة والقيام بعمل ما على العنصر دون المساس بالمجموعة ككل:

collect([2, 4, 3, 1, 5])

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

()times

يُنشِئ التابع الساكن times مجموعة جديدة عبر استعمال دالة رد نداء عددًا محددًا من المرات:

$collection = Collection::times(10, function ($number) {

   return $number * 9;
});

$collection->all();

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

يكون هذا التابع مفيدًا عند استعماله مع المصانع لإنشاء نماذج Eloquent:

$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'],
   ]
*/

()toArray

يحوّل التابع toArray المجموعة لمصفوفة PHP. إذا كانت مكوّنات المجموعة نماذج Eloquent، تتحوّل النماذج أيضا لمصفوفات:

$collection = collect(['name' => 'Desk', 'price' => 200]);

$collection->toArray();

/*

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

تنبيه: يحوّل toArray كل الكائنات المتداخلة في المجموعة لمصفوفات. إذا أردت الحصول على المصفوفة الخام استعمل التابع all بدلًا منه.

()toJson

يحوّل التابع toJson المجموعة لسلسلة JSON:

$collection = collect(['name' => 'Desk', 'price' => 200]);

$collection->toJson();

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

()transform

يكرّر التابع transform عناصر المجموعة ويستعمل دالة رد نداء مع كل عنصر. يعوّض العناصر في المجموعة بنتائج النداءات:

$collection = collect([1, 2, 3, 4, 5]);

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

   return $item * 2;
});

$collection->all();

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

تنبيه: على عكس أغلب توابع المجموعات، يغيّر التابع المجموعة الأصلية. إذا أردت إنشاء مجموعة جديدة فاستعمل التابع map بدلًا منه.

()union

يضيف التابع union المصفوفة الممرّرة للمجموعة. إذا احتوت المصفوفة مفاتيح موجودة في المجموعة الأصلية، فستُفضَّل قيم المجموعة الأصلية:

$collection = collect([1 => ['a'], 2 => ['b']]);

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

$union->all();

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

()unique

يعيد التابع unique قيمة فريدة في المجموعة. تحتفظ مجموعة النتيجة بالمفاتيح الأصلية لذا في هذا المثال سنستعمل التابع values لإعادة تعيين المفاتيح لأعداد متتالية:

$collection = collect([1, 1, 2, 2, 3, 4, 2]);

$unique = $collection->unique();

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

// [1, 2, 3, 4]

عند العمل مع المصفوفات المتداخلة أو الكائنات، يمكن تحديد المفتاح المستعمل لتحديد الفرادة:

$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'],
   ]
*/

يمكنك أيضا تمرير دالة رد النداء الخاصة بك لتحديد الفرادة:

$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'],
   ]
*/

يستعمل التابع مقارنة غير صارمة أي أن السلاسل النصية التي تحتوي رقمًا تعدّ مساويةً لعددٍ له القيمة الرقمية. استعمل التابع uniqueStrict لمقارنةٍ أكثر صرامةً.

()uniqueStrict

هذا التابع شبيه بالتابع unique لكنه يستعمل مقارنةً صارمةً.

()unless

ينفذ التابع unless دالة رد النداء الممرَّرة إلا في حالة كان المعامل الأول الممرّر true:

$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]

لعكس وظيفة التابع استعمل التابع when.

()unwrap

يعيد التابع unwrap عناصر المجموعة من القيم الممرّرة عند إمكانية التطبيق:

Collection::unwrap(collect('John Doe'));

// ['John Doe']

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

// ['John Doe']

Collection::unwrap('John Doe');

// 'John Doe'

()values

يعيد التابع values مجموعةً جديدةً مع إعادة ضبط المفاتيح لأعداد متتالية:

Collection::unwrap(collect('John Doe'));

// ['John Doe']

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

// ['John Doe']

Collection::unwrap('John Doe');

// 'John Doe'

()when

ينفذّ التابع when النداء الممرّر عندما تكون قيمة المعامل الأول true:

$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]

لعكس وظيفة when استعمل التابع unless.

()where

يرشِّح التابع where المجموعة عبر الزوج المفتاح/القيمة الممرّر:

$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],
   ]
*/

يستعمل التابع مقارنة غير صارمة أي أن السلاسل النصية التي تحتوي رقمًا تعدّ مساويةً لعدد بنفس القيمة الرقمية. استعمل التابع whereStrict لمقارنةٍ أكثر صرامةً.

()whereStrict

يشبه هذا التابع عمل where لكنه يستعمل مقارنةً صارمةً.

()whereIn

يرشِّح التابع المجموعة عبر الزوج المفتاح\القيمة المحتواة في المصفوفة الممرّرة:

$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],
   ]
*/

يستعمل التابع مقارنة غير صارمة أي أن السلاسل النصية التي تحتوي رقمًا تعدّ مساويةً لعددٍ بنفس القيمة الرقمية. استعمل التابع whereInStrict لمقارنةٍ أكثر صرامةً.

()whereInStrict

يشبه هذا التابع عمل whereIn لكنه يستعمل مقارنةً صارمة.

()whereInstanceOf

يرشِّح التابع whereInstanceOf المجموعة حسب صنف ممرّر:

$collection = collect([

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

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

()whereNotIn

يرشِّح التابع المجموعة حسب زوج المفتاح/القيمة غير مجموعة في المصفوفة الممرّرة:

$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],
   ]
*/

يستعمل التابع مقارنة غير صارمة أي أن السلاسل النصية التي تحتوي رقمًا تعدّ مساويةً لعددٍ بنفس القيمة الرقمية. استعمل التابع whereNotInStrict لمقارنةٍ أكثر صرامة.

()whereNotInStrict

يشبه هذا التابع عمل whereNotIn لكنه يستعمل مقارنةً صارمةً.

()wrap

يغلِّف التابع wrap الثابت القيمة في مجموعة عند تطبيقه:

$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']

()zip

يدمج التابع zip قيم المصفوفات الممرّرة في المواضع المناسبة:

$collection = collect(['Chair', 'Desk']);

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

$zipped->all();

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

الرسائل ذات الترتيب العالي

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

يمكن الوصول لكل رسالة ذات ترتيب عالي كخاصية ديناميكية لكائن المجموعة. مثلًا، لنستعمل رسائل التابع each لنداء تابع مع كل عنصر في المجموعة:

$users = User::where('votes', '>', 500)->get();

$users->each->markAsVip();

بنفس الطريقة، يمكن استعمال رسائل sum لجمع أصوات (votes) مجموعة مستخدمين:

$users = User::where('group', 'Development')->get();

return $users->sum->votes;

مصادر

• صفحة Collections في توثيق Laravel الرسمي0