map

PHP 數組和集合變得簡單

透過使用 jQuery 和 Laravel Collections 提供的類似陣列的集合對象，輕鬆而優雅地處理 PHP 陣列。

作曲家要求 AIMEOS/地圖

支援的 PHP 版本：

• PHP 7.1+

• PHP 8+

目錄

• 為什麼選擇 PHP 地圖

• 方法列表

• 創造

• 使用權

• 添加

• 總計的

• 偵錯

• 命令

• 縮短

• 測試

• 突變

• 雜項

• 文件

• 自訂方法

• 表現

• 升級指南

為什麼選擇 PHP 地圖

而不是：

 $list = [['id' => '一', 'value' => '值1'], ['id' => '二', 'value' => '值2'], null];$ list[ ] = ['id'=>'三','值'=>'值3'];    // 新增 elementunset( $list[0] );                                   // 刪除元素$list = array_filter( $list );                       // 刪除空值sort( $list );                                       // 將元素排序$pairs = array_column( $list, 'value', 'id' );       // 建立 ['三' => 'value3']$value = Reset( $pairs ) ?: null;                    // 傳回第一個值

僅使用：

 $list = [['id' => '一', 'value' => '值1'], ['id' => '二', 'value' => '值2'], null];$ value = map( $list ) // 建立Map->push( ['id' => ' Three', 'value' => 'value3'] ) // 新增元素->remove( 0 ) // 刪除元素- >filter () // 刪除空值->sort() // 對元素進行排序->col( 'value', 'id' ) // create ['two' => 'value3']->first() ;                                       // 傳回第一個值

