add join method

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 All notable changes to `laravel-collection-macros` will be documented in this file
 
+## 4.3.0 - 2019-02-25
+- add `join` macro
 
 ## 4.2.0 - 2018-12-16
 - add `head` macro

README.md

@@ -55,6 +55,7 @@ The package will automatically register itself.
 - [`head`](#head)
 - [`ifAny`](#ifany)
 - [`ifEmpty`](#ifempty)
+- [`join`](#join)
 - [`none`](#none)
 - [`paginate`](#paginate)
 - [`parallelMap`](#parallelmap)
@@ -373,6 +374,22 @@ collect([1, 2, 3])->ifEmpty(function(Collection $collection) { // non-empty coll
 });
 ```
 
+### `join`
+
+Join all items from the collection using a string. The final item can be glued with another string.
+
+```php
+collect(['a', 'b', 'c']))->join(', ')); // returns 'a, b, c'
+
+collect(['a', 'b', 'c']))->join(', ', ' and ')); // returns 'a, b and c'
+
+collect(['a', 'b']))->join(', ', ' and ')); // returns 'a and b'
+
+collect(['a']))->join(', ', ' and ')); // returns 'a'
+
+collect([]))->join(', ', ' and ')); // returns ''
+```
+
 ### `none`
 
 Checks whether a collection doesn't contain any occurrences of a given item, key-value pair, or passing truth test. The function accepts the same parameters as the `contains` collection method.

src/macros/join.php

@@ -0,0 +1,27 @@
+<?php
+
+use Illuminate\Support\Collection;
+
+/*
+ * Join all items from the collection using a string. The final items can use a seperate glue string.
+ *
+ */
+Collection::macro('join', function (string $glue, string $finalGlue = ''): string {
+    if ($finalGlue === '') {
+        return $this->implode($glue);
+    };
+
+    if ($this->count() === 0) {
+        return '';
+    }
+
+    if ($this->count() === 1) {
+        return $this->last();
+    }
+
+    $collection = new Collection($this->items);
+
+    $finalItem = $collection->pop();
+
+    return $collection->implode($glue) . $finalGlue . $finalItem;
+});

tests/Macros/JoinTest.php

@@ -0,0 +1,23 @@
+<?php
+
+namespace Spatie\CollectionMacros\Test\Macros;
+
+use Illuminate\Support\Collection;
+use Spatie\CollectionMacros\Test\TestCase;
+
+class JoinTest extends TestCase
+{
+    /** @test */
+    public function it_can_join_items_in_the_collection()
+    {
+        $this->assertEquals('a, b, c', (new Collection(['a', 'b', 'c']))->join(', '));
+
+        $this->assertEquals('a, b and c', (new Collection(['a', 'b', 'c']))->join(', ', ' and '));
+
+        $this->assertEquals('a and b', (new Collection(['a', 'b']))->join(', ', ' and '));
+
+        $this->assertEquals('a', (new Collection(['a']))->join(', ', ' and '));
+
+        $this->assertEquals('', (new Collection([]))->join(', ', ' and '));
+    }
+}