<commit_before>Grabbag is a PHP library that aims provide a simple secure way to request PHP objects chains using path like expressions.

# Features :
* Compact path like syntax using uniform syntax for getter, method or property
* Prevent exception while accessing objects chains and provide a default value when a path cannot be resolved
* Multiple value result using #each
* Structured result using path array

# A first example

Lets take an example from Drupal 8 : Getting the image URL from a node using entity reference field pointing to a media entity would give someting like this :

## Using raw PHP
```php
$node->get('field_media_image')->first()->get('entity')->getTarget()->getValue()->get('field_image')->entity->getFileUri()
```

## Using Grabbag
```php
$grabber = new Grabbag($node);
$result = $grabber->grab('get("field_media_image")/first/get("entity")/target/value/get("field_image")/entity/fileUri');
echo $result->getValue();
```

## Comparition : 
* Raw PHP expression is not implicitly secure : Some of the methods/properties along the expression can return or be NULL in some case and then cause an exception. If you really want to secure expression, you would test some of the values before accessing them.
* Grabbag expression is implicitly secure. If it's not possible to walk along the object chain, grab method will return NULL or a default value to be specified.

# Multiple value result using #each

Path can collect more than one simple value using #each keyword.
Let's consider the following example that looks like the previous one except for the #each
```php
$grabber = new Grabbag($node);
$result = $grabber->grab('get("field_media_image")/#each/get("entity")/target/value/get("field_image")/entity/fileUri');
var_dump($result->getValue());
```
if the value corresponding to #each in the path can be iterated (if it's an array or an object implementing [Iterator interface](http://php.net/manual/en/class.iterator.php) for instance), #each will resolve the path considering each one of these values.

For instance if 
```php
$node->get('field_media_image') 
```
contains 4 items, then the result value will be an array looking like this : 
```php
["my/image/1.jpg", "my/image/2.jpg", "my/image/3.jpg", "my/image/4.jpg"]
```
# Structured result using path array
Path arrays allow to go a step further.
A path array is an array gathering paths in order to produce structured arrays.
Lets take an example : 

```php
$grabber = new Grabbag($node);
$result = $grabber->grab([
    'content-title:get("title").value',
    'images:get("field_media_image")/#each/get("entity")/target/value/get("field_image")' => [
        'uri:entity/fileUri',
        'alt:alt'
    ]
 ]);
var_dump($result->getValue());
```
will produce a structured array such as : 
```php
[
    'content-title' => 'My node title', 
    'images' => [
        [
            'uri' => "my/image/1.jpg"
            'alt' => "My image 1 alt"
        ],
        [
            'uri' => "my/image/2.jpg"
            'alt' => "My image 2 alt"
        ],
                [
            'uri' => "my/image/3.jpg"
            'alt' => "My image 3 alt"
        ],
    ]
]
```
# Field of use

Grabbag can be used in all PHP project using object intensively. This inclure project build on top of some of the most popular PHP framework or CMS such as Drupal 8, Symfony, Laravel and so on ...

It can be used everywhere you would have to get values from objects in order to extract values, array or structured array. for example: 
* Producing data for json Rest web-services.  
* Producing variables for twig templates.<commit_msg>Update README.md - Composer install + level title<commit_after># Grabbag - Grab object with ease for PHP

## Installation
```
$ composer require slavielle/grabbag
```

Grabbag is a PHP library that aims provide a simple secure way to request PHP objects chains using path like expressions.

## Features :
* Compact path like syntax using uniform syntax for getter, method or property
* Prevent exception while accessing objects chains and provide a default value when a path cannot be resolved
* Multiple value result using #each
* Structured result using path array

## A first example

Lets take an example from Drupal 8 : Getting the image URL from a node using entity reference field pointing to a media entity would give someting like this :

### Using raw PHP
```php
$node->get('field_media_image')->first()->get('entity')->getTarget()->getValue()->get('field_image')->entity->getFileUri()
```

### Using Grabbag
```php
$grabber = new Grabbag($node);
$result = $grabber->grab('get("field_media_image")/first/get("entity")/target/value/get("field_image")/entity/fileUri');
echo $result->getValue();
```

### Comparition : 
* Raw PHP expression is not implicitly secure : Some of the methods/properties along the expression can return or be NULL in some case and then cause an exception. If you really want to secure expression, you would test some of the values before accessing them.
* Grabbag expression is implicitly secure. If it's not possible to walk along the object chain, grab method will return NULL or a default value to be specified.

## Multiple value result using #each

Path can collect more than one simple value using #each keyword.
Let's consider the following example that looks like the previous one except for the #each
```php
$grabber = new Grabbag($node);
$result = $grabber->grab('get("field_media_image")/#each/get("entity")/target/value/get("field_image")/entity/fileUri');
var_dump($result->getValue());
```
if the value corresponding to #each in the path can be iterated (if it's an array or an object implementing [Iterator interface](http://php.net/manual/en/class.iterator.php) for instance), #each will resolve the path considering each one of these values.

For instance if 
```php
$node->get('field_media_image') 
```
contains 4 items, then the result value will be an array looking like this : 
```php
["my/image/1.jpg", "my/image/2.jpg", "my/image/3.jpg", "my/image/4.jpg"]
```
## Structured result using path array
Path arrays allow to go a step further.
A path array is an array gathering paths in order to produce structured arrays.
Lets take an example : 

```php
$grabber = new Grabbag($node);
$result = $grabber->grab([
    'content-title:get("title").value',
    'images:get("field_media_image")/#each/get("entity")/target/value/get("field_image")' => [
        'uri:entity/fileUri',
        'alt:alt'
    ]
 ]);
var_dump($result->getValue());
```
will produce a structured array such as : 
```php
[
    'content-title' => 'My node title', 
    'images' => [
        [
            'uri' => "my/image/1.jpg"
            'alt' => "My image 1 alt"
        ],
        [
            'uri' => "my/image/2.jpg"
            'alt' => "My image 2 alt"
        ],
                [
            'uri' => "my/image/3.jpg"
            'alt' => "My image 3 alt"
        ],
    ]
]
```
## Field of use

Grabbag can be used in all PHP project using object intensively. This inclure project build on top of some of the most popular PHP framework or CMS such as Drupal 8, Symfony, Laravel and so on ...

It can be used everywhere you would have to get values from objects in order to extract values, array or structured array. for example: 
* Producing data for json Rest web-services.  
* Producing variables for twig templates.
{'fraction_non_alphanumeric': 0.1155151350617619, 'fraction_numerical': 0.0035292520700420794, 'mean_word_length': 3.7443657437218287, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 51, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6752558', 'n_tokens_mistral': 2118, 'n_tokens_neox': 2053, 'n_words': 870}