README

此仓库包含一些有用的集合宏。

Spatie是一家位于比利时安特卫普的网页设计公司。您可以在我们的网站上找到我们所有开源项目的概述在这里。

支持我们

我们投入了大量资源来创建一流的开放源代码包。您可以通过购买我们的付费产品之一来支持我们。

我们非常感谢您从家乡寄给我们明信片，说明您正在使用我们的哪些包。您可以在我们的联系我们页面上找到我们的地址。我们将所有收到的明信片发布在我们的虚拟明信片墙上。

安装

您可以通过Composer引入此包

composer require spatie/laravel-collection-macros

该包将自动注册自己。

宏

after
at
- second
- third
- fourth
- fifth
- sixth
- seventh
- eighth
- ninth
- tenth
- getNth
before
catch
chunkBy
collectBy
containsAny
containsAll
eachCons
extract
filterMap
firstOrFail
firstOrPush
fromPairs
getCaseInsensitive
glob
groupByModel
hasCaseInsensitive
head
if
ifAny
ifEmpty
insertAfter
insertAfterKey
insertAt
insertBefore
insertBeforeKey
none
paginate
path
pluckMany
pluckManyValues
pluckToArray
prioritize
recursive
rotate
sectionBy
simplePaginate
sliceBefore
tail
try
toPairs
transpose
validate
weightedRandom
withSize

`after`

从集合中获取下一个项目。

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

$currentItem = 2;

$currentItem = $collection->after($currentItem); // return 3;
$collection->after($currentItem); // return null;

$currentItem = $collection->after(function($item) {
    return $item > 1;
}); // return 3;

您还可以传递第二个参数作为后备。

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

$currentItem = 3;

$collection->after($currentItem, $collection->first()); // return 1;

`at`

检索指定索引处的项目。

$data = new Collection([1, 2, 3]);

$data->at(0); // 1
$data->at(1); // 2
$data->at(-1); // 3

`second`

检索第二个索引处的项目。

