darkghosthunter / fluid
Fluid utility class based on Laravel's Fluent class
Fund package maintenance!
Ko Fi
paypal.me/darkghosthunter
Installs: 1 038
Dependents: 2
Suggesters: 0
Security: 0
Stars: 1
Watchers: 1
Forks: 0
Open Issues: 0
Requires
- php: >=7.4
- ext-json: *
Requires (Dev)
- phpunit/phpunit: ^9.3
This package is auto-updated.
Last update: 2022-02-25 18:20:44 UTC
README
Fluid
A flexible class based on the famous Laravel's Fluent and Eloquent Model class.
Fluid will allow you to flexible manipulate a class as a bag of properties (or array keys), and allow simple serialization while hiding sensible data from your users.
Installation
Fire up composer and require it into your project.
composer require darkghosthunter/fluid
Otherwise, you can just download this as a ZIP file and require it manually in your code:
<?php require_once 'path/to/fluid/Fluid.php'; require_once 'path/to/fluid/Concerns/HasArrayAccess.php'; require_once 'path/to/fluid/Concerns/HidesAttributes.php'; require_once 'path/to/fluid/Concerns/HasInstanceHelpers.php'; // Optionally, these two together too require_once 'path/to/fluid/FluidFillable.php'; require_once 'path/to/fluid/Exceptions/InvalidAttributeException.php';
Usage
The Fluid class is a class that can be accessed as a normal object or array. It can be serialized to an array, string or JSON.
You can instance Fluid like the normal way, or just using make()
:
<?php use DarkGhostHunter\Fluid\Fluid; $emptyFluid = new Fluid; $fluid = new Fluid(['foo' => 'bar']); $otherFluid = Fluid::make(['foo' => 'bar']); $otherEmptyFluid = Fluid::make();
You can also use fromJson()
if you need to make an instance from a JSON string:
<?php use DarkGhostHunter\Fluid\Fluid; $fluid = Fluid::fromJson('"{"foo":"bar"}"'); echo $fluid->foo; // 'bar'
To be totally safe to use, these static helper methods will return your class that extended the Fluid
instead of the base class. So using Oil::make()
will return an instance of Oil
.
<?php use DarkGhostHunter\Fluid\Fluid; class Water extends Fluid { // ... } $water = Water::make(); get_class($water); // 'Water'
Override the static helpers
Fluid uses the magic of __callStatic
to create a new instance. In previous versions you could not override the static methods with your own logic, but now you can:
<?php use DarkGhostHunter\Fluid\Fluid; class Water extends Fluid { /** * My Custom "Make" static method * * @return \DarkGhostHunter\Fluid\Fluid|string */ public static function make() { return 'My Custom Logic'; } } echo Water::make(); // 'My Custom Logic'
Attributes
Every attribute lies inside a protected array called $attributes
, and each of these can be set as it was a property or an array.
<?php use DarkGhostHunter\Fluid\Fluid; $fluid = new Fluid(['foo' => 'bar']); $fluid->foo = 'notBar'; $fluid['baz'] = 'qux'; echo $fluid->foo; // 'notBar'; echo $fluid['baz']; // 'qux' echo $fluid['thisAttributeDoesNotExists']; // null echo $fluid->thisAlsoDoesNotExists; // null
For convenience, if a property or array key doesn't exists it will return null.
Serializing
Serializing means taking the class to another representation, like an array or string.
To serialize as an array, use the toArray()
method.
<?php use DarkGhostHunter\Fluid\Fluid; $fluid = new Fluid(['foo' => 'bar']); $array = $fluid->toArray(); echo $fluid['foo']; // 'bar'
Since there is no magic for using
(array)$fluid
, the latter will serialize every property, so to avoid that.
Serializing to a string will output JSON, as with the toJson()
method.
<?php use DarkGhostHunter\Fluid\Fluid; $fluid = new Fluid(['foo' => 'bar']); $json = (string)$fluid; $moreJson = $fluid->toJson(); echo $json; // "{"foo":"bar"}" echo $moreJson; // "{"foo":"bar"}"
Hiding attributes from serialization
Sometimes is handy to hide attributes from serialization, like application keys, API secrets, user credentials or certificate locations.
You can turn this on using shouldHide()
method, or if you're extending Fluid
, setting $shouldHide
to false.
<?php use DarkGhostHunter\Fluid\Fluid; class Water extends Fluid { /** * Attributes to hide on serialization * * @var array */ protected $hidden; /** * Should hide attributes on serialization * * @var bool */ protected $shouldHide = true; // ... } $fluid = new Fluid; $fluid->shouldHide();
Set the attributes to hide inside the $hidden
property. Alternatively, you can use the setHidden()
method after is instanced.
<?php use DarkGhostHunter\Fluid\Fluid; $fluid = new Fluid(['foo' => 'bar', 'baz' => 'qux']); $fluid->setHidden(['baz']); $fluid->shouldHide(); echo $fluid->baz; // 'qux' echo $fluid['baz']; // 'qux' print_r($fluid->toArray()); // Array( ['foo' => 'bar'] ) echo (string)$fluid; // "{"foo":"bar"}"
Fillable
Sometimes you want to ensure the user doesn't fill anything more than some predetermined attributes. You can use the FluidFillable
class to enforce this.
You can put the attributes allowed to be set in the $fillable
array or use setFillable()
afterwards.
<?php use DarkGhostHunter\Fluid\FluidFillable; $fluid = new FluidFillable(['foo' => 'bar', 'baz' => 'qux']); $fluid->setFillable(['foo', 'baz']); $fluid->alpha = 'bravo'; /* * [!] DarkGhostHunter\Fluid\Exceptions\InvalidAttributeException * * Attribute [foo] in not set as fillable in FluidFillable. */
The user will get a InvalidAttributeException
when trying to set an attribute which is not fillable in the class.
You can use this to force developers to only allow certain attributes inside an instance, allowing you to displace any filtering logic once the instance is processed in your application.
License
This package is licenced by the MIT License.