您仍然可以使用：

 $map[] = ['id' => '三', 'value' => 'value3'];$value = $map[0];count( $map );foreach( $map as $key => value ）；

使用回調：

此外，映射物件允許您將匿名函數傳遞給許多方法，例如：

 $map->each( function( $val, $key ) { echo $key . ': ' . $val;
} );

jQuery 風格：

如果你的地圖元素是對象，你可以為每個對象呼叫它們的方法，並將結果作為新地圖獲取，就像在 jQuery 中一樣：

 // MyClass 實作setStatus() （傳回$this）與getCode() （由建構子初始化）$map = Map::from( ['a' => new MyClass( 'x' ), 'b' => new MyClass ( 'y' )] );$map->setStatus( 1 )->getCode()->toArray();

這將在兩個物件上呼叫setStatus( 1 ) 。如果setStatus()實作傳回$this ，則新映射也將包含：

 ['a' => MyClass(), 'b' => MyClass()]

在這些新的地圖元素上，將呼叫getCode()它為第一個物件傳回x ，為第二個物件傳回y 。從getCode()結果建立的地圖將會傳回：

 ['a' => 'x', 'b' => 'y']

方法

function map function is_map __call __callStatic __construct after all arsort arsorted asorted at avg before bool callcast chunkclearclonecolcollapsecombinecompareconcat containscopycountcountBydddelimiterdKeyd flip float from fromJson get getIterator grep groupBy has if ifAny ifEmpty 實作在包含索引insertAfter insertAt insertBefore inString int intersect intersectAssoc intersectKeys is isEmpty int interricis isectAssoc intersectKeys is isEmpty isNumeric is isectAssoc isectKeys is isEmpty isNumeric join jsonSerialize keys krsort krsorted ksort last lastKey ltrim map max merge method min none nth offsetExists offsetGet offsetSet offsetUnset only 順序刪除分區管道rsorted rtrim 搜尋sep set 移位shuffle 混洗跳過切片某種排序排序拼接split strAfter strContains strContainsAll strEnds strEndsAll string strLower strReplace strStarts strStartsAll strUpper 字尾總和取變樹時點擊樹數ted union unique unshift usort usorted value walk where with zip

創造

• function map() ：從傳遞的元素建立一個新的映射

• __construct() ：建立一個新地圖

• clone() ：克隆地圖及其中的所有對象

• copy() ：建立一個新副本

• explode() ：將字串拆分為元素映射

• from() ：從傳遞的元素建立一個新映射

• fromJson() ：從 JSON 字串建立新地圖

• times() ：透過多次呼叫閉包來建立一個新地圖

• tree() ：從列表項目建立樹狀結構

使用權

• __call() ：呼叫自訂方法

• __callStatic() ：靜態呼叫自訂方法

• all() ：傳回普通數組

• at() ：傳回給定位置的值

• bool() ：透過鍵傳回一個元素並將其轉換為布林值

• call() ：對所有項目呼叫給定方法

• find() ：傳回第一個/最後一個符合元素

• first() ：傳回第一個元素

• firstKey() ：傳回第一個鍵

• get() ：按鍵返回元素

• index() ：傳回給定鍵的數字索引

• int() ：按鍵傳回一個元素並將其轉換為整數

• float() ：按鍵傳回一個元素並將其轉換為 float

• keys() ：傳回所有鍵

• last() ：傳回最後一個元素

• lastKey() ：傳回最後一個鍵

• pop() ：傳回並刪除最後一個元素

• pos() ：傳回值的數字索引

• pull() ：透過鍵返回並刪除元素

• random() ：傳回保留金鑰的隨機元素

• search() ：找出元素的鍵

• shift() ：傳回並刪除第一個元素

• string() ：按鍵返回元素並將其轉換為字串

• toArray() ：傳回普通數組

• unique() ：傳回保留鍵的所有唯一元素

• value() ：傳回具有新鍵的所有元素

添加

• concat() ：使用新鍵新增所有元素

• insertAfter() ：在給定元素之後插入值

• insertAt() ：在地圖中的給定位置插入元素

• insertBefore() ：在給定元素之前插入值

• merge() ：合併元素並覆蓋現有元素

• pad() ：用給定值填滿到指定長度

• prepend() ：在開頭加入一個元素（別名）

• push() ：在末尾加上一個元素

• put() ：在映射中設定給定的鍵和值（別名）

• set() ：覆蓋或新增元素

• union() ：新增元素而不覆蓋現有元素

• unshift() ：在開頭新增一個元素

• with() ：傳回一個副本並設定一個元素

總計的

• avg() ：傳回所有值的平均值

• count() ：傳回元素總數

• countBy() ：計算相同值在地圖中出現的頻率

• max() ：傳回所有元素的最大值

• min() ：傳回所有元素的最小值

• Percentage() ：傳回所有通過測試的元素的百分比

• sum() ：傳回映射中所有值的總和

偵錯

• dd() ：列印地圖內容並終止腳本

• dump() ：列印地圖內容

• tap() ：將地圖的克隆傳遞給給定的回調

訂購依據

• arsort() ：保留鍵的反向排序元素

• asorted() ：反向排序元素，保留映射副本中的鍵

• asort() ：對保留鍵的元素進行排序

• asorted() ：對元素進行排序，保留映射副本中的鍵

• krsort() ：按鍵對元素進行反向排序

• krsorted() ：按映射副本中的鍵對元素進行反向排序

• ksort() ：按鍵對元素進行排序

• order() ：按傳遞的鍵對元素進行排序

• reverse() ：反轉數組順序並保留鍵

• returned() ：反轉映射副本中的元素順序

• toReversed() ：反轉映射副本中的元素順序（別名）

• rsort() ：使用新鍵對元素進行反向排序

• rsorted() ：使用映射副本中的新鍵對元素進行反向排序

• shuffle() ：隨機化元素順序

• shuffled() ：隨機化映射副本中的元素順序

• sort() ：對分配新鍵的元素進行就地排序

• sorted() ：使用新鍵對映射副本中的元素進行排序

• toSorted() ：使用新鍵（別名）對映射副本中的元素進行排序

• uasort() ：使用回呼對保留鍵的元素進行排序

• uasorted() ：使用映射副本中的回調對保留鍵的元素進行排序

• uksort() ：使用回呼按鍵對元素進行排序

• uksorted() ：使用映射副本中的回調按鍵對元素進行排序

• usort() ：使用回呼分配新鍵對元素進行排序

• usorted() ：使用回呼在映射副本中指派新鍵對元素進行排序

縮短

• after() ：傳回給定元素之後的元素

• before() ：傳回給定元素之前的元素

• clear() ：刪除所有元素

• diff() ：傳回給定清單中缺少的元素

• diffAssoc() ：傳回給定清單中缺少的元素並檢查鍵

• diffKeys() ：按鍵傳回給定清單中缺少的元素

• except() ：傳回一個沒有傳遞元素鍵的新映射

• filter() ：對所有元素套用過濾器

• grep() ：將正規表示式套用至所有元素

• intersect() ：傳回共享的元素

• intersectAssoc() ：傳回共享元素並檢查鍵

• intersectKeys() ：傳回鍵共享的元素

• nth() ：傳回映射中的每個第 n 個元素

• only() ：僅傳回鍵指定的元素

• pop() ：傳回並刪除最後一個元素

• pull() ：透過鍵返回並刪除元素

• reject() ：刪除所有符合的元素

• remove() ：透過鍵刪除元素

• shift() ：傳回並刪除第一個元素

• Skip() ：跳過給定數量的項目並返回其餘項目

• slice() ：傳回地圖的切片

• take() ：傳回具有給定項目數的新地圖

• where() ：依給定條件篩選元素列表

測試

• function is_map() ：測試變數是否為映射對象

• compare() ：將值與所有映射元素進行比較

• contains() ：測試地圖中是否存在項目

• each() ：對每個元素應用回調

• empty() ：測試地圖是否為空

• equals() ：測試地圖內容是否相等

• every() ：驗證所有元素是否通過給定回呼的測試

• has() ：測試鍵是否存在

• if() ：根據條件執行回調

• ifAny() ：如果地圖包含元素則執行回呼

• ifEmpty() ：如果地圖為空則執行回調

• in() ：測試是否包含元素

• include() ：測試是否包含元素

• inString() ：測試該項目是否為地圖中字串的一部分

• is() ：測試映射是否包含相同的鍵和值

• isEmpty() ：測試地圖是否為空

• isNumeric() ：測試所有條目是否都是數值

• isObject() ：測試所有條目是否都是對象

• isScalar() ：測試所有條目是否都是標量值。

• isString() ：測試所有條目是否都是字串值。

• Implements() ：測試所有條目是否都是實作介面的對象

• none() ：測試是否沒有元素屬於映射

• some() ：測試是否至少包含一個元素

• strContains() ：測試至少一個傳遞的字串是否是至少一個條目的一部分

• strContainsAll() ：測試所有條目是否包含傳遞的字串之一

• strEnds() ：測試是否至少有一個條目以傳遞的字串之一結尾

• strEndsAll() ：測試所有條目是否至少以傳遞的字串之一結尾

• strStarts() ：測試至少一個條目是否以至少一個傳遞的字串開頭

• strStartsAll() ：測試所有條目是否以傳遞的字串之一開頭

突變

• cast() ：將所有條目轉換為傳遞的類型

• chunk() ：將地圖分割成區塊

• col() ：建立鍵/值映射

• crash() ：折疊多維元素覆蓋元素

• 組合（）：將地圖元素作為鍵與給定值組合起來

• flat() ：展平多維元素而不覆蓋元素

• Flip() ：將鍵與其值交換

• groupBy() ：將關聯數組元素或物件分組

• join() ：將連接的元素作為帶分隔符號的字串傳回

• ltrim() ：從所有字串的左側刪除傳遞的字符

• map() ：對每個元素應用回調並傳回結果

• partition() ：將列表分成給定數量的群組

• pipeline() ：對整個映射套用回調

• pluck() ：建立鍵/值映射（別名）

• prefix() ：為每個映射條目加上前綴

• reduce() ：根據地圖內容計算單一值

• rekey() ：根據傳遞的函數更改金鑰

• Replace() ：遞歸替換元素

• rtrim() ：刪除所有字串右側傳遞的字符

• splice() ：用新元素取代切片

• strAfter() ：傳回傳遞值之後的字串

• strLower() ：將所有字母字元轉換為小寫

• strReplace() ：用替換字串取代所有出現的搜尋字串

• strUpper() ：將所有字母字元轉換為大寫

• suffix() ：為每個映射條目添加後綴

• toJson() ：以 JSON 格式傳回元素

• toUrl() ：建立 HTTP 查詢字串

• transfrom() ：對建立新鍵/值對的每個元素套用回調

• transpose() ：交換二維映射的行和列

• traverse() ：遍歷巢狀項目樹，將每個項目傳遞給回調

• Trim() ：從所有字串的左側/右側刪除傳遞的字符

• walk() ：將給定的回呼套用至所有元素

• zip() ：合併對應索引處所有陣列的值

雜項

• delimiter() ：設定或傳回多維數組路徑的分隔符

• getIterator() ：傳回元素的迭代器

• jsonSerialize() ：指定應序列化為 JSON 的數據

• method() ：註冊自訂方法

• offsetExists() ：檢查鍵是否存在

• offsetGet() ：按鍵返回元素

• offsetSet() ：覆蓋一個元素

• offsetUnset() ：透過鍵刪除元素

• sep() ：設定目前映射中多維數組的路徑分隔符

方法文檔

is_map() 函數

測試變數是否為映射對象

函數 is_map( $var ) : bool

• @param mix $var要測試的變數

範例：

 is_map( new Map() );// trueis_map( [] );// false

地圖()函數

傳回傳遞的元素的新映射。

函數映射( $elements = [] ) : AimeosMap

• @param mix $elements元素列表或單一值

• @return AimeosMap地圖實例

範例：

 // arraymap( [] );// nullmap( null );// scalarmap( 'a' );// objectmap( new stdClass() );// 映射objectmap( new Map() );// 可迭代objectmap ( new ArrayObject() );// 閉包計算 lazilymap( function() {return [];
} );

