معرفی collections

اصول آموزش Laravel

تاریخ : دوشنبه 27 آذر 1396

کلاس Illuminate\Support\Collection یک بسته مناسب و راحت برای کار با آرایه های داده فراهم می کند. به عنوان مثال، کد زیر را بررسی کنید. از collect helper برای ایجاد نمونه جدید از آرایه استفاده می کنیم، عملگر strtoupper را بر روی هر عنصر اجرا می کنیم و سپس تمام عناصر خالی را حذف می کنیم:

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

همانطور که می بینید، کلاس Collection به شما اجازه می دهد تا روش های زنجیره ای خود را برای انجام نقشه های روان به کار ببرید. به طور كلي مجموعه ها تغيير نمي كنند، به اين معني كه هر متد Collection نمونه كاملا جديدي از کلاس Collection را باز مي گرداند.


متد Creating Collections

همانطور که در بالا ذکر شد، collect helper نمونه جدید Illuminate\Support\Collection را برای آرایه دریافت شده بر می گرداند. بنابراین ایجاد یک collection ساده است:

$collection = collect([1, 2, 3]);
نکته :نتایج کوئری های Eloquent همیشه نمونه ای از کلاس Collection را بر می گرداند


توسعه Collections

Collection ها "macroable" هستند، به این معنی که می توان متد هایی را به کلاس Collection در زمان اجرا می توان اضافه نمود. برای مثال در کد زیر متدی به نام toUpper را به این مجموعه اضافه نمودیم :

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

به طور معمول جهت معرفی نمودن متد ایجاد شده از service provider استفاده شده تا در تمامی قسمت های برنامه قابل دسترس باشد.


متد های موجود در کلاس Collection

متدهای از پیش تعریف شده این کلاس عبارتند از :


متد all

این متد تمامی زیر آرایه های تعریف شده موجود در این مجموعه را بر می گرداند :

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

// [1, 2, 3]


متد avg

این متد معدل مقادیر را بر اساس کلید دریافتی بر می گرداند :

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

// 20

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

// 2


متد chunk

با استفاده از این متد می توان مجموعه را به چند زیر مجموعه کوچکتر با سایز مشخص شده تقسیم کرد :

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

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

$chunks->toArray();

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

از این روش می توان در view ها زمان نمایش اطلاعات مانند زیر استفاده کرد :

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


متد 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

این متد کلید آرایه یک مجموعه با مقدار آرایه مجموعه ای دیگر را ترکیب می کند :

$collection = collect(['name', 'age']);

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

$combined->all();

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


متد concat

این متد آرایه دریافتی را به انتهای آرایه مجموعه اضافه می کند :

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

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

$concatenated->all();

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


متد contains

این متد وجود یک آیتم مشخص را در مجموعه بررسی می کند :

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

$collection->contains('Desk');

// true

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

// false

شما همچنین می توانید یک key / value را همانند زیر ارسال نمایید :

$collection = collect([
    ['product' => 'Desk', 'price' => 200],
    ['product' => 'Chair', 'price' => 100],
]);

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

// false

همچنین می توانید یک متد callback را جهت بررسی داده های خود اجرا کنید :

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

$collection->contains(function ($value, $key) {
    return $value > 5;
});

// false


متد containsStrict

این متد همانند contains می باشد و از "strict" comparisons جهت بررسی داده ها استفاده می کند.


متد 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

این متد محتوای مجموعه را نمایش و روند اجرای برنامه را قطع میکند :

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

$collection->dd();

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

چنانچه بخواهیم روند اجرای برنامه متوقف نشود از متد dump می توان استفاده کرد.


متد diff

این متد مقدار آیتم های یک مجموعه را با مجموعه دیگر مقایسه و در صورت عدم وجود، برگشت داده خواهند شد :

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

$diff = $collection->diff([2, 4, 6, 8]);

$diff->all();

// [1, 3, 5]


متد diffAssoc

این متد همانند متد diff می باشد با این تفاوت که براساس key / value عمل می کند :

$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

