Download the PHP package axetools/dot without Composer
On this page you can find all versions of the php package axetools/dot. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Informations about the package dot
axetools/dot
axetools/dot is a PHP library to access and set array values using dot notation or any other key separator.
Q: There are quite a few 'dot' projects that exist on Packagist, what is different about this one?
Every other 'dot' project requires you to create a copy of your data and instantiate a new class, this project uses light weight static methods to access and modify your existing arrays without the need to create a second copy of the data.
The other advantage that this has over many other implementations is that you can select an alternative key separator than a '.' which is necessary if you have key values that contain '.' characters in them.
Q: Why add this to Packagist?
This package has been used on several of my projects both personally and professionally, and I am tired of copying the class from one project to another. If my teams and I get usage out of this project, I wanted to share it to allow anyone else who this could help use it as well.
Warning: When you have xDebug enabled the recursion depth is set to 100, however the PHP manual advises against doing 100-200 recursion levels as it can smash the stack and cause termination of the current script. This class utilizes recursion to traverse the array. If you need to traverse an array with depth deeper than 100 levels this likely is the wrong tool to utilize.
Installation
The preferred method of installation is via Composer. Run the following command to install the package and add it as
a requirement to your project's composer.json
:
Usage
The Dot class contains static methods to facilitate the safe access, setting, unsetting and counting of array data in php.
Dot::has()
The Dot::has()
checks to see if there is a value in the search array for the search key. This method utilizes
recursion to traverse the array.
There is a globally available dotHas()
function, that wraps the Dot::has()
static method included in the autoloader.
Description
Parameters
- searchArray
- The array that will be searched for the provided key value
- searchKey
- The delimited key that will be searched for in the provided searchArray. If the array does not have string keys number strings can be used instead to access the appropriate position in the array
- delimiter
- The key delimiter can be specified, this is needed when there are '.' values contained within the expected array keys already
Return Values
The method returns true
if found and false
if not.
Examples
Example #1 simple key value lookup
Example #2 mixed key lookup
Dot::get()
The Dot::get()
method is for getting data from an array provided that there is a key that exists in the search
location, if there is not, then return a default value instead.
There is a globally available dotGet()
function, that wraps the Dot::get()
static method included in the autoloader.
Description
Parameters
- searchArray
- The array that will be searched for the provided key value
- searchKey
- The delimited key that will be searched for in the provided searchArray. If the array does not have string keys number strings can be used instead to access the appropriate position in the array
- default
- The default value to return if the searchKey is not found in the searchArray
- delimiter
- The key delimiter can be specified, this is needed when there are '.' values contained within the expected array keys already
Return Values
Returns from the method are the mixed value stored in the array at the searched key position or the default value provided.
Examples
Example #1 simple key value lookup
Example #2 mixed key lookup
Dot::set()
The Dot::set()
method will set the passed value inside the provided array at the location of the key provided.
The set method will create the key structure needed to place the value in the array if it is not present already.
There is a globally available dotSet()
function, that wraps the Dot::set()
static method included in the autoloader.
Description
Parameters
- setArray
- The array that will the value will be placed inside
- setKey
- The delimited key that will be searched for in the provided searchArray. If the array does not have string keys number strings can be used instead to access the appropriate position in the array
- value
- The default value to return if the searchKey is not found in the searchArray
- delimiter
- The key delimiter can be specified, this is needed when there are '.' values contained within the expected array keys already
Return Values
There is no return for this method, the array is passed by reference and is updated with the inserted value.
Examples
Example #1 simple key value lookup
Example #2 nested setting
Dot::increment()
The Dot::increment()
method will increment a value inside the provided array at the location of the key provided.
If the location already contains a numeric value it will be incremented by the increment amount. If the location is
not defined in the array the default will be uses as an initial value to be incremented by.
There is a globally available dotIncement()
function, that wraps the Dot::increment()
static method included in the
autoloader.
Description
Parameters
- incrementArray
- The array that will the value will be incremented inside the array in the position of the incrementKey.
- incrementKey
- The delimited key that will be searched for in the provided incrementArray. If the array does not have string keys number strings can be used instead to access the appropriate position in the array
- incrementor
- The amount to increment the value by. This can be positive or negative numeric values, either integers or floats.
- default
- The default value to return if the incrementKey is not found in the incrementArray
- delimiter
- The key delimiter can be specified, this is needed when there are '.' values contained within the expected array keys already
Return Value
The method returns an int|float
depending on the incrementor and (default or initial key value) from the incrmenetArray.
If the incrementor is an int
and the initial key value is an int
then the method's return will be an int
. If the
incrementor or (default or initial key value) are float
values then the method will return a float.
Examples
Example #1 looping over an uninitialized array
Dot::append()
The Dot::append()
method will set the passed value as an array value inside the provided array at the location of the
key provided. If the location already contains a value the values will be merged into a single array. The
append method will create the key structure needed to place the array value in the array if it is not present already.
There is a globally available dotAppend()
function, that wraps the Dot::append()
static method included in the
autoloader.
Description
Parameters
- appendArray
- The array that will the value will be placed inside the array in the position of the appendKey.
- appendKey
- The delimited key that will be searched for in the provided appendArray. If the array does not have string keys number strings can be used instead to access the appropriate position in the array
- value
- The value be set in the array. If the key location is not set already in the array the full path to the key location will be created and the value will be added to the key location in an array. If there is already a value in the key location the new value will be appended to the end of the array. If the value in the key location is not an array the location will be converted to an array and the new value will be appended to the end of the new array.
- delimiter
- The key delimiter can be specified, this is needed when there are '.' values contained within the expected array keys already
Return Values
There is no return for this method, the array is passed by reference and is updated with the inserted value.
Examples
Example #1 insert with an existing value
Example #2 setting the key and creating an initial array
Dot::delete()
The Dot::delete()
method will unset the key location provided. If the key location is not in the array there will be
no effect on the passed array.
There is a globally available dotDelete()
function, that wraps the Dot::delete()
static method included in the
autoloader.
Description
Parameters
- deleteArray
- The array that will the value will have a value unset from it, is in the deleteKey is in the array.
- deleteKey
- The delimited key that will be searched for in the provided deleteArray. If the array does not have string keys number strings can be used instead to access the appropriate position in the array
- delimiter
- The key delimiter can be specified, this is needed when there are '.' values contained within the expected array keys already
Return Values
There is no return for this method, the array is passed by reference and is updated.
Examples
Example #1 simple key value unset
Dot::count()
The Dot::count()
method will generate a count of the elements in the location of the key provided. If the value at the
location of the key provided is not an array (or there is no value at the provided key) by default the method will
return 0. This behavior can be changed to return a -1 instead when there is no value or a non array value.
There is a globally available dotCount()
function, that wraps the Dot::count()
static method included in the
autoloader.
Description
Parameters
- countArray
- The array that will the value will be placed inside
- countKey
- The delimited key that will be searched for in the provided searchArray. If the array does not have string keys number strings can be used instead to access the appropriate position in the array
- delimiter
- The key delimiter can be specified, this is needed when there are '.' values contained within the expected array keys already
- return
- By default the method will return 0 if the value at the key location either does not have a value set or if the value is not an array. This can be changed using the Dot::NEGATIVE_ON_NON_ARRAY constant instead return a -1 if there is not a value set or the value is not an array at the key location.
Return Values
The method returns an int
with the count of the array elements. If the value at the key location is not an array or
not set the method by default will return a 0, this can be changed to return a -1 by setting the return
parameter to Dot::NEGATIVE_ON_NON_ARRAY
.
Examples
Example #1 simple array count
Example #2 no element found and non array elements
Dot::flatten()
The Dot::flatten()
method will flatten a multidimensional array to a single dimensional array with the dotKeys =>
values as the returned new array. Each non-array value in the source array will have a cooresponding line in the output
array.
There is a globally available dotFlatten()
function, that wraps the Dot::flatten()
static method included in the
autoloader.
Description
Parameters
- array
- The source data array
- delimiter
- The key delimiter can be specified, this is needed when there are '.' values contained within the expected array keys already, the "flattened" keys will be delimited by this value.
- prepend
- Primarily used in the method's recursion, this can be used to prepend a string to the generated keys
Return Values
The method will return an array 1 dimension deep with array<dotKeys, mixed>
INFO: The
Dot::set()
method can be used over the resulting rows of the flattened array to reconstruct the original input array