參見：

• rekey() - 根據傳遞的函式變更金鑰

• Transform() - 使用傳遞的函數建立新的鍵/值對並傳回結果的新映射

__構造（）

建立一個新的地圖物件。

公共函數 __construct( $elements = [] )

• @param mix $elements單一元素、元素列表、Map 物件、可迭代物件或迭代器、其他所有內容

範例：

 // arraynew Map( [] );// nullnew Map( null );// 標量 new Map( 'a' );// objectnew Map( new stdClass() );// 映射objectnew Map( new Map() ) ; // 可迭代物件 new Map( new ArrayObject() );// 閉包延遲計算 new Map( function() {return [];
} );

__稱呼（）

處理對類別的自訂方法的動態呼叫。

公用函數 __call( 字串 $name, 陣列 $params )

• @param string $name方法名稱

• @param array<mixed> $params參數列表

• @return 被呼叫函數或新映射的混合結果以及元素方法的結果

呼叫Map::method()新增的自訂方法。被呼叫的方法可以使用$this->items存取內部陣列。

範例：

 Map::method( 'case', function( $case = CASE_LOWER ) {return new self( array_change_key_case( $this->items, $case ) );
} );

Map::from( ['a' => 'bar'] )->case( CASE_UPPER );// ['A' => 'bar']

