Skip to content

Commit

Permalink
Updated Readme file with installation instructions & packagist badges.
Browse files Browse the repository at this point in the history
  • Loading branch information
oliverde8 committed Feb 17, 2017
1 parent 860e5fa commit 7d55317
Showing 1 changed file with 112 additions and 30 deletions.
142 changes: 112 additions & 30 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,12 @@

This library allow simplified manipulation of recursive associative arrays with an object oriented aproach in php.

[![Latest Stable Version](https://poser.pugx.org/oliverde8/associative-array-simplified/v/stable)](https://packagist.org/packages/oliverde8/associative-array-simplified)
[![Build Status](https://travis-ci.org/oliverde8/AssociativeArraySimplified.svg?branch=master)](https://travis-ci.org/oliverde8/AssociativeArraySimplified)
[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/oliverde8/AssociativeArraySimplified/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/oliverde8/AssociativeArraySimplified/?branch=master)
[![Code Coverage](https://scrutinizer-ci.com/g/oliverde8/AssociativeArraySimplified/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/oliverde8/AssociativeArraySimplified/?branch=master)
[![Total Downloads](https://poser.pugx.org/oliverde8/associative-array-simplified/downloads)](https://packagist.org/packages/oliverde8/associative-array-simplified)
[![License](https://poser.pugx.org/oliverde8/associative-array-simplified/license)](https://packagist.org/packages/oliverde8/associative-array-simplified)

[![SensioLabsInsight](https://insight.sensiolabs.com/projects/fc4c6968-5c27-49ee-9cda-4d648aa650f9/big.png)](https://insight.sensiolabs.com/projects/fc4c6968-5c27-49ee-9cda-4d648aa650f9)

Expand All @@ -14,68 +17,120 @@ This is the main clas of the library. It allows the manipulation of the associat

This allow you to get data from an associative array with ease. This can be used many places even for getting information from SESSION or POST & GET values.

### Exemple
Typically when we try and get information from a an array of which we don't know the content we need to write a lot of conditions :

To get a value from a simple array.
```php
$array = ['a' => ['b' => 2, 'c' => 3]];
if (isset($array['a'])) {
$valB = isset($array['a']['b']) ? $array['a']['b'] : "default";
$valB = isset($array['a']['c']) ? $array['a']['c'] : "default";
}
```

After a certain while we write a lot conditions and the array is very nested it becomes difficult to understand.
This library makes it much easier to write code of this type & makes it easier to read and understand.
The code above is simply replaced by :

```php
$object = new AssociativeArray( ['a' => ['b' => 2, 'c' => 3]]);
$valB = $object->get('a/b', 'default');
$valB = $object->get('a/c', 'default');
```

## Requirments
* `PHP` 5.4 or higher.

## Installation

You should always install the library using composer.

```bash
composer require oliverde8/associative-array-simplified
```

**Manual installation is not recomended and not supported.**

## Usage Exemples

### Get values from a simple array

```php
$array = ['a' => 1, 'b' => 2,];
$object = new AssociativeArray($array);

$this->get('a');
$object->get('a');
//This will return '1'

$this->get('c');
$object->get('c');
//This will return null
```

What really helps is you can actually set a default value to get.
### Get a value and if no value is set get a default one

```php
$this->get('c', 10);
$object->get('c', 10);
//This will return 10
```

But most importantly it's recursive.
### Get nested values recursively

```php
$array = ['a' => ['b' => 2]];
$object = new AssociativeArray($array);

$this->get('a');
$object->get('a');
//This will return ['b' => 2]

$this->get(['a', 'b']);
$object->get(['a', 'b']);
//This will return 2
```

> And of course you can continue to use default values with the recursive get.
You can also use separators to use simple strings in the get :
### Use separators in the string keys to get nested values

The default separator is `/`

```php
$this->get('a/b');
$object->get('a/b');
//This will return 2
```

Of course you can simply edit the content of the array :
### You can set new values or replace them.

```php
// Both of these do the same thing.
$this->set('a/d', 10);
$this->set(['a','d'], 10);
$object->set('a/d', 10);
$object->set(['a','d'], 10);
```

And finally you can get back your array :
### You can get back your array

```php
// And you get back the array.
$this->array()
$object->array()
```

## Exemple static methods
### Using custom separators

When creating the AssociativeArray you can specify the separator to use. So instead of
```php
$array = ['a' => ['b' => 2]];
$object = new AssociativeArray($array);
$this->get('a/b');
```

The class has also static methods to manipulate your array directly.
You can write

```php
$array = ['a' => ['b' => 2]];
$object = new AssociativeArray($array, '.');
$this->get('a.b');
```

### Example usage of static methods

The class has also static methods to manipulate your array directly. The method of the objects actually uses these static methods to manipulate the array.

```php
$array = ['a' => ['b' => 2]];
Expand All @@ -90,25 +145,52 @@ AssociativeArray::setFromKey($array, 'a/c', 'yop);
// Will return ['a' => ['b' => 2, 'c' => 'yop']]
```

## More Exemples.
## Other functions

The class has also other functions.

* **clear :** Empties all the data from the array.
* **keyExist :** Checks if a key exists. (value may be null)

## FAQ

### Why don't the associative array has an iterator ?

Associative Array Simplified doesen't try and replace arrays; other libraries were designed to do so.
This library simply makes it easier yo access values in associative arrays.

### Why don't the associative array return associative array instead of normal array's ?

This is something I spent quite some time to decide, but doing it that way would require during the creation of the associative array to process the array to create the nested associative arrays.
This would have slowned then the process of creation without really increasing perormance at any other level. On long term I might create a second object working that way.

There is some questions about this how should this work :

When creating the AssociativeArray you can specify the separator to use. So instead of
```php
$array = ['a' => ['b' => 2]];
$object = new AssociativeArray($array);
$this->get('a/b');
```

You can write
$object->get('a');
//This will return ['b' => 2]

```php
$array = ['a' => ['b' => 2]];
$object = new AssociativeArray($array, '.');
$this->get('a.b');
$object->get(a)->get('b');
//Should return 2

$object->get(a)->get('b')->get('c', 'default');
//Will make an error but should have returned 'default'
```

# TODO
* Check composer & Add to packagist. Yop all is ready for take off
So there is some reflexion to be done on the subject.

### Why don't the assotiative array use references ?

It's planned. Current implementation is slower as it duplicated the arrays during the set operations.

### ...

## TODO

* Add some more options (clear, disable new data ...)
* Add a second version using references to use less memory.
* uses references to use less memory.
* create second version returning Associative Array instead of normal arrays.
* Something else? Open a ticket :)

0 comments on commit 7d55317

Please sign in to comment.