1 заметка с тегом

PHP

Справочник по методам коллекции Laravel



Изначально данный материал планировался как мини статья о методах коллекций, но потом всё скатилось в банальный перевод оригинальной документации.

Статья в разработке. Осталось дописать несколько методов и навигацию ;)



Как создать коллекцию из массива?
Очень просто:

// Допустим у нас есть такой массив
$myArray = [
    'one' => 'first',
    'two' => 'second',
    'three' => 'the third'
];

// Создаём коллекцию
$collection = collect($myArray);



Методы для работы с коллекциями



all() Возвращает базовый массив коллекции
avg() Среднее значение всех элементов коллекции
chank() Разбить коллекцию на множество мелкий коллекций





Метод all
Метод all() вернёт базовый массив коллекции

$myArray = [
    'one' => 'first',
    'two' => 'second',
    'three' => 'the third'
];

$collection = collect($myArray);
$collection->all();

// Результат
array:3 [▼
    "one" => "first"
    "two" => "second"
    "three" => "the third"
]



Метод avg
Посчитать среднее значение всех элементов коллекции

$collection = collect([0, 10]);
dd($collection->avg());

//Результат
5

Если коллекция содержит вложенные массивы или объекты, то вам необходимо передать ключ по которому будет считаться среднее значение

$myArray = [
    ['name' => 'one', 'amount' => '10'],
    ['name' => 'two', 'amount'=> '2']
];
$collection = collect($myArray);

dd($collection->avg('amount'));

//Результат
6



Метод chank
Разобьёт коллекцию на множество мелкий коллекций

$myArray = [
    'one' => 'first',
    'two' => 'second',
    'three' => 'the third'
];

$collection = collect($myArray);
dd($collection->chunk(2) );

// Результат
Collection {#17 ▼
  #items: array:2 [▼
    0 => Collection {#15 ▼
      #items: array:2 [▼
        "one" => "first"
        "two" => "second"
      ]
    }
    1 => Collection {#16 ▼
      #items: array:1 [▼
        "three" => "the third"
      ]
    }
  ]
}



Метод collapse
Позволяет собрать одну коллекцию из множества коллекций

$myArray = [
    [
        'one' => 'first',
        'two' => 'second',
    ],
    [
        'three' => 'the third'
    ]
];
$collection = collect($myArray);

dd( $collection->collapse() );

// Результат
Collection {#15 ▼
  #items: array:3 [▼
    "one" => "first"
    "two" => "second"
    "three" => "the third"
  ]
}



Метод contains
Проверяет, содержит ли коллекция нужное значение. Проверка осуществляется по значениям ключей.

$myArray = [
    'one' => 'first',
    'two' => 'second',
    'three' => 'the third'
];

$collection = collect($myArray);

dump( $collection->contains('first') ); // true
dump( $collection->contains('one') ); // false

// Результат
true
false



Метод count
count позволяет сосчитать количество элементов коллекции

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

// Результат
3



Метод diff
Метод diff сравнивает коллекцию с другой коллекцией или массивом

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

//Результат
array:3 [▼
  0 => 1
  2 => 3
  4 => 5
]



Метод each
Что бы перебрать каждый элемент коллекции воспользуетесь методом each

$myArray = [
    'one' => 'first',
    'two' => 'second',
    'three' => 'the third'
];

$collection = collect($myArray);
$collection->each(function ($item, $key) {
    dump($item . ' -> ' . $key);
});

// Результат
"first -> one"
"second -> two"
"the third -> three"



Метод every
А что бы создать новую коллекцию содержащую только каждый N элемент начиная с первого — every

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

dd( $collection->every(4));

// Результат
Collection {#15 ▼
  #items: array:2 [▼
    0 => "a"
    1 => "e"
  ]
}

Вторым аргументом можно указать смещение

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

dd($collection->every(4, 1));

// Результат
Collection {#15 ▼
  #items: array:2 [▼
    0 => "b"
    1 => "f"
  ]
}