如果項目是對象，這也允許呼叫對象方法：

 $item = new MyClass(); // 使用方法 setStatus() （傳回 $this）與 getCode() ImplementMap::from( [$item, $item] )->setStatus( 1 )->getCode()->toArray();

這將呼叫映射中每個元素的setStatus()方法，並使用它們的回傳值建立一個新映射。在新映射上，為每個元素呼叫getCode()方法，其傳回值也儲存在新映射中。然後返回最後一個映射，並且原始映射中的映射鍵將保留在返回的映射中。

如果元素不是對象，則跳過它們，如果這適用於所有元素，則傳回空映射。如果映射包含混合類型的對象，並且其中一個對象未實現所調用的方法，則會拋出錯誤。

__callStatic()

處理對類別的自訂方法的靜態呼叫。

公用靜態函數 __callStatic( 字串 $name, 陣列 $params )

• @param string $name方法名稱

• @param array<mixed> $params參數列表

• @return 被呼叫函數或新映射的混合結果以及元素方法的結果

• @throws BadMethodCallException如果沒有為該名稱註冊任何方法

靜態呼叫 Map::method() 新增的自訂方法。被呼叫的方法無法存取內部數組，因為沒有可用的物件。

範例：

地圖::method( 'foo', function( $arg1, $arg2 ) {} );
地圖::foo( $arg1, $arg2 );

後（）

傳回給定元素之後的元素。

 ($value) 之後的公用函數：self

• @param Closure|int|string $value帶有 (item, key) 參數的值或函數

