README

Present your arguments.

What Is This?
How Does It Work?
- Arguments
Features

What Is This?

It’s a simple tool for passing around collections of variable structured data.

90% of the reason I built it was because I got very tired of writing isset(), etc, conditionals when the nonexistence of a key was equivalent to a falsey value in terms of program flow. It grew from there to provide some other functionality related to moving collections of structure data around. I find it particularly useful when templating with Laravel Blade.

(Brief is only one way to solve the issues I might use here as examples: It’s not intended to be an authoritative or "best" solution, merely a convenient one, if you find it convenient.)

How Does It Work?

$Brief = Brief::make([
    'key' => 'value',
]);

$Brief->key;
// 'value'

$Brief->doesnt_exist;
// null

Instead of throwing an error or exception, Brief will return null if a key does not have an associated value.

ℹ️	You can also create a Brief with `new`, `make()` is just slightly more concise: $Brief = new Brief([ 'key' => 'value', ]);

Arguments

A new Brief, whether created with new Brief() or Brief::make(), takes two arguments:

$items: The values to be stored, usually as an array.
$settings: Some settings for things like callables, aliases, etc.

Both arguments are optional, although if you wish to create an empty Brief it is recommended to use new EmptyBrief() or Brief::empty() to make your code clearer.

These arguments are treated the same whichever method of instantiation you use, with one major difference. While $items will accept an existing Brief through either method, the behavior will be different:

Brief::make($Brief): This will return the exact same Brief that you passed to it.
new Brief($Brief): This will attempt to ingest all of the data and settings stored on the passed Brief and apply them to a new instance of Brief.

In many situations the distinction will be academic—you can still get at your data whichever one you use—but the distinction should be kept in mind, especially if you feel you might be using strict comparison on Briefs. My recommendation is to simply pick an instantiation method and use that for an entire project, to minimize possible confusion.

Features

Storing Data

This is the primary feature of Brief.

Brief expects data in an array, but whether that array is keyed or numeric is up to you. (Or, use a language where arrays aren’t as confusing.)

$keyed = Brief::make([
    'key' => 'value1',
    'key2' => 'value2',
]);

$numeric = Brief::make([
    'number1',
    'number2',
]);

Aliasing

You may find yourself in a situation where you want to have multiple keys that point to the same data. With aliases, you can accomplish this easily:

$brief = Brief::make([
    'a_rose' => 'sweet smell',
], [
    'aliases' => [
        'a_rose' => 'any_other_name',
    ]
]);

$brief->a_rose;
// "sweet smell"

$brief->any_other_name;
// "sweet smell"

Aliases are passed through the "settings" array (the optional second argument to a new Brief). Use the key aliases or alias to set any aliases you would like.

You can define multiple aliases for a single key at once by passing an array of strings instead of a single string:

$brief = Brief::make([
    'original_key' => 'value',
], [
    'aliases' => [
        // "Array" style
        'original_key' => ['another_key', 'another_another_key'],
        // "String" style
        'original_key' => 'yet_another_key',
    ]
]);

$brief->original_key === $brief->another_key === $brief->another_another_key === $brief->yet_another_key;
// true

Aliases can also be chained to one another, if that’s something you feel like doing. Brief will make a relatively naive attempt to not get sucked into infinite alias loops, and will simply stop trying to resolve an alias chain if it detects such a loop.

$brief = Brief::make([
    'a_rose' => 'sweet smell',
], [
    'aliases' => [
        'a_rose' => ['any_other_name'],
        'any_other_name' => ['montague'],
    ]
]);

$brief->a_rose === $brief->montague;
// true

Custom Empty Test

Brief comes with isEmpty() and isNotEmpty() which somewhat naively test if the Brief is empty (they examine only whether top-level items in the array are not equal to null). If your use case requires a more robust test, you can pass that test to the isEmpty parameter at instantiation. It accepts anything PHP considers callable.

$brief = Brief::make([
    ['key' => 'value'],
    ['isEmpty' => function($brief) {
        // some logic
    }]
);

$brief->isEmpty(); // false (hopefully)

Logging

Since the basic concept for Brief is about how either your data exists or doesn’t, Brief will not complain loudly if you do something it doesn’t like. If it’s recoverable, it will simply recover and move on, with your data likely lost. In most cases, this should be fine; Your logic will have something to do if Brief gives you null for a piece of data you thought you’d added.

In some situations, though, you don’t want this—you want to know what’s happened. Fortunately, Brief includes a very simple logging feature. To use it, just do the following:

$brief = Brief::make(
    ['key' => 'value'],
    ['logger' => function($name, $description, $clone, $data) {
        // Do something with this data
    }]
);

In this example, whenever Brief encounters errors that it has some understanding of, an error message will be passed to the callable you’ve defined here. If instead of a callable you pass boolean true to the logger setting, then it will just dispatch an canned message to PHP’s error_log() and your system will handle that however it’s configured to.

If, for some reason, you need to manually log something to a Brief, you can do so:

$brief = Brief::make(
    ['key' => 'value'],
    ['logger' => function($name, $description, $clone, $data) {
        // Do something with this data
    }]
);

$brief->log('ExampleError', 'This is to prove a point', ['a_key' => 'some_value']);

It will be sent to whatever logger you have defined (or, if you haven’t defined one, nothing will happen). This is exactly the same mechanism Brief uses to log errors internally.

⚠️	This method is only fired on problems Brief is equipped to understand and expect; it will not, for instance, catch an exception you throw during `transform()`.

ℹ️	If you used v1 of Brief, then these logger calls happen in the same places where Brief used to throw Exceptions, and replace that functionality; Brief will not longer throw Exceptions of its own volition.

alwaysblank / brief

Maintainers

Details