Метод except
Исключить из коллекции элементы можно с помощью метода except

$myArray = [
    'one' => 'first',
    'two' => 'second',
    'three' => 'the third'
];
$collection = collect($myArray);

dd($collection->except('two'));

// Результат
Collection {#15 ▼
  #items: array:2 [▼
    "one" => "first"
    "three" => "the third"
  ]
}



Метод filter
Метод фильтрует коллекцию с помощью функции колбэка сохраняя лишь те элементы при обработке которых колбэк вернул true

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

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

dd($filtered);

// Результат
Collection {#16 ▼
  #items: array:2 [▼
    2 => 3
    3 => 4
  ]
}



Метод first
Работает так же как и filter, только возвращает первый элемент при обработке которого колбэк вернул true

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

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

dd($filtered);

// Результат
3
Обратите внимание, что первый аргумент функции колбэка (в отличии от колбэка filter) является ’ключ’, второй ’значение’. У фильтра наоборот.



Метод flatten
Данный метод сделает плоским многомерную коллекцию

$myArray = [
    [
        'one' => 'first',
        'two' => [
            'second', 'the third'
        ]
    ]
];
$collection = collect($myArray);

$flattened = $collection->flatten();
dd( $flattened );

// Результат
Collection {#15 ▼
  #items: array:3 [▼
    0 => "first"
    1 => "second"
    2 => "the third"
  ]
}



Метод flip
Поменяет местами ключи и значения в коллеции

$myArray = [
    'one' => 'first',
    'two' => 'second'
];
$collection = collect($myArray);

dd( $collection->flip());

// Результат
Collection {#15 ▼
  #items: array:2 [▼
    "first" => "one"
    "second" => "two"
  ]
}



Метод forget
Удалить элемент из коллекции по ключу можно с помощью данного метода

$myArray = [
    'one' => 'first',
    'two' => 'second'
];
$collection = collect($myArray);

$collection->forget('one');

dd($collection);

// Результат
Collection {#14 ▼
  #items: array:1 [▼
    "two" => "second"
  ]
}
Обратите внимание, что данный метод, в отличии от большинства, не создаёт новую коллекцию, а изменяет базовую.



Метод forPage
Создаёт новую коллекцию в которой будут присутствовать элементы заданной страницы. Метод первым аргументом принимает номер страницы, вторым количество элементов на ней.

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

dump($collection->forPage(2, 3));
dump($collection->forPage(3, 3));

// Результат
Collection {#15 ▼
  #items: array:3 [▼
    3 => 4
    4 => 5
    5 => 6
  ]
}
Collection {#15 ▼
  #items: array:3 [▼
    6 => 7
    7 => 8
    8 => 9
  ]
}



Метод get
Данный метод возвращает значение по ключу. Если ключа не существует, то будет возвращён null либо значение по умолчанию

$myArray = [
    'one' => 'first',
    'two' => 'second'
];
$collection = collect($myArray);

dd($collection->get('one'));

// Результат
"first"

Для установки значения по умолчанию передайте необходимое значение вторым аргументом.

$myArray = [
    'one' => 'first',
    'two' => 'second'
];
$collection = collect($myArray);

dd($collection->get('three', 'nothing'));

// Результат
"nothing"

Вы так же можете указать в качестве второго аргумента колбэк функцию, результат работы которой будет возвращён, в случае если значение не найдено.

$myArray = [
    'one' => 'first',
    'two' => 'second'
];
$collection = collect($myArray);

$get = $collection->get('three', function () {
    return 'result';
});

dd($get);

// Результат
"result"



Метод groupBy
Группирует элементы коллекции по ключу

$collection = collect([
    ['user' => 'one',   'action' => 'buy'],
    ['user' => 'one',   'action' => 'pay'],
    ['user' => 'two',   'action' => 'pay'],
    ['user' => 'three', 'action' => 'buy'],
    ['user' => 'three', 'action' => 'buy'],
]);

