دوره آموزشی PHP
کلیه حقوق مادی و معنوی این مقاله متعلق به آموزشگاه تحلیل داده می باشد و هر گونه استفاده غیر قانونی از آن پیگرد قانونی دارد.
آموزش Collection ها در laravel
1. مقدمه
2. نحوه ی ایجاد نمونه ی جدید از کلاس Collection
3. شرح توابع موجود در کلاس Collection
مقدمه
کلاس Illuminate\Support\Collection از فریم ورک Laravel یک wrapper کارآمد و بهینه برای کار با داده های از نوع آرایه در اختیار برنامه نویس قرار می دهد (wrapper = هر کلاسی که قابلیت و امکانات یک کلاس یا کامپوننت دیگری را در خود کپسوله سازی کند). برای فهم بهتر توجه خود را به مثال ساده ی زیر جلب نمایید.
در این مثال تابع کمکی (helper) collect را فراخوانده و به وسیله ی آن نمونه ای جدید از کلاس collection ایجاد می کنیم. سپس تابع strtoupper را برای هر المان اجرا نموده و تمامی المان های تهی (با مقدار null) را حذف می کنیم:
$collection = collect(['taylor', 'abigail', null])->map(function ($name) {
return strtoupper($name);
})
->reject(function ($name) {
return empty($name);
});
همان طور که از مثال فوق مشاهده می شود، کلاس Collection به شما اجازه می دهد متدهایش را (با اتصال آن ها به انتهای یکدیگر) به صورت زنجیره ای فراخوانی نموده و آرایه را (علاوه بر ویرایش) به آسانی به فیلد مزبور نگاشت (map) نمایید. شایان توجه است که هر متد Collection به طور کلی نمونه ی کاملا جدید از کلاس Collection را در خروجی برمی گرداند.
نحوه ی ایجاد نمونه ی جدید از کلاس Collection
همان طور که در بالا نیز ذکر شد، تابع کمکی collect یک نمونه ی کاملا جدید از کلاس Illuminate\Support\Collection را در خروجی برمی گرداند. نحوه ی ایجاد collection جدید به صورت زیر می باشد:
$collection = collect([1, 2, 3]);
به طور پیش فرض، collection های مدل های Eloquent در قالب نمونه هایی جدید از کلاس Collection به عنوان خروجی برگردانده می شوند. البته شما آزادید هر زمان که اپلیکیشن استفاده از Collection را ایجاب می کند، از این کلاس استفاده نمایید.
شرح توابع موجود در کلاس Collection
در زیر به شرح تمامی متدهای کلاس Collection می پردازیم. یادآور می شویم که تمامی متدهای این کلاس را می توان به منظور دستکاری و ویرایش آسان آرایه به یکدیگر متصل نموده و به صورت زنجیره ای فراخوانی کرد.
بعلاوه تقریبا تمامی متدهای Collection یک نمونه ی جدید از کلاس مزبور را به عنوان خروجی برگردانده تا نمونه ی اصلی collection در صورت لزوم حفظ شده و برای استفاده در آینده در دسترس باشد.
فهرست متدهای کلاس Collection
متد all()
کل آرایه ی اصلی را به عنوان خروجی برمی گرداند:
collect([1, 2, 3])->all();
// [1, 2, 3]
متد avg()
متد avg میانگین مقادیر موجود در collection را محسابه کرده و در خروجی برمی گرداند:
collect([1, 2, 3, 4, 5])->avg();
// 3
در صورتی که collection دربردارنده ی آرایه یا اشیا تودرتو باشد، بایستی یک کلید در داخل آرایه برای مشخص کردن مقادیری که می خواهید میانگین آن محاسبه شود، ارسال کنید:
$collection = collect([
['name' => 'JavaScript: The Good Parts', 'pages' => 176],
['name' => 'JavaScript: The Definitive Guide', 'pages' => 1096],
]);
$collection->avg('pages');
// 636
Chunk()
این متد یک مجموعه (آرایه) کامل را بر اساس مقداری که به عنوان آرگومان به آن ارسال می شود، به بخش های کوچکتر با اندازه ی مشخص تقسیم می کند:
$collection = collect([1, 2, 3, 4, 5, 6, 7]);
$chunks = $collection->chunk(4);
$chunks->toArray();
// [[1, 2, 3, 4], [5, 6, 7]]
این متد به خصوص داخل view ها و زمانی که با یک سیستم نمایش gird مانند، همچون bootstrap کار می کنید بسیار کارآمد و مفید واقع می شود. فرض کنید یک مجموعه از مدل های Eloquent در دست دارید و می خواهید آن ها به صورت grid را نمایش دهید:
@foreach ($products->chunk(3) as $chunk)
<div class="row">
@foreach ($chunk as $product)
<div class="col-xs-4">{{ $product->name }}</div>
@endforeach
</div>
@endforeach
Collapse()
متد collapse مجموعه ای از چندین آرایه ی مجزا را در قالب یک collection واحد و تک بعدی در خروجی برمی گرداند:
$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]
Contains()
متد contains بررسی می کند آیا مجموعه ی مورد نظر حاوی مقدار خاصی هست یا خیر و در صورت وجود مقدار مورد درخواست، true را برمی گرداند:
$collection = collect(['name' => 'Desk', 'price' => 100]);
$collection->contains('Desk');
// true
$collection->contains('New York');
// false
همچنین می توانید یک جفت کلید / مقدار به عنوان پارامتر به متد contains ارسال کنید. متد نام برده به وسیله ی پارامتر ارسالی بررسی می کند آیا جفت کلید/مقدار ارائه شده در مجموعه وجود دارد یا خیر:
$collection = collect([
['product' => 'Desk', 'price' => 200],
['product' => 'Chair', 'price' => 100],
]);
$collection->contains('product', 'Bookcase');
// false
همچنین می توانید یک تابع (بازفراخوان) callback به عنوان پارامتر برای بررسی وجود یا عدم وجود مقدار مورد نظر در مجموعه به تابع contains() ارسال کنید:
$collection = collect([1, 2, 3, 4, 5]);
$collection->contains(function ($key, $value) {
return $value > 5;
});
// false
متد count()
تعداد کل آیتم های موجود در یک مجموعه را به عنوان خروجی برمی گرداند:
$collection = collect([1, 2, 3, 4]);
$collection->count();
// 4
متد diff()
متد diff دو مجموعه (collection) را با یکدیگر یا یک مجموعه را با یک آرایه ی متعارف PHP مقایسه می کند و تفاوت بین آن ها را در خروجی برمی گرداند:
$collection = collect([1, 2, 3, 4, 5]);
$diff = $collection->diff([2, 4, 6, 8]);
$diff->all();
// [1, 3, 5]
each()
متد حاضر داخل آیتم های موجود در مجموعه حلقه زده و تمامی آیتم ها را به ترتیب و به صورت جداگانه به تابع callback ارسال می کند:
$collection = $collection->each(function ($item, $key) {
//
});
برای خروج از حلقه باید مقدار false را از تابع callback برگردانید:
$collection = $collection->each(function ($item, $key) {
if (/* some condition */) {
return false;
}
});
متد every()
این متد یک مجموعه ی جدید متشکل از تمامی المان های مشخص شده توسط پارامتر ارسالی را در خروجی برمی گرداند:
$collection = collect(['a', 'b', 'c', 'd', 'e', 'f']);
$collection->every(4);
// ['a', 'e']
در صورت تمایل می توانید اندیس شروع یا نقطه ی برش (offset) را به عنوان پارامتر دوم به متد پاس دهید:
$collection->every(4, 1);
// ['b', 'f']
متد except()
متد except همان طور که از نامش پیداست تمامی آیتم های موجود در مجموعه را به استثنای آن هایی که به عنوان پارامتر به متد پاس داده شده اند را به عنوان خروجی برمی گرداند:
$collection = collect(['product_id' => 1, 'name' => 'Desk', 'price' => 100, 'discount' => false]);
$filtered = $collection->except(['price', 'discount']);
$filtered->all();
// ['product_id' => 1, 'name' => 'Desk']
متد except درست برعکس متد only عمل می کند.
متد filter()
این متد یک مجموعه را بر اساس شرط مشخص شده در تابع callback فیلتر کرده و تنها آن المان هایی را به عنوان خروجی برمی گرداند که با شرط منطبق باشند (مثلا همگی از دو بزرگتر باشند):
$collection = collect([1, 2, 3, 4]);
$filtered = $collection->filter(function ($value, $key) {
return $value > 2;
});
$filtered->all();
// [3, 4]
این متد نقطه ی مقابل متد reject می باشد.
fitst()
این متد اولین المانی که با شرط معینی همخوانی داشته باشد را به عنوان خروجی برمی گرداند:
collect([1, 2, 3, 4])->first(function ($key, $value) {
return $value > 2;
});
// 3
همچنین می توانید متد first را بدون آرگومان صدا بزنید که در این صورت اولین المان موجود در مجموعه در خروجی بازیابی می شود. در صورتی که collection تهی باشد، مقدار null برگردانده می شود:
collect([1, 2, 3, 4])->first();
// 1
متد flatmap()
متد flatmap() داخل یک collection حلقه زده و سپس تک تک المان های آن را به تابع callback ارسال می کند. تابع بازفراخوان (callback) می تواند آیتم های ارسالی را ویرایش کرده و برگرداند. بدین وسیله مجموعه ای جدید از آیتم های ویرایش شده به عنوان خروجی برگردانده می شود. در نهایت آرایه ها flatten شده و در قالب یک آرایه ی واحد و تک بعدی در خروجی به نمایش در می آید:
$collection = collect(
['name' => 'Sally'],
['school' => 'Arkansas'],
['age' => 28]
]);
$flattened = $collection->flatMap(function ($values) {
return strtoupper($values);
});
$flattened->all();
// ['name' => 'SALLY', 'school' => 'ARKANSAS', 'age' => 28];
متد flatten()
این متد یک مجموعه ی چند بعدی را به یک collection تک بعدی تبدیل می کند:
$collection = collect(['name' => 'taylor', 'languages' => ['php', 'javascript']]);
$flattened = $collection->flatten();
$flattened->all();
// ['taylor', 'php', 'javascript'];
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']
نکته: برخلاف دیگر متدهای collection، 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()
این متد آیتمی که دارای کلید معین هست را به عنوان خروجی برمی گرداند (کلید را به عنوان آرگومان پذیرفته و در خروجی مقدار مربوطه را برمی گرداند). در صورتی که کلید مورد نظر در آرایه موجود نباشد، مقدار null را به عنوان خروجی برمی گرداند:
$collection = collect(['name' => 'taylor', 'framework' => 'laravel']);
$value = $collection->get('name');
// taylor
همچنین می توان یک callback به عنوان مقدار پیشفرض ارسال کرد. در صورتی که کلید مورد نظر در آرایه موجود نباشد مقدار callback را به عنوان خروجی برمی گرداند:
$collection->get('email', function () {
return 'default-value';
});
// default-value
متد 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 از نوع رشته، می توانید یک تابع callback را به عنوان آرگومان ارسال کنید. تابع callback بایستی مقداری که می خواهید گروه بر اساس آن کلید گروه بندی شوند را به عنوان خروجی برگرداند:
$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'],
],
]
*/
متد has()
این متد بررسی می کند آیا کلید معینی در مجموعه وجود دارد یا خیر:
$collection = collect(['account_id' => 1, 'product' => 'Desk']);
$collection->has('email');
// false
متد implode()
متد implode دو آیتم در یک مجموعه را به هم پیوند می زند (مقدار دو کلید را به یکدیگر join می کند). آرگومان های این متد به نوع آیتم های موجود در مجموعه بستگی دارد.
چنانچه آیتم های داخل مجموعه از نوع شی یا آرایه باشند، در آن صورت بایستی کلید آن attribute هایی را که مایلید به یکدیگر پیوند زده شده و نیز تفکیک گری که باید بین دو مقدار قرار گیرد را به ترتیب به عنوان آرگومان های اول و دوم به تابع implode() ارسال کنید.
$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() تمامی مقادیری که در array یا collection مورد نظر موجود نیستند را حذف می کند:
$collection = collect(['Desk', 'Sofa', 'Chair']);
$intersect = $collection->intersect(['Desk', 'Chair', 'Bookcase']);
$intersect->all();
// [0 => 'Desk', 2 => 'Chair']
همان طور که می بینید مجموعه ی خروجی کلیدهای collection اصلی را نگه می دارد.
متد isEmpty()
این متد در صورتی که collection مورد نظر تهی باشد مقدار true را برمی گرداند و در غیر این صورت false را بازیابی می کند:
collect([])->isEmpty();
// true
متد keyBy()
متد keyByیک مجموعه را بر اساس کلیدی که به عنوان آرگومان به آن پاس داده شده، کلید دهی (key) می کند:
$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'],
]
*/
در صورتی که چندین آیتم دارای کلید یکسان باشند، تنها آخرین آیتم در collection خروجی لحاظ می شود.
البته شما می توانید callback خود را به عنوان آرگومان ارسال کنید که خروجی آن کلیدی خواهد بود که مجموعه بر اساس آن کلیددهی (key) می شود:
$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'],
]
*/
متد key()
متد 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()
آخرین المان موجود در یک collection را که با شرط مشخص شده در تابع callback منطبق می باشد را در خروجی برمی گرداند:
collect([1, 2, 3, 4])->last(function ($key, $value) {
return $value < 3;
});
// 2
همچنین می توانید متد last را بدون هیچ آرگومان فراخوانی کنید که در آن صورت آخرین المان موجود در مجموعه را برمی گرداند. در صورت تهی بودن collection، مقدار null برگردانده می شود:
collect([1, 2, 3, 4])->last();
// 4
متد map()
متد map داخل مجموعه حلقه زده و سپس هر مقدار را به تابع callback پاس می دهد. callback می تواند آیتم را ویرایش نموده و آن را در خروجی برگرداند. بدین وسیله یک نمونه ی جدید از مجموعه، متشکل از آیتم های ویرایش شده ی collection اصلی در خروجی ارائه می شود:
$collection = collect([1, 2, 3, 4, 5]);
$multiplied = $collection->map(function ($item, $key) {
return $item * 2;
});
$multiplied->all();
// [2, 4, 6, 8, 10]
نکته: درست مانند بیشتر متدهای کلاس collection، تابع map یک نمونه ی جدید از کلاس مزبور را به عنوان خروجی برمی گرداند. بنابراین مجموعه ی اصلی که تابع بر روی آن اجرا شده دست نخورده باقی می ماند. به منظور تغییر collection اصلی بایستی متد transform را بر روی آن فراخونی نمایید.
متد max()
این متد مقدار بیشینه ی کلید معین (بزرگترین مقدار عددی در مجموعه) را به عنوان خروجی برمی گرداند:
$max = collect([['foo' => 10], ['foo' => 20]])->max('foo');
// 20
$max = collect([1, 2, 3, 4, 5])->max();
// 5
متد merge()
متد merge آرایه ی ارسالی به عنوان پارامتر را با مجموعه ی مورد نظر ترکیب می کند. هر کلید رشته ای موجود در آرایه که با کلید رشته ای داخل مجموعه منطبق باشد، جایگزین مقدار داخل مجموعه شده و روی مقدار آن بازنویسی می شود:
$collection = collect(['product_id' => 1, 'name' => 'Desk']);
$merged = $collection->merge(['price' => 100, 'discount' => false]);
$merged->all();
// ['product_id' => 1, 'name' => 'Desk', 'price' => 100, '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
متد only()
این متد آیتم های موجود در مجموعه را که دارای کلید مشخص هستند به عنوان خروجی برمی گرداند:
$collection = collect(['product_id' => 1, 'name' => 'Desk', 'price' => 100, 'discount' => false]);
$filtered = $collection->only(['product_id', 'name']);
$filtered->all();
// ['product_id' => 1, 'name' => 'Desk']
متد only درست برعکس تابع except می باشد.
متد pluck()
متد pluck() تمامی مقادیر موجود در مجموعه که از نظر کلید ارسالی به آن یکسان هستند را در خروجی بازیابی می کند:
$collection = collect([
['product_id' => 'prod-100', 'name' => 'Desk'],
['product_id' => 'prod-200', 'name' => 'Chair'],
]);
$plucked = $collection->pluck('name');
$plucked->all();
// ['Desk', 'Chair']
حتی می توانید با ارسال کلید به عنوان پارامتر دوم به این متد، مشخص نمایید collection خروجی با چه اسمی کلید دهی شود:
$plucked = $collection->pluck('name', 'product_id');
$plucked->all();
// ['prod-100' => 'Desk', 'prod-200' => 'Chair']
pop()
pop() آخرین آیتم را از مجموعه حذف کرده و در خروجی برمی گرداند:
$collection = collect([1, 2, 3, 4, 5]);
$collection->pop();
// 5
$collection->all();
// [1, 2, 3, 4]
متد prepend() یک آیتم را به ابتدای یک مجموعه اضافه می کند:
$collection = collect([1, 2, 3, 4, 5]);
$collection->prepend(0);
$collection->all();
// [0, 1, 2, 3, 4, 5]
در صورت تمایل می توانید یک آرگومان دوم به متد prepend() ارسال کنید که کلید آیتم ضمیمه شده به مجموعه را مشخص می کند:
$collection = collect(['one' => 1, 'two', => 2]);
$collection->prepend(0, 'zero');
$collection->all();
// ['zero' => 0, 'one' => 1, 'two', => 2]
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()
این متد یک جفت کلید مقدار جدید را که به صورت آرگومان به آن ارسال شده، در مجموعه درج می کند:
$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)
در صورت تمایل می توانید یک عدد صحیح را به عنوان آرگومان به متد ذکر شده پاس دهید. در صورتی که مقدار این آرگومان بزرگتر از 1 باشد، مجموعه ای از آیتم ها به صورت تصادفی در خروجی بازیابی می شود:
$random = $collection->random(3);
$random->all();
// [2, 4, 5] - (retrieved randomly)
متد reduce()
یک مجموعه از مقادیر را به تنها یک مقدار تبدیل می کند و نتیجه ی هر iteration را به iteration بعدی پاس می دهد:
$collection = collect([1, 2, 3]);
$total = $collection->reduce(function ($carry, $item) {
return $carry + $item;
});
// 6
مقدار متغیر $carry در تکرار یا چرخش اول null می باشد. البته شما می توانید با ارسال آرگومان دیگری به تابع مقدار آغازین را مشخص نمایید:
$collection->reduce(function ($carry, $item) {
return $carry + $item;
}, 4);
// 10
تابع reject()
این متد مجموعه را بر اساس شرط تعیین شده در تابع callback که به عنوان پارامتر پاس داده شده فیلتر می کند. تابع callback بایستی برای هر آیتمی که با شرط منطبق نیستند و می خواهد از مجموعه ی ورودی حذف کند (و در مجموعه ی خروجی لحاظ نکند)، مقدار true را بر گرداند:
$collection = collect([1, 2, 3, 4]);
$filtered = $collection->reject(function ($value, $key) {
return $value > 2;
});
$filtered->all();
// [1, 2]
متد reject عملکردی متضاد متد filter دارد.
متد reverse()
متد reverse() ترتیب قرارگیری آیتم های مجموعه را معکوس می کند:
$collection = collect([1, 2, 3, 4, 5]);
$reversed = $collection->reverse();
$reversed->all();
// [5, 4, 3, 2, 1]
متد search()
این متد مقداری که به عنوان آرگومان به آن پاس داده شده را داخل مجموعه جستجو کرده و کلید آن را در صورت یافتن مقدار مورد درخواست، در خروجی برمی گرداند. اگر آیتم مورد نظر یافت نشد، مقدار false برگردانده می شود:
$collection = collect([2, 4, 6, 8]);
$collection->search(4);
// 1
جستجو داخل مجموعه بر اساس یک مقایسه ی تقریبی صورت می پذیرد. به منظور اعمال مقایسه ی دقیق کافی است مقدار true را به عنوان پارامتر ورودی دوم به متد مذکور ارسال نمایید:
$collection->search('4', true);
// false
همچنین می توانید تابع بازفرخوان (callback) خود را به عنوان آرگومان ارسال نمایید. این تابع به دنبال اولین آیتمی (از نظر مکان قرارگیری) که با شرط مشخص شده داخلش مطابقت دارد گشته و آن را به عنوان خروجی برمی گرداند:
$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()
این متد بر اساس اندیس شروع که به عنوان آرگومان به آن ارسال شده یک مجموعه را برش داده و در خروجی برمی گرداند. مثال زیر آیتم های بعد از شماره ی مکان قرارگیری 4 را از مجموعه استخراج می کند:
$collection = collect([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
$slice = $collection->slice(4);
$slice->all();
// [5, 6, 7, 8, 9, 10]
برای کاهش سایز خروجی (و محدود تر کردن نتیجه)، می توانید یک آرگومان دوم به متد ارسال کنید. این آرگومان تعداد آیتم های استخراجی از collection را تعیین می کند:
$slice = $collection->slice(4, 2);
$slice->all();
// [5, 6]
آیتم های استخراج شده به عنوان خروجی مجددا با کلیدهای عددی اندیس گذاری می شوند (کلیدهایی از نوع عدد اندیس جدید آن ها خواهد بود). اگر مایلید کلیدهای اصلی را حفظ کنید، درآن صورت کافی است مقدار true را به عنوان آرگومان سوم به متد ارسال نمایید.
sort()
این متد مجموعه را مرتب سازی می نماید:
$collection = collect([5, 3, 1, 2, 4]);
$sorted = $collection->sort();
$sorted->values()->all();
// [1, 2, 3, 4, 5]
مجموعه ی مرتب شده کلیدهای اصلی آرایه را حفظ می کند (کلیدهای اصلی آرایه پس از مرتب سازی تغییر نکرده و ثابت می ماند). در این مثال با استفاده از متد values کلید های آیتم های مجموعه را دوباره (به ترتیب عددی متوالی) اندیس گذاری می کنیم.
به منظور مرتب سازی مجموعه ای از اشیا و آرایه های تودرتو، بخش های مربوط به متدهای sortBy و sortByDesc را مطالعه نمایید.
در صورتی که مرتب سازی شما حالت پیچیده تری به خود می گیرد، درآن صورت می توانید یک تابع callback با الگوریتم اختصاصی خود به عنوان آرگومان به متد sort ارسال کنید.
متد sortBy()
این متد مجموعه را بر اساس کلید ارسالی (به عنوان آرگومان) مرتب سازی می کند:
$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],
]
*/
کلیدهای آرایه پس از مرتب سازی ثابت می ماند. در این نمونه، از متد values برای اندیس گذاری آیتم های آرایه به ترتیب عددی متوالی بهره گرفتیم (با values کلیدهای آرایه را به ترتیب عددی متوالی اندیس گذاری می کنیم).
شما می توانید تابع callback خود را برای تعیین نحوه ی مرتب سازی مقادیر مجموعه به متد نام برده ارسال کنید:
$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()
این متد از نظر نوع و تعداد پارامتر ورودی (signature) با متد sortBy یکسان است ولی مجموعه ی مورد نظر را بجای صعودی، به ترتیب نزولی sort می کند.
متد 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]
متد 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
علاوه بر آن می توانید یک تابع callback به متد ارسال کنید که مشخص می کند حاصل جمع کدام مقادیر از مجموعه بایستی محاسبه شده و در خروجی لحاظ شود:
$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()
این متد یک مجموعه ی جدید از collection جاری ایجاد کرده و در خروجی برمی گرداند. پارامتر ارسالی به متد تعداد آیتم هایی که باید در خروجی لحاظ شود را مشخص می کند:
$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]
متد toArray()
این متد همان طور که از نامش پیدا است collection مورد نظر را به یک آرایه ی متعارف در PHP تبدیل می کند. چنانچه مقادیر موجود در مجموعه از مدل های Eloquent باشند، در آن صورت مدل ها نیز در اثر اجرای این متد به آرایه تبدیل می شوند:
$collection = collect(['name' => 'Desk', 'price' => 200]);
$collection->toArray();
/*
[
['name' => 'Desk', 'price' => 200],
]
*/
نکته: toArray تمامی اشیای قرار گرفته در دل مجموعه (nested و تودرتو) را نیز به آرایه تبدیل می کند. اگر می خواهید آرایه را همان طور که هست (بدون تغییر) دریافت کنید، در آن صورت بایستی (بجای متد نام برده) متد all را فراخوانی نمایید.
تابع toJson()
مجموعه را به فرمت JSON تبدیل می کند:
$collection = collect(['name' => 'Desk', 'price' => 200]);
$collection->toJson();
// '{"name":"Desk","price":200}'
متد transform()
این متد داخل مجموعه حلقه زده و callback ارسالی به متد را به ازای هر آیتم داخل collection صدا می زند. آیتم های موجود در مجموعه با مقادیر بازگشتی (خروجی callback) جایگزین می شوند:
$collection = collect([1, 2, 3, 4, 5]);
$collection->transform(function ($item, $key) {
return $item * 2;
});
$collection->all();
// [2, 4, 6, 8, 10]
نکته: بر خلاف عمده ی متدهای کلاس collection، تابع transforms در اصل خود مجموعه تغییرات را اعمال نموده و یک مجموعه ی ویرایش شده را در نتیجه بر می گرداند. اگر می خواهید یک مجموعه ی جدید بجای ویرایش مجموعه ی اصلی دریافت کنید، در آن صورت بایستی متد 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 تمامی آیتم های یگانه و منحصربفرد (غیرتکراری) داخل مجموعه را در خروجی برمی گرداند:
$collection = collect([1, 1, 2, 2, 3, 4, 2]);
$unique = $collection->unique();
$unique->values()->all();
// [1, 2, 3, 4]
کلید های آرایه در مجموعه ی خروجی تغییر نخواهند کرد. در این مثال با استفاده از متد values مجددا آیتم های موجود در آرایه را به ترتیب عددی متوالی اندیس گذاری کردیم.
برای آرایه ها و اشیا تودرتو نیز بایستی یک کلید به عنوان آرگومان که آیتم منحصربفرد را مشخص می کند به تابع ارسال کنید:
$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'],
]
*/
همچنین می توانید callback خود را به متد unique ارسال کرده و از این طریق آیتم منحصربفرد و غیر تکراری را در خروجی برگردانید:
$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'],
]
*/
متد values()
این متد یک مجموعه ی جدید را به عنوان خروجی برگردانده و کلیدهای آن را به اعداد صحیح متوالی ریست می کند:
$collection = collect([
10 => ['product' => 'Desk', 'price' => 200],
11 => ['product' => 'Desk', 'price' => 200]
]);
$values = $collection->values();
$values->all();
/*
[
0 => ['product' => 'Desk', 'price' => 200],
1 => ['product' => 'Desk', 'price' => 200],
]
*/
متد where()
این متد یک مجموعه را بر اساس جفت/کلید مقدار (key/value pair) ارسالی فیلتر می کند:
$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],
]
*/
متد where مقادیر آیتم های یک مجموعه را بر اساس مقایسه و تطبیق دقیق فیلتر می کند. برای فیلتر کردن خروجی بر اساس مقایسه و تطبیق تقریبی (loose comparison) بایستی متد whereloose را فراخوانی نمایید.
متد whereLoose()
whereLoose() از نظر تعداد و نوع پارامتر ورودی (signature) با متد قبلی تفاوتی ندارد به جز اینکه در این متد تمامی مقادیر بر اساس مقایسه ی منطقی تقریبی تطبیق و فیلتر می شوند.
متد 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],
]
*/
متد whereIn() مقادیر آیتم ها را بر اساس تطبیق منطقی دقیق بررسی و مقایسه می کند.
متد whereInLoose()
این متد از نظر تعداد و نوع پارامتر ورودی (signature) با متد wherein فرق ندارد و تنها تفاوت آن ها در نحوه ی تطبیق مقادیر و فیلتر کردن نتیجه می باشد (whereInLoose از تطبیق منطقی تقریبی و غیر دقیق برای مقایسه و فیلتر نتیجه بهره می گیرد).
متد zip()
متد zip() مقادیر آرایه ی ورودی را با مقادیر موجود در مجموعه در اندیس منطبق (که دارای شماره ی مکان قرارگیری یکسان است) ترکیب می کند:
$collection = collect(['Chair', 'Desk']);
$zipped = $collection->zip([100, 200]);
$zipped->all();
// [['Chair', 100], ['Desk', 200]]