$data = new Collection([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);

$data->second(); // 2

`third`

检索第三个索引处的项目。

$data = new Collection([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);

$data->third(); // 3

`fourth`

检索第四个索引处的项目。

$data = new Collection([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);

$data->fourth(); // 4

`fifth`

检索第五个索引处的项目。

$data = new Collection([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);

$data->fifth(); // 5

`sixth`

检索第六个索引处的项目。

$data = new Collection([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);

$data->sixth(); // 6

`seventh`

检索第七个索引处的项目。

$data = new Collection([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);

$data->seventh(); // 7

`eighth`

检索第八个索引处的项目。

$data = new Collection([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);

$data->eighth(); // 8

`ninth`

检索第九个索引处的项目。

$data = new Collection([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);

$data->ninth(); // 9

`tenth`

检索第十个索引处的项目。

$data = new Collection([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);

$data->tenth(); // 10

`getNth`

检索第n个项目。

$data = new Collection([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]);

$data->getNth(11); // 11

`before`

从集合中获取上一个项目。

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

$currentItem = 2;

$currentItem = $collection->before($currentItem); // return 1;
$collection->before($currentItem); // return null;

$currentItem = $collection->before(function($item) {
    return $item > 2;
}); // return 2;

您还可以传递第二个参数作为后备。

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

$currentItem = 1;

$collection->before($currentItem, $collection->last()); // return 3;

`catch`

查看 Try

`chunkBy`

将集合中的值分组成组，直到给定的回调函数为true。如果传递了可选参数 $preserveKeys 且其值为 true，则将保留原始键。

collect(['A', 'A', 'B', 'A'])->chunkBy(function($item) {
    return $item == 'A';
}); // return Collection([['A', 'A'],['B'], ['A']])

`collectBy`

在给定的键处获取一个项目，并收集它。

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

$collection->collectBy('foo'); // Collection([1, 2, 3])

您还可以传递第二个参数作为后备。

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

$collection->collectBy('baz', ['Nope']); // Collection(['Nope'])

`containsAny`

如果给定值中的任何一个存在于集合中，将返回 true。

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

$collection->containsAny(['b', 'c', 'd']); // returns true
$collection->containsAny(['c', 'd', 'e']); // returns true
$collection->containsAny(['d', 'e', 'f']); // returns false
$collection->containsAny([]); // returns false

`containsAll`

如果所有给定值都存在于集合中，将返回 true。

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

$collection->containsAll(['b', 'c',]); // returns true
$collection->containsAll(['c', 'd']); // returns false
$collection->containsAll(['d', 'e']); // returns false
$collection->containsAll([]); // returns true

`eachCons`

获取从给定块大小开始的集合中的连续相邻项。如果传递了可选参数 $preserveKeys 且其值为 true，则将保留原始键。

collect([1, 2, 3, 4])->eachCons(2); // return collect([[1, 2], [2, 3], [3, 4]])

`extract`

从集合中提取键。这与only非常相似，但有两个主要区别

extract返回一个值数组，而不是关联数组
如果值不存在，将使用null填充值，而不是省略它

extract在PHP 7.1短list()语法中使用时非常有用。

[$name, $role] = collect($user)->extract('name', 'role.name');

`filterMap`

一次性将集合映射并移除假值。

$collection = collect([1, 2, 3, 4, 5, 6])->filterMap(function ($number) {
    $quotient = $number / 3;

    return is_integer($quotient) ? $quotient : null;
});

$collection->toArray(); // returns [1, 2]

`firstOrFail`

获取第一个元素。如果找不到元素，将抛出Spatie\CollectionMacros\Exceptions\CollectionItemNotFound异常。

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

$collection->toArray(); // returns [1]

collect([])->firstOrFail(); // throws Spatie\CollectionMacros\Exceptions\CollectionItemNotFound

`firstOrPush`

使用第一个参数提供的可调用函数检索第一个元素。如果不存在值，将第二个参数的值推入集合。您可以传递一个可调用函数作为第二个参数。

当处理缓存的类属性时，此方法非常有用，您希望将一次从API或计算密集型函数中检索的值存储在集合中以供多次使用。

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

$collection->toArray(); // returns [1, 2, 3, 4]

偶尔，您可能需要指定要推送到的目标集合。您可以将此作为第三个参数传递。

$collection = collect([1, 2, 3]);
$collection->filter()->firstOrPush(fn($item) => $item === 4, 4, $collection);

$collection->toArray(); // returns [1, 2, 3, 4]

`fromPairs`

将集合转换为关联数组形式的集合项。

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

$collection->toArray(); // returns ['a' => 'b', 'c' => 'd', 'e' => 'f']

`getCaseInsensitive`

获取给定键的值。

如果键是字符串，我们将使用不区分大小写的比较来搜索键。

$collection = collect([
    'foo' => 'bar',
]);

$collection->getCaseInsensitive('Foo'); // returns 'bar';

`glob`

返回一个glob()结果的集合。

Collection::glob('config/*.php');

`groupByModel`

类似于groupBy，但按Eloquent模型对集合进行分组。由于键是对象而不是整数或字符串，结果被分成单独的数组。

$posts->groupByModel('category');

// [
//     [$categoryA, [/*...$posts*/]],
//     [$categoryB, [/*...$posts*/]],
// ];

完整签名：groupByModel($callback, $preserveKeys, $modelKey, $itemsKey)

`hasCaseInsensitive`

确定集合是否包含具有给定名称的键。

如果$key是字符串，我们将使用不区分大小写的比较来搜索键。

$collection = collect([
    'foo' => 'bar',
]);

$collection->hasCaseInsensitive('Foo'); // returns true;

`head`

从集合中检索第一个元素。

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

$collection->head(); // return 1

$collection = collect([]);

$collection->head(); // return null

`if`

if宏可以帮助分支集合链。这是此宏的签名

if(mixed $if, mixed $then = null, mixed $else = null): mixed

$if、$then和$else可以是任何类型。如果将这些参数之一传递给闭包，则将执行该闭包，并且宏将使用其结果。

当$if返回一个真值时，则返回$then，否则返回$else。

以下是一些示例

collect()->if(true, then: true, else: false); // returns true
collect()->if(false, then: true, else: false); // returns false

当将闭包传递给$if、$then或$else时，整个集合将被作为参数传递给该闭包。

// the `then` closure will be executed
// the first element of the returned collection now contains "THIS IS THE VALUE"
$collection = collect(['this is a value'])
    ->if(
        fn(Collection $collection) => $collection->contains('this is a value'),
        then: fn(Collection $collection) => $collection->map(fn(string $item) => strtoupper($item)),
        else: fn(Collection $collection) => $collection->map(fn(string $item) => Str::kebab($item))
    );

// the `else` closure will be executed
// the first element of the returned collection now contains "this-is-another-value"
$collection = collect(['this is another value'])
    ->if(
        fn(Collection $collection) => $collection->contains('this is a value'),
        then: fn(Collection $collection) => $collection->map(fn(string $item) => strtoupper($item)),
        else: fn(Collection $collection) => $collection->map(fn(string $item) => Str::kebab($item))
    );

`ifAny`

如果集合不为空，则执行传递的可调用函数。将返回整个集合。

collect()->ifAny(function(Collection $collection) { // empty collection so this won't get called
   echo 'Hello';
});

collect([1, 2, 3])->ifAny(function(Collection $collection) { // non-empty collection so this will get called
   echo 'Hello';
});

`ifEmpty`

如果集合为空，则执行传递的可调用函数。将返回整个集合。

collect()->ifEmpty(function(Collection $collection) { // empty collection so this will called
   echo 'Hello';
});

collect([1, 2, 3])->ifEmpty(function(Collection $collection) { // non-empty collection so this won't get called
   echo 'Hello';
});

`insertAfter`

在给定项的第一个出现之后插入一个项，并返回更新后的Collection实例。可选地提供一个键。

collect(['zero', 'two', 'three'])->insertAfter('zero', 'one');
// Collection contains ['zero', 'one', 'two', 'three']

collect(['zero' => 0, 'two' => 2, 'three' => 3]->insertAfter(0, 5, 'five');
// Collection contains ['zero' => 0, 'five' => 5, 'two' => 2, 'three' => 3]

`insertAfterKey`

在给定键之后插入一个项，并返回更新后的Collection实例。可选地提供一个新项的键。

collect(['zero', 'two', 'three'])->insertAfterKey(0, 'one');
// Collection contains ['zero', 'one', 'two', 'three']

collect(['zero' => 0, 'two' => 2, 'three' => 3]->insertAfterKey('zero', 5, 'five');
// Collection contains ['zero' => 0, 'five' => 5, 'two' => 2, 'three' => 3]

`insertAt`

在给定索引处插入一个项，并返回更新后的Collection实例。可选地提供一个键。

collect(['zero', 'two', 'three'])->insertAt(1, 'one');
// Collection contains ['zero', 'one', 'two', 'three']

collect(['zero' => 0, 'two' => 2, 'three' => 3]->insertAt(1, 5, 'five');
// Collection contains ['zero' => 0, 'five' => 5, 'two' => 2, 'three' => 3]

`insertBefore`

在给定项的第一个出现之前插入一个项，并返回更新后的Collection实例。可选地提供一个键。

collect(['zero', 'two', 'three'])->insertBefore('two', 'one');
// Collection contains ['zero', 'one', 'two', 'three']

collect(['zero' => 0, 'two' => 2, 'three' => 3]->insertBefore(2, 5, 'five');
// Collection contains ['zero' => 0, 'five' => 5, 'two' => 2, 'three' => 3]

`insertBeforeKey`

在给定键之前插入一个项，并返回更新后的Collection实例。可选地提供一个新项的键。

collect(['zero', 'two', 'three'])->insertBeforeKey(1, 'one');
// Collection contains ['zero', 'one', 'two', 'three']

collect(['zero' => 0, 'two' => 2, 'three' => 3]->insertBeforeKey('two', 5, 'five');
// Collection contains ['zero' => 0, 'five' => 5, 'two' => 2, 'three' => 3]

`none`

检查集合是否不包含给定项、键值对或通过真值测试的任何出现。该函数接受与contains集合方法相同的参数。

collect(['foo'])->none('bar'); // returns true
collect(['foo'])->none('foo'); // returns false

collect([['name' => 'foo']])->none('name', 'bar'); // returns true
collect([['name' => 'foo']])->none('name', 'foo'); // returns false

collect(['name' => 'foo'])->none(function ($key, $value) {
   return $key === 'name' && $value === 'bar';
}); // returns true

`paginate`

为集合中的项目创建一个LengthAwarePaginator实例。

collect($posts)->paginate(5);

此分页将$posts的内容分页为每页5个项目。paginate接受相当多的选项，有关详细信息，请参阅Laravel文档。

paginate(int $perPage = 15, string $pageName = 'page', int $page = null, int $total = null, array $options = [])

`path`

使用“点”符号从集合中返回具有多维度数据的项。与原生集合的pull方法类似，但不会从集合中删除项。

$collection = new Collection([
    'foo' => [
        'bar' => [
            'baz' => 'value',
        ]
    ]
]);

$collection->path('foo.bar.baz') // 'value'

`pluckMany`

返回只包含指定键的集合。

$collection = collect([
    ['a' => 1, 'b' => 10, 'c' => 100],
    ['a' => 2, 'b' => 20, 'c' => 200],
]);

$collection->pluckMany(['a', 'b']);

// returns
// collect([
//     ['a' => 1, 'b' => 10],
//     ['a' => 2, 'b' => 20],
// ]);

`pluckManyValues`

返回只包含指定键值的集合。

$collection = collect([
    ['a' => 1, 'b' => 10, 'c' => 100],
    ['a' => 2, 'b' => 20, 'c' => 200],
]);

$collection->pluckMany(['a', 'b']);

// returns
// collect([
//     [1, 10],
//     [2, 20],
// ]);

`pluckToArray`

返回指定键值的数组。

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

$collection->pluckToArray('a'); // returns [1, 2, 3]

`prioritize`

将元素移动到集合的开始位置。

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

$collection
   ->prioritize(function(array $item) {
      return $item['id'] === 2;
   })
   ->pluck('id')
   ->toArray(); // returns [2, 1, 3]

`recursive`

递归地将数组及其子元素转换为集合。

collect([
  'item' => [
     'children' => []
  ]   
])->recursive();

// subsequent arrays are now collections

在某些情况下，您可能不想将所有子元素转换为集合。您可以通过向递归方法提供数字来只转换到一定深度。

collect([
  'item' => [
     'children' => [
        'one' => [1],
        'two' => [2]
     ]
  ]   
])->recursive(1); // Collection(['item' => Collection(['children' => ['one' => [1], 'two' => [2]]])])

这在大约某个深度它将不再必要或可能破坏您的代码时很有用。

collect([
  'item' => [
     'children' => [
        'one' => [1],
        'two' => [2]
     ]
  ]   
])
  ->recursive(1)
  ->map(function ($item) {
    return $item->map(function ($children) {
      return $children->mapInto(Model::class);
    });
  }); // Collection(['item' => Collection(['children' => ['one' => Model(), 'two' => Model()]])])

// If we do not pass a max depth we will get the error "Argument #1 ($attributes) must be of type array"

`rotate`

以给定的偏移量旋转集合中的项目。

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

$rotate = $collection->rotate(1);

$rotate->toArray();

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

`sectionBy`

根据给定的键将集合拆分为部分。类似于 groupBy，但尊重集合中项目的顺序并重用现有键。

$collection = collect([
    ['name' => 'Lesson 1', 'module' => 'Basics'],
    ['name' => 'Lesson 2', 'module' => 'Basics'],
    ['name' => 'Lesson 3', 'module' => 'Advanced'],
    ['name' => 'Lesson 4', 'module' => 'Advanced'],
    ['name' => 'Lesson 5', 'module' => 'Basics'],
]);

$collection->sectionBy('module');

// [
//     ['Basics', [
//         ['name' => 'Lesson 1', 'module' => 'Basics'],
//         ['name' => 'Lesson 2', 'module' => 'Basics'],
//     ]],
//     ['Advanced', [
//         ['name' => 'Lesson 3', 'module' => 'Advanced'],
//         ['name' => 'Lesson 4', 'module' => 'Advanced'],
//     ]],
//     ['Basics', [
//         ['name' => 'Lesson 5', 'module' => 'Basics'],
//     ]],
// ];

完整签名：sectionBy($callback, $preserveKeys, $sectionKey, $itemsKey)

`simplePaginate`

为集合中的项目创建一个 Paginator 实例。

collect($posts)->simplePaginate(5);

此代码将 $posts 的内容分页为每页5个项目。 simplePaginate 接受许多选项，请查阅 Laravel 文档以获取深入了解。

simplePaginate(int $perPage = 15, string $pageName = 'page', int $page = null, int $total = null, array $options = [])

有关分页的深入了解，请参阅 Laravel 文档。

`sliceBefore`

在给定回调为 true 之前从集合中切出值。如果传递了可选参数 $preserveKeys 为 true，则将保留原始键。

collect([20, 51, 10, 50, 66])->sliceBefore(function($item) {
    return $item > 50;
}); // return collect([[20],[51, 10, 50], [66])

`tail`

从集合中提取尾部。即除了第一个元素之外的所有内容。这是 slice(1)->values() 的简写，但仍然非常实用。如果传递了可选参数 $preserveKeys 为 true，则将保留键，并回退到 slice(1)。

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

`toPairs`

将集合转换为一个成对的数组。

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

$collection->toArray(); // returns ['a', 'b'], ['c', 'd'], ['e', 'f']

`transpose`

转置的目标是旋转多维数组，将行转换为列，列转换为行。

collect([
    ['Jane', 'Bob', 'Mary'],
    ['jane@example.com', 'bob@example.com', 'mary@example.com'],
    ['Doctor', 'Plumber', 'Dentist'],
])->transpose()->toArray();

// [
//     ['Jane', 'jane@example.com', 'Doctor'],
//     ['Bob', 'bob@example.com', 'Plumber'],
//     ['Mary', 'mary@example.com', 'Dentist'],
// ]

`try`

如果在 try 和 catch 之间的任何方法抛出异常，则可以在 catch 中处理该异常。

collect(['a', 'b', 'c', 1, 2, 3])
    ->try()
    ->map(fn ($letter) => strtoupper($letter))
    ->each(function() {
        throw new Exception('Explosions in the sky');
    })
    ->catch(function (Exception $exception) {
        // handle exception here
    })
    ->map(function() {
        // further operations can be done, if the exception wasn't rethrow in the `catch`
    });

尽管这些方法命名为 try/catch 以便与 PHP 兼容，但集合本身的行为更像数据库事务。因此，当抛出异常时，将返回原始集合（在 try 之前）。

您可以通过向处理器添加第二个参数来在 catch 中访问集合。您还可以通过返回一个值来在 catch 中修改集合。

$collection = collect(['a', 'b', 'c', 1, 2, 3])
    ->try()
    ->map(function ($item) {
        throw new Exception();
    })
    ->catch(function (Exception $exception, $collection) {
        return collect(['d', 'e', 'f']);
    })
    ->map(function ($item) {
        return strtoupper($item);
    });

// ['D', 'E', 'F']

`validate`

如果给定的 $callback 对每个项目返回 true，则返回 true。如果 $callback 是字符串或数组，则将其视为验证规则。

collect(['foo', 'foo'])->validate(function ($item) {
   return $item === 'foo';
}); // returns true


collect(['sebastian@spatie.be', 'bla'])->validate('email'); // returns false
collect(['sebastian@spatie.be', 'freek@spatie.be'])->validate('email'); // returns true

`weightedRandom`

通过重量返回随机项目。在此示例中，具有 a 的项目被选中的机会最大，而具有 c 的项目被选中的机会最小。

// pass the field name that should be used as a weight

$randomItem = collect([
    ['value' => 'a', 'weight' => 30],
    ['value' => 'b', 'weight' => 20],
    ['value' => 'c', 'weight' => 10],
])->weightedRandom('weight');

或者，您可以通过传递可调用来获取重量。

$randomItem = collect([
    ['value' => 'a', 'weight' => 30],
    ['value' => 'b', 'weight' => 20],
    ['value' => 'c', 'weight' => 10],
])->weightedRandom(function(array $item) {
   return $item['weight'];
});

`withSize`

使用指定数量的项目创建一个新的集合。

Collection::withSize(1)->toArray(); // return [1];
Collection::withSize(5)->toArray(); // return [1,2,3,4,5];

变更日志

有关最近更改的信息，请参阅变更日志。

测试

$ composer test

贡献

有关详细信息，请参阅贡献指南。

安全性

如果您发现了关于安全性的错误，请通过电子邮件 security@spatie.be 而不是使用问题跟踪器。

鸣谢

关于 Spatie

Spatie是一家位于比利时安特卫普的网页设计公司。您可以在我们的网站上找到我们所有开源项目的概述在这里。

许可证

MIT 许可证 (MIT)。有关更多信息，请参阅许可证文件。

spatie / laravel-collection-macros

维护者

详细信息

README

支持我们

安装

宏

after

at

second

third

fourth

fifth

sixth

seventh

eighth

ninth

tenth

getNth

before

catch

chunkBy

collectBy

containsAny

containsAll

eachCons

extract

filterMap

firstOrFail

firstOrPush

fromPairs

getCaseInsensitive

glob

groupByModel

hasCaseInsensitive

head

if

ifAny

ifEmpty

insertAfter

insertAfterKey

insertAt

insertBefore

insertBeforeKey

none

paginate

path

pluckMany

pluckManyValues

pluckToArray

prioritize

recursive

rotate

sectionBy

simplePaginate

sliceBefore

tail

toPairs

transpose

try

validate

weightedRandom

withSize

变更日志

测试

贡献

安全性

鸣谢

关于 Spatie

许可证

`after`

`at`

`second`

`third`

`fourth`

`fifth`

`sixth`

`seventh`

`eighth`

`ninth`

`tenth`

`getNth`

`before`

`catch`

`chunkBy`

`collectBy`

`containsAny`

`containsAll`

`eachCons`

`extract`

`filterMap`

`firstOrFail`

`firstOrPush`

`fromPairs`

`getCaseInsensitive`

`glob`

`groupByModel`

`hasCaseInsensitive`

`head`

`if`

`ifAny`

`ifEmpty`

`insertAfter`

`insertAfterKey`

`insertAt`

`insertBefore`

`insertBeforeKey`

`none`

`paginate`

`path`

`pluckMany`

`pluckManyValues`

`pluckToArray`

`prioritize`

`recursive`

`rotate`

`sectionBy`

`simplePaginate`

`sliceBefore`

`tail`

`toPairs`

`transpose`

`try`

`validate`

`weightedRandom`

`withSize`