$grouped = $collection->groupBy('action');

dd($grouped);

// Результат
Collection {#18 ▼
  #items: array:2 [▼
    "buy" => Collection {#16 ▼
      #items: array:3 [▼
        0 => array:2 [▼
          "user" => "one"
          "action" => "buy"
        ]
        1 => array:2 [▼
          "user" => "three"
          "action" => "buy"
        ]
        2 => array:2 [▼
          "user" => "three"
          "action" => "buy"
        ]
      ]
    }
    "pay" => Collection {#17 ▼
      #items: array:2 [▼
        0 => array:2 [▼
          "user" => "one"
          "action" => "pay"
        ]
        1 => array:2 [▼
          "user" => "two"
          "action" => "pay"
        ]
      ]
    }
  ]
}



Метод has
Проверяет существование ключа

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

dump($collection->has('one')); // true
dump($collection->has('ololo')); // false

// Результат
true
false



Метод implode
Объединяет элементы коллекции. Передаваемые в метод аргументы зависят от типа коллекции.
Если коллекция объект или массив, то первый аргумент должен указывать на ключ, второй — строка с помощью которой будет произведена склейка.

$collection = collect([
    ['user' => 'one',   'action' => 'buy'],
    ['user' => 'one',   'action' => 'pay'],
    ['user' => 'two',   'action' => 'pay'],
    ['user' => 'three', 'action' => 'buy'],
    ['user' => 'three', 'action' => 'buy'],
]);

dd($collection->implode('action', ', '));

// Результат
"buy, pay, pay, buy, buy"

Если коллекция содержит строки или числа, то указываем единственный аргумент, строка с помощью которой будет произведена склейка.

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

// Результат
"1-2-3-4-5"



Метод intersect
Метод удаляет любые пересекающиеся значения, которые не присутствуют в данном массиве или коллекции:

$collection = collect(['one', 'two', 'three']);

dd($collection->intersect(['one', 'three', 'hmm']));

// Результат
Collection {#15 ▼
  #items: array:2 [▼
    0 => "one"
    2 => "three"
  ]
}



Метод isEmpty
Пуста ли коллекция.

dump(collect([])->isEmpty()); // true
dump(collect([1, 2, 3, 4, 5])->isEmpty()); // false

// Результат
true
false



Метод keyBy
Устанавливает в качестве ключа элемента коллекции выбранное значение ключа
(не знаю как лучше описать, смотрите пример =) )

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

dd ($collection->keyBy('product_id'));

// Результат
Collection {#16 ▼
  #items: array:2 [▼
    "prod-100" => array:2 [▼
      "product_id" => "prod-100"
      "name" => "desk"
    ]
    "prod-200" => array:2 [▼
      "product_id" => "prod-200"
      "name" => "chair"
    ]
  ]
}



Метод keys
Метод возвращает все ключи коллекции

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

dd($collection->keys());

// Результат
Collection {#15 ▼
  #items: array:2 [▼
    0 => "first"
    1 => "second"
  ]
}



Метод last
Возвращает последний элемент коллекции при обработке которого колбек вернул истину (true)
(Данный метод обратный методу first)

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

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

dd($last);

// Результат
4



Метод map
Метод map передаёт в функцию колбека каждый элемент и создаёт новую коллекцию обработанную этим колбеком.

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

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

dd($map);

// Результат
Collection {#16 ▼
  #items: array:5 [▼
    0 => 2
    1 => 4
    2 => 6
    3 => 8
    4 => 10
  ]
}



Метод max
Возвращает максимальное значение в коллекции

dump(collect([['foo' => 10], ['foo' => 20]])->max('foo')); // 20
dump(collect([1, 2, 3, 4, 5])->max()); // 5

// Результат
20
5



Метод merge
Производит слияние массива с коллекцией, перезаписывая при этом одноимённые ключи. Цифровые ключи добавляются в конец коллекции.

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

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

