Laravel 5 Fluent API: The Public API

The following sections will highlight the usage of the various public methods that the Fluent class provides. There are, however, some omissions in this section, namely the methods required to implement PHP's ArrayAccess interface. The examples that follow will assume the following test array and object, unless stated otherwise:

 1// A test array for use with Fluent.
 2$testArray = [
 3    'first'  => 'The first value',
 4    'second' => 'The second value',
 5    'third'  => 'The third value'
 6];
 7
 8// A test object for use with Fluent.
 9$testObject = new stdClass;
10$testObject->first  = 'The first value';
11$testObject->second = 'The second value';
12$testObject->third  = 'The third value';

#Retrieving Values With get

The get method will return the value associated with the provided $key. If the $key does not exist, the $default value will be returned (which is null by default).

#Signature

The signature of the get method is:

1public function get(
2    $key,
3    $default = null
4);

#Example Use

Retrieving values from a Fluent instance:

 1$fluent = new Fluent($testArray);
 2 
 3// The first value
 4$message = $fluent->get('first');
 5 
 6$fluent = new Fluent($testObject);
 7 
 8// The first value
 9$message = $fluent->get('first');
10 
11// null
12$willBeNull = $fluent->get('does_not_exist');

The $default value is evaluated using the value helper function, meaning that it can be the result of a function:

1$fluent = new Fluent($testArray);
2 
3// Does not exist yet!
4$message = $fluent->get('does_not_exist', function() {
5    return 'Does not exist yet!';
6});

#Fluent and Closures

If we look at the following code example, one might be tempted to say that the value of $message would be Hello, world!, but that would be incorrect:

 1$testObject = new stdClass;
 2$testObject->method = function() {
 3    return 'Hello, world!';
 4};
 5 
 6$fluent = new Fluent($testObject);
 7 
 8$message = $fluent->method;
 9 
10// Or even this:
11 
12$message = $fluent->get('method');

However, that would be incorrect. It is important to remember that the Fluent object is an elaborate key/value storage container that can behave like an array or an object. When the fluent container is created for an object containing a closure, such as the above example, the closure instance is stored as the value. The following code will quickly prove this:

1// true
2$isClosure = ($fluent->method instanceof Closure):

To evaluate the closure and get the results, the value helper function can be used:

1// Hello, world!
2$message = value($fluent->method);
3 
4// Hello, world!
5$message = value($fluent->get('method'));

#Getting Key/Value Data Associations With getAttributes

The getAttributes method simply returns an array containing all key/value pairs, representing the underlying data contained within the Fluent instance.

#Signature

The signature of the getAttributes method is:

1public function getAttributes();

#Example Use

After the following code is executed:

1$fluent = new Fluent($testObject);
2 
3$attributes = $fluent->getAttributes();

The $attributes variable would look have a value similar to the following:

1array
2  'first'  => string 'The first value'
3  'second' => string 'The second value'
4  'third'  => string 'The third value'

#Converting the Data Object to an Array With toArray

The toArray method returns the exact same values as the getAttributes method; the results of the toArray method will return an array with all of the key/value pairs of the Fluent instance.

#Signature

The signature of the toArray method is:

1public function toArray();

#Example Use

The following method calls are equivalent:

 1$testObject = new stdClass;
 2$testObject->method = function() {
 3    return 'Hello, world!';
 4};
 5 
 6$fluent = new Fluent($testObject);
 7 
 8// Using the `getAttributes` method.
 9$attributes = $fluent->getAttributes();
10 
11// Using the `toArray` method.
12$fluentArray = $fluent->toArray();

#Converting the Data Object to Something JSON Serializable With jsonSerialize

The jsonSerialize method internally returns a call to toArray. Because of this, toArray, jsonSerialize and getAttributes are all functionally equivalent. The jsonSerialize method exists to satisfy PHP's JsonSerializable interface, which allows developers to customize how a class is represented when using the json_encode function.

#Signature

The signature of the jsonSerialize method is:

1public function jsonSerialize();

#Example Use

The following method calls are equivalent:

 1$testObject = new stdClass;
 2$testObject->method = function() {
 3    return 'Hello, world!';
 4};
 5 
 6$fluent = new Fluent($testObject);
 7 
 8// Using the `getAttributes` method.
 9$attributes = $fluent->getAttributes();
10 
11// Using the `toArray` method.
12$fluentArray = $fluent->toArray();
13 
14// Using the `jsonSerialize` method.
15$jsonResult  = $fluent->jsonSerialize();

#Converting the Object to JSON With toJson

The toJson method will return a JSON encoded version of the data stored within the fluent instance. It internally does this by returning a call to PHP's json_encode function, passing in any $options that were supplied. Like the json_encode function, the $options parameter is a bitmask of the predefined JSON constants.

#Signature

The signature of the toJson method is:

1public function toJson(
2    $options = 0
3);

#Example Use

The following code:

1$testObject = new stdClass;
2$testObject->method = function() {
3    return 'Hello, world!';
4};
5 
6$fluent = new Fluent($testObject);
7 
8$jsonValue = $fluent->toJson();

would be converted into the following JSON, stored in the $jsonValue variable:

1{ "first":  "The first value",
2  "second": "The second value",
3  "third":  "The third value",
4  "method":{}
5}

Alternatively, a well-formatted value can be returned by passing in the JSON_PRETTY_PRINT constant:

1$fluent = new Fluent($testObject);
2 
3$jsonValue = $fluent->toJson(JSON_PRETTY_PRINT);

This time, the $jsonValue would contain the following value:

1{
2    "first": "The first value",
3    "second": "The second value",
4    "third": "The third value",
5    "method": {}
6}

#toJson and Deeply Nested Data Structures

The toJson method internally makes a call to PHP's json_encode function. Unlike json_encode, toJson does not provide a way to specify the depth (essentially how many arrays are nested inside of each other) to which data will be encoded, which is by default set to 512. To convert a fluent object into its JSON equivalent with a depth greater than 512, the following method will be sufficient:

 1$testObject = new stdClass;
 2$testObject->method = function() {
 3    return 'Hello, world!';
 4};
 5 
 6$fluent = new Fluent($testObject);
 7 
 8// Replace 512 with the desired depth.
 9$jsonValue = json_encode(
10    $fluent->jsonSerialize(),
11    0,
12    512
13);

∎