PHPackages                             collab-corp/formatter - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Validation & Sanitization](/categories/validation)
4. /
5. collab-corp/formatter

AbandonedArchivedLibrary[Validation & Sanitization](/categories/validation)

collab-corp/formatter
=====================

Formatting utility package for php

v4.0.2(4y ago)343851MITPHPPHP ^8.0

Since Apr 16Pushed 3y ago1 watchersCompare

[ Source](https://github.com/collab-corp/formatter)[ Packagist](https://packagist.org/packages/collab-corp/formatter)[ RSS](/packages/collab-corp-formatter/feed)WikiDiscussions master Synced 2d ago

READMEChangelogDependencies (4)Versions (25)Used By (0)

Input Formatter
===============

[](#input-formatter)

[![Tests](https://github.com/collab-corp/formatter/actions/workflows/tests.yml/badge.svg)](https://github.com/collab-corp/formatter/actions/workflows/tests.yml/badge.svg)

[![StyleCI](https://camo.githubusercontent.com/16d478865de41e6f566e7b13b919d04e348d50599c66ed362cdc0e18d3c951d2/68747470733a2f2f7374796c6563692e696f2f7265706f732f3131393839373239382f736869656c643f6272616e63683d6d6173746572)](https://styleci.io/repos/119897298)

A php package for formatting data/values using a laravel validation like syntax, powered by `Illuminate\Support` components.

Installation
------------

[](#installation)

`composer require collab-corp/formatter`

Use
---

[](#use)

The most basic use is simple, just pass your value and array of callables that your value should be called against:

```
use CollabCorp\Formatter\Support\ValueFormatter;

$formatter = new ValueFormatter("   uncle bob   ", ['trim', 'ucwords']);

$formatter->apply()->get(); // returns "Uncle Bob"
```

### Passing Arguments To Callables

[](#passing-arguments-to-callables)

You can specify arguments using a `:` followed by a comma delimited list `e.g callable:arg1,arg2`:

```
function suffix_string($value, $suffix)
{
    return $value.$suffix;
}

$formatter = new ValueFormatter("  Foo  ", ['trim', 'suffix_string:Bar']);

$formatter->apply()->get(); // returns "FooBar"
```

**Note:** Notice that we only specified the `suffix` parameter. The `ValueFormatter` class automatically passes your value as the first parameter to every function with the exception of delegation to objects/instances (See Using Instances section below).

#### What if value isnt the first parameter to my function?

[](#what-if-value-isnt-the-first-parameter-to-my-function)

No problem, you can specify what order you want your value passed by using the `:value:` placeholder:

For example, `preg_replace` accepts a value to format as the third parameter:

```
// trim & replace all non numerics with "#"
$formatter = new ValueFormatter("   ABC123   ", [
    'trim',
    'preg_replace:/[^0-9]/,#,:value:'
]);

$formatter->apply()->get(); // returns "###123"
```

### Whitelisting Allowed Callables

[](#whitelisting-allowed-callables)

By default, all callables are allowed to be called, but if you are dynamically calling callables or want to add a protection layer, it may be worth specifying what callable functions should be allowed:

```
$formatter = new ValueFormatter("   uncle bob   ", ['trim', 'ucwords']);

$formatter->allowedCallables(["trim"]); //only trim is allowed

// throws  InvalidArgumentException:
// "Encountered non whitelisted function or non callable [ucwords]"
$formatter->apply()->get();
```

### Using Instances/Object Values & Method Chaining

[](#using-instancesobject-values--method-chaining)

It is possible to pass an object/instance to the formatter and utilize any methods on that instance. Using a `.` convention you can specify method chaining on that instance. For example take a [Carbon](https://carbon.nesbot.com/docs/) instance:

```
$formatter = new ValueFormatter(new Carbon\Carbon('2020-05-24'), [
    '.addDays:1',
    '.format:m/d/Y'
]);

$formatter->apply()->get() // returns "05/25/2020"
```

### Closures/Formattable Classes

[](#closuresformattable-classes)

You can use closures for formatting your value as well:

```
$formatter = new ValueFormatter("the value", [
    function($value){
        //do something to the value
        return $value;
    },
    ...
]);
```

Or you can also implement the `CollabCorp\Formatter\Support\Contracts\Formattable` contract and use instances:

```
use CollabCorp\Formatter\Support\Contracts\Formattable;
use Closure;

class FormatValue implements Formattable
{
    /**
     * Format the value.
     *
     * @param  mixed $value
     * @param  Closure $exit
     * @return mixed
     */
    public function format($value, Closure $exit)
    {
        // quit formatting value(s)
        if($someCondition){
            $exit();
        }

        // or change the $value
        $value = "Changed"

        return $value;
    }
}

$formatter = new ValueFormatter("The value", [
    "trim"
    new FormatValue
    // or using class constant:
     FormatValue::class // formatter will new up the class.
]);
```

### Optional Formatting/Blank Input

[](#optional-formattingblank-input)

Sometimes you may only want to format a value if the value isnt `null` or "blank": You can specify `?` anywhere in the chain of callables to specify if the formatter should break out of processing callables, often this should be defined in front of all your callables:

```
$formatter = new ValueFormatter(null, [
    "?", //tells the class not to process callables if value is blank
    'to_carbon',
    '.addDays:1',
    '.format:m/d/Y'
]);

$formatter->apply()->get(); // returns original null value
```

**Note:** This packages uses Laravel's [blank](https://laravel.com/docs/8.x/helpers#method-blank) helper to determine blank/empty values. If you have more complicated logic to break out of rules, use a closure or a `Formattable` class and call the 2nd argument `exit` callback:

```
$formatter = new ValueFormatter(null, [
    function($value, $exit){
        if($quitProcessing){
            $exit(); // tells formatter to quit processing.
        }
    },
    'to_carbon',
    '.addDays:1',
    '.format:m/d/Y'
]);
```

### Formatting multiple values

[](#formatting-multiple-values)

So far all the examples have been using a single value, but often times we are working with much more data from client requests. This is where the `DataFormatter` class is preferred:

```
use CollabCorp\Formatter\DataFormatter;

$data = [
  'first_name'=>'    jim    ',
  'last_name'=>'   thompson',
  'phone_number'=>'123-456-7890',
  'date_of_birth'=>"1991-05-01",
  ...
];

$callables = [
    'first_name'=>'trim|ucfirst',
    'last_name'=>'trim|ucfirst',
    'phone_number'=>'preg_replace:/[^0-9]/,,:value:',
    'date_of_birth'=>'?|to_carbon|.format:m/d/y',
    ...
];

$formatter = new DataFormatter($data, $callables);

$formatter->apply()->get(); //returns formatted data
```

### Array Input

[](#array-input)

You may also format array data using dot notation:

```
$data = [
  'contact_info'=>[
    'first_name'=>'    jim    ',
    'last_name'=>'   thompson',
    'phone_number'=>'123-456-7890',
    'address'=>'123 some lane.'
  ]
];

$callables = [
    'contact_info.first_name'=>'trim|ucwords',
    'contact_info.last_name'=>'trim|ucwords',
    'contact_info.phone_number'=>'preg_replace:/[^0-9]/,,:value:',
    'contact_info.address'=>[function ($address) {
      return 'Address Is: '.$address;
    }],
];
$formatter = new DataFormatter($data, $callables);

$formatter->apply()->get();
```

### Wildcard Formatting

[](#wildcard-formatting)

Callables can contain wildcards as well:

```
$data = [
    'first_name'=>'    jim    ',
    'last_name'=>'   thompson',
    ...
];
$callables = [
    //apply to all keys that contain "name"
    '*name*'=>'trim|ucwords',
];

$formatter = new DataFormatter($data, $callables);

$formatter->apply()->get();
```

This includes array input:

```
$callables = [
    'contact_info.*name*'=>'trim|ucwords',
    // 'contact_info.*name'=>'trim|ucwords',
    // 'contact_info.name*'=>'trim|ucwords',
];

$formatter = new DataFormatter($data, $callables);

$formatter->apply()->get();
```

### Concerns

[](#concerns)

If you prefer using a trait to easily create formatter instances, we provide the `CollabCorp\Formatter\Support\Concerns\FormatsData` trait for easy access:

```