// Результат
Collection {#15 ▼
  #items: array:4 [▼
    "product_id" => 1
    "name" => "Desk"
    "price" => 100
    "discount" => false
  ]
}



Метод min
Возвращает минимальное значение в коллекции

dump(collect([['foo' => 10], ['foo' => 20]])->min('foo')); // 10
dump(collect([1, 2, 3, 4, 5])->min()); // 1

// Результат
10
1



Метод only
Метод возвращает только указанные элементы.
(Работает только с «простыми» коллекциями)

$collection = collect(['name' => 'one', 'amount' => 10, 'price'  => 5]);

dd( $collection->only(['amount', 'price']) );

// Результат
Collection {#15 ▼
  #items: array:2 [▼
    "amount" => 10
    "price" => 5
  ]
}



Метод pluck
Возвращает все значения ключей коллекции по указанному ключу

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

dd($collection->pluck('name'));

// Результат
Collection {#15 ▼
  #items: array:3 [▼
    0 => "Desk"
    1 => "Chair"
    2 => "Chair"
  ]
}

Вторым аргументом вы можете указать наименование ключа значение которого будет использоваться в качестве ключа новой коллекции

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

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

// Результат
Collection {#15 ▼
  #items: array:3 [▼
    "prod-100" => "Desk"
    "prod-200" => "Chair"
    "prod-300" => "Chair"
  ]
}



Метод pop
Метод удаляет и возвращает (проще говоря вытаскивает) последний элемент коллекции. Данный метод изменяет оригинальную коллекцию.

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

dump($collection->pop()); // возвращает 5 и удаляет этот элемент из коллекции

dump($collection->all());

// Результат
5

array:4 [▼
  0 => 1
  1 => 2
  2 => 3
  3 => 4
]



Метод prepend
Добавляет элемент в начало коллекции. Данный метод изменяет оригинальную коллекцию.

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

$collection->prepend(5); 

dump($collection->all());

// Результат
array:6 [▼
  0 => 5
  1 => 1
  2 => 2
  3 => 3
  4 => 4
  5 => 5
]

Второй переданный аргумент задаст имя нового ключа

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

$collection->prepend(5, 'five'); 

dump($collection->all());

// Результат
array:6 [▼
  "five" => 5
  0 => 1
  1 => 2
  2 => 3
  3 => 4
  4 => 5
]



Метод pull
Метод извлекает из коллекции произвольный элемент по ключу. Данный метод изменяет оригинальную коллекцию.

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

dump($collection->pull('name')); // "Desk"

dump($collection->all());

// Результат
 "Desk"

array:1 [▼
  "product_id" => "prod-100"
]



Метод push
Добавляет элемент в конец коллекции. Данный метод изменяет оригинальную коллекцию.

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

dump($collection->push(5));

dd($collection->all());

Результат

Collection {#14 ▼
  #items: array:5 [▼
    0 => 1
    1 => 2
    2 => 3
    3 => 4
    4 => 5
  ]
}

array:5 [▼
  0 => 1
  1 => 2
  2 => 3
  3 => 4
  4 => 5
]



Метод put
Устанавливает заданный ключ и значение в коллекции. Данный метод изменяет оригинальную коллекцию.

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

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

// Результат
Collection {#14 ▼
  #items: array:3 [▼
    "product_id" => 1
    "name" => "Desk"
    "price" => 100
  ]
}



Метод random
Возвращает случайный элемент из коллекции

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

dd($collection->random());

// Результат (Конечно же будет разный)
5



Метод reduce



Метод reject



Метод reverse



Метод search



Метод shift



Метод shuffle



Метод slice



Метод 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],
    ]
*/

Сортируемая коллекция сохраняет оригинальные ключи массива.
Вы можете использовать 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



Метод splice



Метод sum



Метод take



Метод toArray



Метод toJson



Метод transform



Метод unique



Метод values



Метод where



Метод whereLoose



Метод whereIn



Метод whereInLoose



Метод zip