این متد همانند متد diff بوده با این تفاوت که براساس کلید عمل می کند :

$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

این متد محتویات مجموعه را بدون متوقف کردن اجرای برنامه متوقف می کند:

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

$collection->dump();

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


متد each

این متد هر بار یک آیتم از مجموعه دریافت و به متد callback جهت اجرای عملیات بر روی آن ارسال می کند :

$collection = $collection->each(function ($item, $key) {
    //
});

با برگشت مقدار false می توان روند اجرای each را متوقف کرد :

$collection = $collection->each(function ($item, $key) {
    if (/* some condition */) {
        return false;
    }
});


متد eachSpread

همانند متد each بوده و آیتم های تودرتو را به callback ارسال می کند:

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

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


متد every

از این متد جهت تایید آزمون مشخص روی تمامی عناصر استفاده می شود :

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

// false


متد except

این متد تمامی عناصر به غیر از آیتم های مشخص شده را بر می گرداند :

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

$filtered = $collection->except(['price', 'discount']);

$filtered->all();

// ['product_id' => 1]


متد filter

از این متد جهت فیلتر کردن عناصر با یک شرط معین استفاده می شود :

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

$filtered = $collection->filter(function ($value, $key) {
    return $value > 2;
});

$filtered->all();

// [3, 4]

اگر شرطی تعیین نشود تمامی عناصر معادل false حذف خواهند شد :

$collection = collect([1, 2, 3, null, false, '', 0, []]);

$collection->filter()->all();

// [1, 2, 3]


متد first

اولین آیتم که با گذر از شرط تعیین شده تایید شود برگشت داده خواهد شد :

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

// 3

چنانچه شرطی تعیین نگردد اولین آیتم برگشت داده خواهد شد :

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 حلقه زده و سپس تک تک المان های آن را به تابع callback ارسال می کند. تابع بازفراخوان (callback) می تواند آیتم های ارسالی را ویرایش کرده و برگرداند. بدین وسیله مجموعه ای جدید از آیتم های ویرایش شده به عنوان خروجی برگردانده می شود. در نهایت آرایه ها flatten شده و در قالب یک آرایه ی واحد و تک بعدی در خروجی به نمایش در می آید:

$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

این متد یک مجموعه ی چند بعدی را به یک collection تک بعدی تبدیل می کند:

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

$flattened = $collection->flatten();

$flattened->all();

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

می توانید میزان "depth" را به عنوان آرگومان ارسال کنیم :

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


متد flip

این متد کلید و مقدار را جا به جا می کند :

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

$flipped = $collection->flip();

$flipped->all();

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


متد forget

این متد آیتم را با استفاده از کلید مشخص شده حذف می کند :

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

$collection->forget('name');

$collection->all();

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


متد forPage

روش forPage یک مجموعه جدید را که حاوی آیتم هایی است که در یک شماره صفحه مشخص وجود دارد، بازمی گرداند. این روش شماره صفحه را به عنوان اولین آرگومان و تعداد آیتم هایی که در هر صفحه نشان می دهد را به عنوان آرگومان دوم می پذیرد :

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

$chunk = $collection->forPage(2, 3);

$chunk->all();

// [4, 5, 6]


متد get

این متد یک آیتم را با استفاده از کلید آن باز می گرداند :

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

$value = $collection->get('name');

// taylor

چنانچه کلیدی یافت نشود مقدار پیش فرض null برگشت داده خواهد شد . می توان مقدار پیش فرض را مانند زیر تعیین کرد :

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

$value = $collection->get('foo', 'default-value');

// default-value

همچنین می توانید مقدار پیش فرض را با استفاده از روش 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'],
        ],
    ]
*/

همچنین می توانید از روش 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('product');

// true


متد implode

متد 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

این متد هر آیتمی را از مجموعه اصلی که در آرایه یا مجموعه داده شده موجود نباشد حذف می کند. مجموعه نتیجه، کلیدهای اصلی مجموعه را حفظ خواهد کرد:

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

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

$intersect->all();

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


