The packages under the BrightComponents namespace are basically a way for me to avoid copy/pasting simple functionality that I like in all of my projects. There's nothing groundbreaking here, just a little extra functionality for form requests, controllers, custom rules, services, etc.
The package contains classes, interfaces, etc. that may be common among other BrightComponents packages.
You can install the package via composer:
composer require bright-components/commonLaravel versions > 5.6.0 will automatically identify and register the service provider. If you have this functionality disabled, add the package service provider to your config/app.php file, in the 'providers' array:
'providers' => [
//...
BrightComponents\Common\BrightComponentsServiceProvider::class,
//...
];Currently, the 'common' package simply provides a Payload class and a couple of ResponseFactory macros to help convert the Payload into either a json response or return a view with the payload data. The provided example below, uses the Payload from within a Controller class.
public function index(Request $request)
{
$users = \App\Models\User::get();
// As an alternative to "new Payload", you could resolve an instance via your controller's constructor.
$payload = (new Payload)->setOutput($users)
->setMessages(['success' => 'Operation successful!'])
->setStatus($payload::STATUS_OK);
return response()->jsonWithPayload($payload);
// return response()->viewWithPayload('dashboard', $payload, 'users');
}Messages and status are optional. You can use these values in the response you return, however you wish.
To optionally wrap the output with a key, pass the key (string) as the second argument to setOutput:
$payload->setOutput($users, 'data');If your payload includes 'messages', the output will automatically be wrapped with a key. If you do not provide a wrapping key, the key 'data' will be used.
As seen above, a couple of ResponseFactory macros are available to you, which makes sending payload responses, easier. For example:
$payload->setOutput($users, 'users')->setMessages(['success' => 'Operation Successful!']);
response()->jsonWithPayload($payload);will yield the following structure:
{
"users": [
{
"id": 1,
"name": "Clayton Stone",
"email": "clay@test.com",
"email_verified_at": "2019-03-18 20:29:26",
"created_at": "2019-03-18 20:29:26",
"updated_at": "2019-03-18 20:29:26"
},
{
"id": 2,
"name": "John Doe",
"email": "john15@gmail.com",
"email_verified_at": "2019-03-23 18:20:11",
"created_at": "2019-03-23 18:19:41",
"updated_at": "2019-03-23 18:20:16"
}
],
"messages": {
"success": "Operation successful!"
}
}
The other helper is viewWithPayload():
response()->viewWithPayload('dashboard', $payload, 'payload');The third argument is the string that you will use to refer to the data in your view. By default, 'payload' is used. Using the following:
$payload->setOutput($users, 'users')->setMessages(['success' => 'Operation Successful!']);
return response()->viewWithPayload('dashboard', $payload);You would access your data as follows:
<h1>{{ $payload->name }}</h1>
<span>{{ $payload->email }}</span>However, you can set the variable name in the following manner:
$payload->setOutput($users, 'users')->setMessages(['success' => 'Operation Successful!']);
return response()->viewWithPayload('dashboard', $payload, 'user');and access your data as follows:
<h1>{{ $user->name }}</h1>
<span>{{ $user->email }}</span>If you choose not to use the helper methods, refer to the PayloadContract below for the available methods on the Payload instance:
<?php
namespace BrightComponents\Common\Payloads\Contracts;
interface PayloadContract extends Status
{
/**
* Set the Payload status.
*
* @param string $status
*
* @return $this
*/
public function setStatus($status);
/**
* Get the status of the payload.
*
* @return string
*/
public function getStatus();
/**
* Set the Payload output.
*
* @param mixed $output
* @param string|null $wrapper
*
* @return $this
*/
public function setOutput($output, ? string $wrapper = null);
/**
* Get the Payload output.
*
* @return array
*/
public function getOutput();
/**
* Get the unwrapped Payload output.
*
* @return array
*/
public function getUnwrappedOutput();
/**
* Set the Payload messages.
*
* @param array $output
*
* @return $this
*/
public function setMessages(array $messages);
/**
* Get messages array from the payload.
*
* @return array
*/
public function getMessages();
/**
* Get the wrapper for the output.
*
* @return string
*/
public function getOutputWrapper();
/**
* Get the wrapper for messages.
*
* @return string
*/
public function getMessagesWrapper();
}composer testPlease see CHANGELOG for more information on what has changed recently.
Please see CONTRIBUTING for details.
If you discover any security related issues, please email clay@phpstage.com instead of using the issue tracker.
We plan to work on flexibility/configuration soon, as well as release a framework agnostic version of the package.
The MIT License (MIT). Please see License File for more information.