• @return self<int|string,mixed>包含給定元素之後元素的新映射

使用此方法儲存密鑰。

範例：

 Map::from( [0 => 'b', 1 => 'a'] )->after( 'b' );// [1 => 'a']Map::from( ['a' = > 1, 'b' => 0] )->after( 1 );// ['b' => 0]Map::from( [0 => 'b', 1 => 'a'] )- >after( 'c' );// []Map::from( ['a', 'c', 'b'] )->after( function( $item, $key ) {return $item >= ' c'；
} );// [2 => 'b']

全部（）

以普通數組的形式傳回元素。

公用函數 all() ：數組

• @return array普通數組

範例：

 Map::from( ['a'] )->all();// ['a']

排序()

按相反順序對所有元素進行排序並保持鍵關聯。

公用函數 arsort( int $options = SORT_REGULAR ) : self

• @param int $options arsort()的排序選項

• @return self<int|string,mixed>更新了流體介面的地圖

使用此方法保留密鑰並且不會建立新的映射。

$options參數修改值的比較方式。可能的參數值為：

• SORT_REGULAR ：正常比較元素（不更改型別）

• SORT_NUMERIC ：以數字方式比較元素

• SORT_STRING ：將元素當作字串進行比較

• SORT_LOCALE_STRING ：根據當前語言環境或透過setlocale()更改，將元素作為字串進行比較

• SORT_NATURAL ：使用「自然排序」（如natsort()將元素作為字串進行比較

• SORT_FLAG_CASE ：使用 SORT_STRING|SORT_FLAG_CASE 和 SORT_NATURAL|SORT_FLAG_CASE 對字串進行不區分大小寫的排序

範例：

 Map::from( ['b' => 0, 'a' => 1] )->arsort();// ['a' => 1, 'b' => 0]Map::from( [ 'a', 'b'] )->arsort();// ['b', 'a']Map::from( [0 => 'C', 1 => 'b'] )->arsort ();// [1 => 'b', 0 => 'C']Map::from( [0 => 'C', 1 => 'b'] )->arsort( SORT_STRING|SORT_FLAG_CASE ); // [0 => 'C', 1 => 'b'] 因為'C' -> 'c' 且'c' > 'b'

分類()

按相反順序對所有元素的副本進行排序並維護鍵關聯。

公用函數 Arsorted( int $options = SORT_REGULAR ) : self

• @param int $options arsort()的排序選項

• @return self<int|string,mixed>更新了流體介面的地圖

使用此方法保留密鑰並建立新的映射。

$options參數修改值的比較方式。可能的參數值為：

• SORT_REGULAR ：正常比較元素（不更改型別）

• SORT_NUMERIC ：以數字方式比較元素

• SORT_STRING ：將元素當作字串進行比較

• SORT_LOCALE_STRING ：根據當前語言環境或透過setlocale()更改，將元素作為字串進行比較

• SORT_NATURAL ：使用「自然排序」（如natsort()將元素作為字串進行比較

• SORT_FLAG_CASE ：使用 SORT_STRING|SORT_FLAG_CASE 和 SORT_NATURAL|SORT_FLAG_CASE 對字串進行不區分大小寫的排序

範例：

 Map::from( ['b' => 0, 'a' => 1] )->arsorted();// ['a' => 1, 'b' => 0]Map::from( [ 'a', 'b'] )->arsorted();// ['b', 'a']Map::from( [0 => 'C', 1 => 'b'] )->arsorted ();// [1 => 'b', 0 => 'C']Map::from( [0 => 'C', 1 => 'b'] )->arsorted( SORT_STRING|SORT_FLAG_CASE ); // [0 => 'C', 1 => 'b'] 因為'C' -> 'c' 且'c' > 'b'

分類()

對所有元素進行排序並維護鍵關聯。

公用函數 asort( int $options = SORT_REGULAR ) : self

• @param int $options asort()的排序選項

• @return self<int|string,mixed>更新了流體介面的地圖

使用此方法保留密鑰並且不會建立新的映射。

此參數修改值的比較方式。可能的參數值為：

• SORT_REGULAR ：正常比較元素（不更改型別）

• SORT_NUMERIC ：以數字方式比較元素

• SORT_STRING ：將元素當作字串進行比較