متد intersectByKeys

متد 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

این متد چنانچه مجموعه خالی باشد مقدار true در غیر اینصورت مقدار false بر می گرداند:

collect([])->isEmpty();

// true


متد 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'],
    ]
*/

همچنین می توانید از روش callback در این متد استفاده نمایید :

$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

آخرین آیتم که مصداق یک شرط مشخص باشد را برمی گرداند :

collect([1, 2, 3, 4])->last(function ($value, $key) {
    return $value < 3;
});

// 2

اگر شرطی تعیین نشود آخرین عنصر برگشت داده خواهد شد.

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

// 4


متد macro

با استفتده از این متد می توان متدهای مورد نظر خود را به این کلاس اضافه نماییم.


متد make

این متد نمونه ای از کلاس collection را ایجاد می کند.


متد 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]


متد mapInto

روش mapInto بر روی مجموعه حلقه می زند، و یک نمونه جدید از کلاس داده شده با گذراندن مقدار به سازنده ایجاد می کند:

class Currency
{
    /**
     * Create a new currency instance.
     *
     * @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

The mapSpread method iterates over the collection's items, passing each nested item value into the given callback. The callback is free to modify the item and return it, thus forming a new collection of modified items:

$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

The mapToGroups method groups the collection's items by the given callback. The callback should return an associative array containing a single key / value pair, thus forming a new collection of grouped values:

$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

The mapWithKeys method iterates through the collection and passes each value to the given callback. The callback should return an associative array containing a single key / value pair:

$collection = collect([
    [
        'name' => 'John',
        'department' => 'Sales',
        'email' => '[email protected]'
    ],
    [
        'name' => 'Jane',
        'department' => 'Marketing',
        'email' => '[email protected]'
    ]
]);

$keyed = $collection->mapWithKeys(function ($item) {
    return [$item['email'] => $item['name']];
});

$keyed->all();

/*
    [
        '[email protected]' => 'John',
        '[email protected]' => 'Jane',
    ]
*/


متد max

مقدار max را براساس کلید بر می گرداند :

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

// 20

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

// 5


متد median

این متد مقدار متوسط مجموعه را بر می گرداند :

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

// 15

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

// 1.5


متد 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 را براساس کلید بر می گرداند :

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

// [10]

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

// [1]


متد nth

The nth method creates a new collection consisting of every n-th element:

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

$collection->nth(4);

// ['a', 'e']

You may optionally pass an offset as the second argument:

$collection->nth(4, 1);

// ['b', 'f']


متد 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']


متد 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

از این متد جهت جدا کردن آیتم هایی که مورد تایید شرط مورد نظر هستند و آیتم هایی که مورد تایید شرط نیستند استفاده می گردد:

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

list($underThree, $aboveThree) = $collection->partition(function ($i) {
    return $i < 3;
});


متد pipe

این متد نوع داده collection را به callback ارسال می کند و نتیجه آنرا بر می گرداند :

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

$piped = $collection->pipe(function ($collection) {
    return $collection->sum();
});

// 6


متد 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']


متد 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]

همچنین از آرگومان دوم به عنوان کلید استفاده نمایید :

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

همچنین می توانید تعداد آیتم هایی که بصورت تصادفی برگشت دا می شوند را تعیین کنید :

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

$random->all();

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


متد reduce

این متد مجموعه را به یک مقدار کاهش می دهد ، و نتیجه هر تکرار را به تکرار بعدی انتقال می دهد :

$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

این متد آیتم که مصداق شرط تعیین شده نباشند را بر می گرداند و برعکس متد filter عمل می کند :

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

$filtered = $collection->reject(function ($value, $key) {
    return $value > 2;
});

$filtered->all();

// [1, 2]


متد 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

در حالت پیش فرض از روش "loose" جهت مقایسه و جستجو استفاده می شود برای جستجو با استفاده از روش "strict مقدار true را به عنوان آرگومان دوم ارسال می کنیم :

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

// false

همچنین می توانید از callback در این متد استفاده نمایید :

