Download the PHP package eftec/arrayone without Composer

ArrayOne

It is a minimalist library that process arrays in PHP with no dependency.

This library is focused to work with business data(reading/saving files, database records, API, etc.), so it is not similar to Numpy, Pandas, NumPHP or alike because they target difference objectives. It is more closely similar to Microsoft PowerQuery and Linq. What it does? Filter, order, renaming column, grouping, validating, amongst many other operations.

• [x] it works with PHP arrays. PHP arrays allows hierarchy structures using indexed and/or associative values.
• [x] It is aimed at speed.
• [x] It is minimalist, using the minimum of dependencies and only 1 PHP class. Do you hate when a simple library adds a whole framework as dependency? Well, not here.
• [x] It works using fluent/nested notations.
• [x] Every method is documented using PhpDoc.

[]() []() []() []() []()

• ArrayOne
  • Basic examples
  • Getting started
  • Concepts
  • Class ArrayOne
  • Method __construct()
    • Parameters:
  • Method isIndexArray()
    • Parameters:
  • Method isIndexTableArray()
    • Parameters:
  • Method makeRequestArrayByExample()
    • Parameters:
  • Method makeValidateArrayByExample()
    • Parameters:
  • Method makeWalk()
    • Parameters:
  • Method set()
    • Parameters:
  • Method setCsv()
    • Parameters:
  • Method setCsvHeadLess()
    • Parameters:
  • Method setJson()
    • Parameters:
  • Method setRequest()
    • Parameters:
  • Method aggr()
    • Parameters:
  • Method all()
  • Method avg()
    • Parameters:
  • Method col()
    • Parameters:
  • Method colRename()
    • Parameters:
  • Method columnToIndex()
    • Parameters:
  • Method count()
  • Method filter()
    • Parameters:
  • Method find()
    • Parameters:
  • Method first()
  • Method flat()
  • Method getAll()
  • Method getVersion()
  • Method group()
    • Parameters:
  • Method indexToCol()
    • Parameters:
  • Method isIndex()
  • Method isIndexTable()
  • Method isValid()
  • Method join()
    • Parameters:
  • Method keepCol()
    • Parameters:
  • Method last()
  • Method map()
    • Parameters:
  • Method mask()
    • Parameters:
  • Method max()
    • Parameters:
  • Method min()
    • Parameters:
  • Method modCol()
    • Parameters:
  • Method nPos()
    • Parameters:
  • Method offsetExists()
  • Method offsetGet()
    • Parameters:
  • Method offsetSet()
    • Parameters:
  • Method offsetUnset()
    • Parameters:
  • Method reduce()
    • Parameters:
  • Method removeCol()
    • Parameters:
  • Method removeDuplicate()
    • Parameters:
  • Method removeFirstRow()
    • Parameters:
  • Method removeLastRow()
    • Parameters:
  • Method removeRow()
    • Parameters:
  • Method rowToValue()
    • Parameters:
  • Method shuffle()
  • Method sort()
    • Parameters:
  • Method splitColumn()
    • Parameters:
  • Method sum()
    • Parameters:
  • Method validate()
    • Parameters:
  • versions
  • License

Basic examples

Getting started

First, you must install the library. You can download this library or use Composer for its installation:

composer require eftec/arrayone

Once the library is installed and included, you can use as:

Concepts

• indexed and named fields works similarly.
• Sometimes, some field contains an array of values that behave like a table (see table field)

Class ArrayOne

Class ArrayOne

Method __construct()

Constructor
You can use (new ArrayOne($array))->method() or use ArrayOne::set($array)->method();

Parameters:

• $array param array|null $array (array|null)

  Method isIndexArray()

  Returns true if the array is an indexed array. It does not scan the whole array, but instead it only returns true if the index 0 exists, and it is the first value.
  Example:

Parameters:

• $value the value to analize. (mixed)

  Method isIndexTableArray()

  It returns true if the value is an indexed array with the first value an array (i.e. a table) Example:

Parameters:

• $value param mixed $value (mixed)

  Method makeRequestArrayByExample()

  It creates an associative array that could be used to be used by setRequest()
  Example:

Parameters:

• $array An associative array with some values. (array)
• $type =['get','post','request','header','cookie'][$i] The default type (string)

  Method makeValidateArrayByExample()

  It generates a validate-array using an example array. It could be used by validation() and filter()
  Example:

Parameters:

• $array param array $array (array)

  Method makeWalk()

  We call a method for every element of the array recursively.
  Example:

Parameters:

• $array Our initial array (array)
• $method the method to call, example: function($row,$index) { return $row; } (callable)
• $identifyTable (def: false) if we want the array identify inside arrays as table (bool)

  Method set()

  It sets the array to be transformed, and it starts the pipeline
  It must be the first operator unless you are using the constructor. Example:

Parameters:

• $array param array|null $array (array|null)
• $service the service instance. You can use the class or an object. (object|null|string)

  Method setCsv()

  It sets the array using a csv. This csv must have a header.
  Example:

Parameters:

• $string the string to parse (string)
• $separator default ",". Set the field delimiter (one character only). (string)
• $enclosure default '"'. Set the field enclosure character (one character only). (string)
• $escape default "\". Set the escape character (one character only). (string)

  Method setCsvHeadLess()

  It sets the array using a head-less csv.
  Example:

Parameters:

• $string the string to parse (string)
• $header If the header is null, then it creates an indexed array.
  if the header is an array, then it is used as header (array|null)
• $separator default ",". Set the field delimiter (one character only). (string)
• $enclosure default '"'. Set the field enclosure character (one character only). (string)
• $escape default "\". Set the escape character (one character only). (string)

  Method setJson()

  It sets the array using a json. Example:

Parameters:

• $json param string $json (string)

  Method setRequest()

  It sets the initial array readint the values from the request (get/post/header/etc.)
  Example:

Parameters:

• $fields An associative array when the values to read 'id'=>'type;defaultvalue'. Types:
  get: get it from the query string
  post: get it from the post
  header: get if from the header
  request: get if from the post, otherwise from get
  cookie: get if from the cookies
  body: get if from the post body (values are not serialized)
  verb: get if from the request method (GET/POST/PUT,etc.)
  (array)
• $defaultValueAll the default value if the value is not found and not other default value is set. (mixed)
• $separator Def:'.', The separator character used when the field is nested.
  example using '.' as separator html:
  result obtained:$result['a']['b']='hello'; (?string)

  Method aggr()

  Returns the aggregates value of a column
  Example:

Parameters:

• $type =['max','min','avg','count','sum'][$i] (string)
• $colName the column to aggregate (count does not require a column) (?mixed)
• $getKey if false (default), it returns the value obtained. if true, it returns the key. (bool)

  Method all()

  Returns the whole array transformed and not only the current navigation.
  Example:

Method avg()

Returns the average value of a specific column
Example:

Parameters:

• $colName the column (mixed)

  Method col()

  Returns a single column as an array of values.
  Example:

Parameters:

• $colName the name of the column (mixed)

  Method colRename()

  It renames a column (or multiples columns) with a different name.
  Example:

Parameters:

• $colName the name of the column or columns (string|array)
• $newColName the name of the column or columns (string|array)

  Method columnToIndex()

  it converts a column into an index
  Example:

Parameters:

• $oldColumn the old column. This column will be converted into an index (mixed)

  Method count()

  Returns the count of an array
  Example:

Method filter()

It filters the values. If the condition is false, then the row is deleted. It uses array_filter()
The indexes are not rebuilt.
Example:

Parameters:

• $condition you can use a callable function ($row,$id):true {}
  or a comparison array ['id'=>'eq;2|lt;3'] "|" adds more comparisons
  or a comparison array [['id=>['eq',2]],['id'=>['lt',3]]]
  (callable|null|array)
• $flat param bool $flat (bool)

  Method find()

  It returns an array with the key and values of the elements that matches the condition.
  Example:

Parameters:

• $condition you can use a callable function ($row,$id):bool {}
  or a comparison array ['id'=>'eq;2|lt;3'] "|" adds more comparisons
  or a comparison array [['id=>['eq',2]],['id'=>['lt',3]]]
  (callable|null|array)
• $onlyFirst if true then it only returns the first value (bool)
• $mode =['all','key','value'] // (default is all)
  all returns the key and the value obtained
  key only returns the key
  value only returns the value (string)

  Method first()

  It returns the first element of an array.

  Method flat()

  It flats the results. If the result is an array with a single row, then it returns the row without the array
  Example:

Method getAll()

Clone of a(). This method returns the whole array transformed and not only the current navigation.
Example:

Method getVersion()

It gets the current version of the library

Method group()

It groups one column and return its column grouped and values aggregated
Example:

Parameters:

• $columnToGroup the column (or columns) to group. (mixed)
• $funcAggreg An associative array ['col-to-aggregate'=>'aggregation']
  or ['new-col'=>'aggregation(col-to-agregate)']
  or ['col-to-aggr'=>function($cumulate,$row) {}]
  or ['col-to-aggr'=>[function($cumulate,$row){},function($cumulate,$numRows){}]
  stack: It stack the rows grouped by the column
  count: Count
  avg: Average
  min: Minimum
  max: Maximum
  sum: Sum
  first: First
  last: last
  group: The grouped value
  function:$cumulate: Is where the value will be accumulated, initially is null
  function:$row: The current value of the row
  (array)
• $useGroupIndex (def true), if true, then the result will use the grouped value as index
  if false, then the result will return the values as an indexed array. (bool)

  Method indexToCol()

  It converts the index into a column, and converts the array into an indexed array
  Example:

Parameters:

• $newColumn the name of the new column (mixed)

  Method isIndex()

  It is the dynamic version of the method isIndexArray.
  

  Method isIndexTable()

  The dynamic version of the method isIndexTableArray()

  Method isValid()

Method join()

Joins the current array with another array
If the columns of both arrays have the same name, then the current name is retained.
Example:

Parameters:

• $arrayToJoin param array|null $arrayToJoin (array|null)
• $column1 the column of the current array (mixed)
• $column2 the column of the array to join. (mixed)

  Method keepCol()

  It keeps a column or columns and removes the rest of columns
  Example:

Parameters:

• $colName The name of the column or columns (array) (mixed)

  Method last()

  It returns the last element of an array.

  Method map()

  It calls a function for every element of an array
  Example:

Parameters:

• $condition The function to call.
  It must have an argument (the current row) and it must return a value (callable|null)

  Method mask()

  It masks the current array using another array.
  Masking deletes all field that are not part of our mask
  The mask is smart to recognize a table, so it could mask multiples values by only specifying the first row.
  Example:

Parameters:

• $arrayMask An associative array with the mask. The mask could contain any value. (array)

  Method max()

  Returns the max of a specific column
  Example:

Parameters:

• $colName the column (mixed)
• $getKey param bool $getKey (bool)

  Method min()

  Returns the min of a specific column
  Example:

Parameters:

• $colName the column (mixed)
• $getKey param bool $getKey (bool)

Method minRow()

It finds the minimum value of a specific column and returns one or many values
Example:

Parameters:

• $colName the name of the column to find a value (mixed)
• $returnType =['first','last','random','all'][$i]
  
  • first returns the first min value
    
  • last returns the last min value
    
  • random if there are many min values, then it returns one randomly
    
  • all returns all the values that have the min value (string)
• $getKey (default is false) if it returns the keys(indexs). If false it returns the columns (bool)

  Method maxRow()

  It finds the minimum value of a specific column and returns one or many values
  Example:

Parameters:

• $colName the name of the column to find a value (mixed)
• $returnType =['first','last','random','all'][$i]
  
  • first returns the first min value
    
  • last returns the last min value
    
  • random if there are many min values, then it returns one randomly
    
  • all returns all the values that have the min value (string)
• $getKey (default is false) if it returns the keys(indexs). If false it returns the columns (bool)

Method modCol()

It adds or modify a column. Example:

Parameters:

• $colName the name of the column. If null, then it uses the entire row (string|int|null)
• $operation the operation to realize. (callable|null)

  Method nPos()

  It returns the n-position of an array.

  Parameters:

• $index param $index ()

  Method offsetExists()

Method offsetGet()

It gets a value of the array
Example:

Parameters:

• $offset (if null, then it used the entire array) (mixed|null)

  Method offsetSet()

  It sets the value of the array.
  Example:

Parameters:

• $offset (if null, then it used the entire array) (mixed|null)
• $value the value to set (mixed)

  Method offsetUnset()

  It deletes a row of the array.
  Example:

Parameters:

• $offset (if null, then it used the entire array) (mixed|null)

  Method reduce()

  You can reduce (flat) an array using aggregations or a custom function. Example:

Parameters:

• $functionAggregation An associative array where the index is the column and the value is the function of aggregation
  A function using the syntax: function ($row,$index,$prev) where $prev is the accumulator value (array|callable)

  Method removeCol()

  It removes a column or columns
  Example:

Parameters:

• $colName The name of the column or columns (array) (mixed)

  Method removeDuplicate()

  This function removes duplicates of a table.
  Example:

Parameters:

• $colName the column (or columns) to use to remove duplicates. (array|string)

  Method removeFirstRow()

  It removes the first row or rows. Numeric index could be renumbered. Example:

Parameters:

• $numberOfRows The number of rows to delete, the default is 1 (the first row) (int)
• $renumber if true then it renumber the list
  ex: if 1 is deleted then $renumber=true: [0=>0,1=>1,'x'=>2] => [0=>0,1=>2]
  ex: if 1 is deleted then $renumber=false: [0=>0,1=>1,2=>2] => [0=>0,2=>2]
  (bool)

  Method removeLastRow()

  It removes the last row or rows Example:

Parameters:

• $numberOfRows the number of rows to delete (int)
• $renumber if true then it renumber the list (since we are deleting the last value then usually we don't need it
  ex: if 1 is deleted then $renumber=true: [0=>0,1=>1,2=>2] => [0=>0,1=>2]
  ex: if 1 is deleted then $renumber=false: [0=>0,1=>1,2=>2] => [0=>0,2=>2]
  (bool)

  Method removeRow()

  It removes the row with the id $rowId. If the row does not exist, then it does nothing Example:

Parameters:

• $rowId The id of the row to delete (mixed)
• $renumber if true then it renumber the list
  ex: if 1 is deleted then $renumber=true: [0=>0,1=>1,2=>2] => [0=>0,1=>2]
  ex: if 1 is deleted then $renumber=false: [0=>0,1=>1,2=>2] => [0=>0,2=>2]
  (bool)

  Method rowToValue()

  It transforms a row of values into a single value. If a row does not contain a column then it returns null Example:

Parameters:

• $colName The name of the column (mixed)
• $nullWhenNotFound if true then it returns null when the column is not found in a row
  otherwise, it skips the column (bool)

  Method shuffle()

Method sort()

Sort an array using a column or columns
Example:

Parameters:

• $column The column or columns to sort.
  If column is null, then it sorts the row (instead of a column of the row) (mixed)
• $direction =['asc','desc'][$i] ascending or descending.
  By default is ascending. (mixed)

  Method splitColumn()

  It split a column in two or more columns using a separator

  Parameters:

• $colName The column to split (string)
• $newCols The name of the new columns (array)
• $separator If null, then it uses the default separator ($this->separator) (string|null)

  Method sum()

  Returns the sum value of a specific column
  Example:

Parameters:

• $colName the column (mixed)

  Method validate()

  Validate the current array using a comparison table
  It returns an associative array with null in the fields without error, or other value if error. Example:

Parameters:

• $comparisonTable see table (array)
• $extraFieldError if true and the current array has more values than comparison table, then it returns an error. (bool)

versions

• 2.6.1 2024-09-28
  • [fixed]
  • In 2.6 and lower, many functions detected when the array is null to avoid to do the operation.
  • In 2.6.1, many functions detects when the array is empty (including null) to avoid to do the operation.
• 2.6 2024-09-26
  • [new] minRow()
  • [new] maxRow()
• 2.5.1 2024-09-20
  • [new] keepCol()
  • [new] coolRename()
  • [new] shuffle()
  • [new] updated this file to contain all the definitions.
• 2.4 2024-08-15
  • [update] sort() now allow to group by multiples columns
  • [fixed] group() fixed the value returned. If multiples columns are used then, the new grouping column could be split.
  • [new] splitColumn() split a column in two or more columns.~~
• 2.3 2024-08-10
  • [new] sum(),min(),max(),avg(),count(),aggr()
• 2.2 2024-08-06
  • sort() now accepts multiple columns.
• 2.1 2024-08-03
  • removeDuplicate(),group() now accepts multiples columns.

• 2.00 2024-03-10

  • nav() and currentArray() are removed from 2.0. The library was optimized and streamlined, and those functions are redundant.
    migration:
• 1.12 2024-03-01
  • Updating dependency to PHP 7.4. The extended support of PHP 7.2 ended 3 years ago.
• 1.11 2024-03-01
  • added method find()
  • aedded method isIndexArray() and isIndexTableArray()
  • now find() and filter() allows multiple conditions
  • and find() and filter(), the condition ['field'='eq;2'] could be written as ['field','2']
• 1.10 2024-02-24
  • Added more doc for validate()
  • Now validate also returns an array $this::$errorStack
  • New method isValid() which returns true is validate has no error. Otherwise false.
• 1.9 2023-11-13
  • added rowToValue()
• 1.8.3 2023-09-16
  • offsetGet() generates a warning in php 8.1 (fixed)
  • current() is marked as deprecated (but it is still functional), use getCurrent()
• 1.8.2 2023-09-16
  • solved a psr-4 problem in composer.json
• 1.8.1 2023-09-16
  • change the PHPDOC comments, now it uses markdown instead of "pre" tag.
  • Added ArrayAccess interface.
• 1.8 2023-07-29
  • [mod] group() allows to specify a custom function(s).
• 1.7 2023-06-04
  • [new] group() allows returning the grouped value. It also allows returning the values as an indexed array.
• 1.6 2023-04-10
  • [optimization] setCurrentArray() now is only used when nav() is called or when the value is returned.
• 1.5 2023-04-07
  • [new] filtercondition() now allow conditions as array.
• 1.4 2023-04-05
  • [fix] filtercondition() fixed a warning when the value is null.
  • [new] group() now allow to stack elements
  • [new] group() now allow to specify a new column
• 1.3 2023-03-31
  • validation now allow negation ("not" prefix).
• 1.2
  • renamed method getValidateArrayByExample() to makeValidateArrayByExample()
  • new method makeRequestArrayByExample()
  • new method setRequest()
  • rename method setCol() to modCol(). Methods that start with "set" are used to initialize the variable.
• 1.1 2023-03-28
  • method filter() now allow a comparison array and a callable function.
  • new method getValidateArrayByExample()
  • new method removeRow()
  • new method removeFirstRow()
  • new mehtod removeLastRow()
  • new method setCsv()
  • new method setJson()
• 1.0 2023-03-26 first version

License

Copyright Jorge Castro Castillo 2023-2024. Licensed under dual license: LGPL-3.0 and commercial license.

In short:

• [x] Can I use in a close source application for free? Yes if you don't modify this library.
• [x] If you modify it, then you must share the source code.
• [x] If you want to modify privately, then you must buy a license.