• SORT_LOCALE_STRING ：根據當前語言環境或透過setlocale()更改，將元素作為字串進行比較

• SORT_NATURAL ：使用「自然排序」（如natsort()將元素作為字串進行比較

• SORT_FLAG_CASE ：使用 SORT_STRING|SORT_FLAG_CASE 和 SORT_NATURAL|SORT_FLAG_CASE 對字串進行不區分大小寫的排序

範例：

 Map::from( ['a' => 1, 'b' => 0] )->asort();// ['b' => 0, 'a' => 1]Map::from( [ 0 => 'b', 1 => 'a'] )->asort();// [1 => 'a', 0 => 'b']Map::from( [0 => 'C' , 1 => 'b'] )->asort();// [0 => 'C', 1 => 'b'] 因為'C' < 'b'Map::from( [0 => ' C', 1 => 'b'] )->arsort( SORT_STRING|SORT_FLAG_CASE );// [1 => 'b', 0 => 'C'] 因為'C' -> 'c' 和'c' > 'b'

分類()

對所有元素的副本進行排序並維護鍵關聯。

公用函數 asorted( int $options = SORT_REGULAR ) : self

• @param int $options asort()的排序選項

• @return self<int|string,mixed>更新了流體介面的地圖

使用此方法保留密鑰並建立新的映射。

此參數修改值的比較方式。可能的參數值為：

• SORT_REGULAR ：正常比較元素（不更改型別）

• SORT_NUMERIC ：以數字方式比較元素

• SORT_STRING ：將元素當作字串進行比較

• SORT_LOCALE_STRING ：根據當前語言環境或透過setlocale()更改，將元素作為字串進行比較

• SORT_NATURAL ：使用「自然排序」（如natsort()將元素作為字串進行比較

• SORT_FLAG_CASE ：使用 SORT_STRING|SORT_FLAG_CASE 和 SORT_NATURAL|SORT_FLAG_CASE 對字串進行不區分大小寫的排序

範例：

 Map::from( ['a' => 1, 'b' => 0] )->asorted();// ['b' => 0, 'a' => 1]Map::from( [ 0 => 'b', 1 => 'a'] )->asorted();// [1 => 'a', 0 => 'b']Map::from( [0 => 'C' , 1 => 'b'] )->asorted();// [0 => 'C', 1 => 'b'] 因為'C' < 'b'Map::from( [0 => ' C', 1 => 'b'] )->asorted( SORT_STRING|SORT_FLAG_CASE );// [1 => 'b', 0 => 'C'] 因為'C' -> 'c' 和'c' > 'b'

在（）

傳回給定位置的值。

公用函數 at( int $pos )

• @param int $pos值在地圖中的位置

• @return mix�null給定位置的值或 NULL（如果沒有可用值）

位置從零開始，位置「0」傳回映射的第一個元素，「1」傳回第二個元素，依此類推。如果位置為負，則序列將從地圖末端開始。

範例：

 Map::from( [1, 3, 5] )->at( 0 );// 1Map::from( [1, 3, 5] )->at( 1 );// 3Map::from( [ 1, 3, 5] )->at( -1 );// 5Map::from( [1, 3, 5] )->at( 3 );// NULL

平均（）

傳回地圖中所有整數和浮點數值的平均值。

公用函數 avg( $col = null ) : 浮點數

• @param Closure|string|null $col嵌套數組或物件中值的閉包、鍵或路徑，用於計算平均值

• @return float所有元素的平均值，如果地圖中沒有元素則為 0

NULL 值被視為 0，非數字值將產生誤差。

這也適用於多維數組，透過傳遞由分隔符號（預設為「/」）分隔的數組鍵，例如「key1/key2/key3」從['key1' => ['key2' => ['key3' => 'val']]] 。這同樣適用於物件的公共屬性或實作__isset()和__get()方法的物件。

範例：

 Map::from( [1, 3, 5] )->avg();// 3Map::from( [1, null, 5] )->avg();// 3Map::from( [1, 'sum', 5] )->avg();// 2Map::from( [['p' => 30], ['p' => 50], ['p' => 10]] )- >avg( 'p' );// 30Map::from( [['i' => ['p' => 30]], ['<sp