$collection->search(function ($item, $key) {
    return $item > 5;
});

// 2


متد shift

عملیات 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

تکه ای از مجموعه را با شروع از index معین شده بر می گرداند :

$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 برای reindex استفاده کنید :


متد sort

از این متد جهت مرتب سازی مجموعه استفاده می شود. مجموعه مرتب شده، کلیدهای آرایه را حفظ می کند، بنابراین در این مثال از متد values برای reindex کلیدها استفاده کردیم :

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

$sorted = $collection->sort();

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

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


متد 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],
    ]
*/

همچنین می توان از روش 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

همانند متد sort می باشد با این تفاوت که بصورت نزولی مرتب می کند :


متد splice

این متد تکه ای از مجموعه را با شروع از index مشخص حذف و آن را بر می گرداند :

$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

همچنین می توانید از روش 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 = 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

The tap method passes the collection to the given callback, allowing you to "tap" into the collection at a specific point and do something with the items while not affecting the collection itself:

collect([2, 4, 3, 1, 5])
    ->sort()
    ->tap(function ($collection) {
        Log::debug('Values after sorting', $collection->values()->toArray());
    })
    ->shift();

// 1


متد times

این متد تعداد دفعات اجرای متد callback تعیین شده را تعیین می کند و مقدار آن را در هر بار اجرا بر می گرداند :

$collection = Collection::times(10, function ($number) {
    return $number * 9;
});

$collection->all();

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

این متد می تواند در Eloquent models مانند زیر مفید باشد :

$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

عناصر موجود در مجموعه را بصورت آرایه بر می گرداند:

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

$collection->toArray();

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


متد toJson

عناصر موجود در مجموعه را بصورت JSON بر می گرداند :

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

$collection->toJson();

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


متد transform

این متد مقادیر تغییر یافته بعد از عملیات صورت گرفته بر روی عناصر مجموعه در callback را جایگزین عناصر اصلی مجموعه می کند :

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

$collection->transform(function ($item, $key) {
    return $item * 2;
});

$collection->all();

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

اگر بخواهیم بر روی مجموعه اصلی تغییری حاصل نشود از متد map استفاده نمایید.


متد union

این متد آرایه داده شده را به مجموعه اضافه می کند. اگر آرایه داده شده شامل کلید هایی است که قبلا در مجموعه اصلی هستند، مقادیر اصلی مجموعه ترجیح داده می شود:

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

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

$union->all();

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


متد 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'],
    ]
*/

همچنین می توانید از callback در این متد استفاده نمایید :

$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

همانند متد unique عمل می کند با این تفاوت که از روش "strict" در مقایسه های خود استفاده می کند.


متد unless

این متد callback مشخص شده را اجرا می کند مگر اینگه آرگومان اول 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

The static unwrap method returns the collection's underlying items from the given value when applicable:

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

// ['John Doe']

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

// ['John Doe']

Collection::unwrap('John Doe');

// 'John Doe'


متد 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],
    ]
*/


متد when

این متد callback مورد نظر را زمانیکه آرگومان اول برابر 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]

این متد عکس متد unless عمل می کند.


متد where

این متد عملیات filter را براساس key /value اعمال می کند :

$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

این متد همانند متد where بوده با این تفاوت که از روش مقایسه "strict" استفاده می کند :


متد whereIn

این متد همانند متد where بوده با این تفاوت که مقادیر را می تواند بصورت آرایه دریافت کند :

$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

این متد همانند متد where بوده با این تفاوت که از روش مقایسه "strict" استفاده می کند :


متد whereNotIn

این متد عکس متد where عمل می کند و مقادیری که در آرایه تعیین شده نباشند را بر می گرداند :

$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

این متد همانند متد whereNotIn بوده با این تفاوت که از روش مقایسه "strict" استفاده می کند :


متد wrap

The static wrap method wraps the given value in a collection when applicable:

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

منابع مورد مطالعه جهت جمع آوری این مطلب:
https://laravel.com/docs/5.5/collections


نظرات