{"id":19215545,"url":"https://github.com/alwaysblank/brief","last_synced_at":"2025-05-12T23:25:20.714Z","repository":{"id":56946512,"uuid":"168903381","full_name":"alwaysblank/brief","owner":"alwaysblank","description":"Present your arguments.","archived":false,"fork":false,"pushed_at":"2023-02-06T22:54:20.000Z","size":101,"stargazers_count":8,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-20T19:37:57.119Z","etag":null,"topics":["hacktoberfest"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alwaysblank.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-02-03T02:59:16.000Z","updated_at":"2022-10-28T15:49:17.000Z","dependencies_parsed_at":"2023-02-16T12:46:02.816Z","dependency_job_id":null,"html_url":"https://github.com/alwaysblank/brief","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alwaysblank%2Fbrief","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alwaysblank%2Fbrief/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alwaysblank%2Fbrief/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alwaysblank%2Fbrief/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alwaysblank","download_url":"https://codeload.github.com/alwaysblank/brief/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253745198,"owners_count":21957319,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest"],"created_at":"2024-11-09T14:14:01.732Z","updated_at":"2025-05-12T23:25:20.669Z","avatar_url":"https://github.com/alwaysblank.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"= Brief 📂\n:Date: 12/15/2019\n:Revision: 2.0.0-alpha\n:Author: Ben Martinez-Bateman\n:Email: ben@alwaysblank.org\n:toc: macro\n:toclevels: 6\n:toc-title:\nifdef::env-github[]\n:tip-caption: :bulb:\n:note-caption: :information_source:\n:important-caption: :heavy_exclamation_mark:\n:caution-caption: :fire:\n:warning-caption: :warning:\nendif::[]\nifndef::env-github[]\n:tip-caption: 💡\n:note-caption: ℹ\n:important-caption: ❗\n:caution-caption: 🔥\n:warning-caption: ⚠\nendif::[]\n\n**Present your arguments.**\n\nimage:https://travis-ci.org/alwaysblank/brief.svg?branch=master[\"Build Status\", link=\"https://travis-ci.org/alwaysblank/brief\"]\n\ntoc::[]\n\n== What Is This?\n\nIt's a simple tool for passing around collections of variable structured data.\n\n90% 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_.\nIt grew from there to provide some other functionality related to moving collections of structure data around.\nI find it particularly useful when templating with https://laravel.com/docs/5.8/blade[Laravel Blade].\n\n(Brief is only one way to solve the issues I might use here as examples:\nIt's not intended to be an authoritative or \"best\" solution, merely a convenient one, if you find it convenient.)\n\n== How Does It Work?\n\n[source,php]\n----\n$Brief = Brief::make([\n    'key' =\u003e 'value',\n]);\n\n$Brief-\u003ekey;\n// 'value'\n\n$Brief-\u003edoesnt_exist;\n// null\n----\n\nInstead of throwing an error or exception, Brief will return `null` if a key does not have an associated value.\n\n[NOTE]\n====\nYou can also create a Brief with `new`, `make()` is just slightly more concise:\n[source,php]\n----\n$Brief = new Brief([\n    'key' =\u003e 'value',\n]);\n----\n====\n\n=== Arguments\n\nA new Brief, whether created with `new Brief()` or `Brief::make()`, takes two arguments:\n\n`$items`:: The values to be stored, usually as an array.\n`$settings`:: Some settings for things like callables, aliases, etc.\n\nBoth 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.\n\nThese arguments are treated the same whichever method of instantiation you use, with one major difference.\nWhile `$items` will accept an existing Brief through either method, the behavior will be different:\n\n`Brief::make($Brief)`:: This will return *the exact same Brief* that you passed to it.\n`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*.\n\nIn 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.\nMy recommendation is to simply pick an instantiation method and use that for an entire project, to minimize possible confusion.\n\n== Features\n\n=== Storing Data\n\nThis is the primary feature of Brief.\n\nBrief expects data in an array, but whether that array is keyed or numeric is up to you.\n(Or, use a language where arrays aren't as confusing.)\n\n[source,php]\n----\n$keyed = Brief::make([\n    'key' =\u003e 'value1',\n    'key2' =\u003e 'value2',\n]);\n\n$numeric = Brief::make([\n    'number1',\n    'number2',\n]);\n----\n\n\n=== Aliasing\n\nYou may find yourself in a situation where you want to have multiple keys that point to the same data.\nWith aliases, you can accomplish this easily:\n\n[source,php]\n----\n$brief = Brief::make([\n    'a_rose' =\u003e 'sweet smell',\n], [\n    'aliases' =\u003e [\n        'a_rose' =\u003e 'any_other_name',\n    ]\n]);\n\n$brief-\u003ea_rose;\n// \"sweet smell\"\n\n$brief-\u003eany_other_name;\n// \"sweet smell\"\n----\n\nAliases are passed through the \"settings\" array (the optional second argument to a new Brief).\nUse the key `aliases` or `alias` to set any aliases you would like.\n\nYou can define multiple aliases for a single key at once by passing an array of strings instead of a single string:\n\n[source,php]\n----\n$brief = Brief::make([\n    'original_key' =\u003e 'value',\n], [\n    'aliases' =\u003e [\n        // \"Array\" style\n        'original_key' =\u003e ['another_key', 'another_another_key'],\n        // \"String\" style\n        'original_key' =\u003e 'yet_another_key',\n    ]\n]);\n\n$brief-\u003eoriginal_key === $brief-\u003eanother_key === $brief-\u003eanother_another_key === $brief-\u003eyet_another_key;\n// true\n----\n\nAliases can also be chained to one another, if that's something you feel like doing.\nBrief 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.\n\n[source,php]\n----\n$brief = Brief::make([\n    'a_rose' =\u003e 'sweet smell',\n], [\n    'aliases' =\u003e [\n        'a_rose' =\u003e ['any_other_name'],\n        'any_other_name' =\u003e ['montague'],\n    ]\n]);\n\n$brief-\u003ea_rose === $brief-\u003emontague;\n// true\n----\n\n=== Custom Empty Test\n\nBrief comes with `isEmpty()` and `isNotEmpty()` which somewhat naively test if the Brief is empty\n(they examine only whether top-level items in the array are not equal to `null`).\nIf your use case requires a more robust test, you can pass that test to the `isEmpty` parameter at instantiation.\nIt accepts anything PHP considers callable.\n\n[source,php]\n----\n$brief = Brief::make([\n    ['key' =\u003e 'value'],\n    ['isEmpty' =\u003e function($brief) {\n        // some logic\n    }]\n);\n\n$brief-\u003eisEmpty(); // false (hopefully)\n----\n\n=== Logging\n\nSince 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.\nIf it's recoverable, it will simply recover and move on, with your data likely lost.\nIn 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.\n\nIn some situations, though, you don't want this--you want to know what's happened.\nFortunately, Brief includes a very simple logging feature.\nTo use it, just do the following:\n\n[source,php]\n----\n$brief = Brief::make(\n    ['key' =\u003e 'value'],\n    ['logger' =\u003e function($name, $description, $clone, $data) {\n        // Do something with this data\n    }]\n);\n----\n\nIn 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.\nIf 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.\n\nIf, for some reason, you need to manually log something to a Brief, you can do so:\n\n[source,php]\n----\n$brief = Brief::make(\n    ['key' =\u003e 'value'],\n    ['logger' =\u003e function($name, $description, $clone, $data) {\n        // Do something with this data\n    }]\n);\n\n$brief-\u003elog('ExampleError', 'This is to prove a point', ['a_key' =\u003e 'some_value']);\n----\n\nIt will be sent to whatever logger you have defined (or, if you haven't defined one, nothing will happen).\nThis is exactly the same mechanism Brief uses to log errors internally.\n\n[WARNING]\n====\nThis method is only fired on problems Brief is equipped to understand and expect;\nit will not, for instance, catch an exception you throw during `transform()`.\n====\n\n[NOTE]\n====\nIf you used v1 of Brief, then these logger calls happen in the same places where Brief used to throw Exceptions, and replace that functionality;\nBrief will not longer throw Exceptions of its own volition.\n====\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falwaysblank%2Fbrief","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falwaysblank%2Fbrief","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falwaysblank%2Fbrief/lists"}