Laravel Fluent Part One: Introduction

This article is part of a two part series covering the Laravel Fluent API. The articles in this series are:

• Laravel Fluent Part One: Introduction
• Laravel Fluent Part Two: The Public API

The Illuminate\Support\Fluent class is a useful data type. It allows for the construction of a data "container" similar to an array or instance of stdClass. However, the Fluent class makes it easier to make assumptions about the data the class instance contains. The following array and stdClass instance will be used for the next couple of examples:

 1<?php
 2 
 3// Create a new array containing sample data
 4$testArray = [
 5    'first'  => 'The first value',
 6    'second' => 'The second value',
 7    'third'  => 'The third value'
 8];
 9 
10// Create a new stdClass instance containing sample data
11$testObject = new stdClass;
12$testObject->first  = 'The first value';
13$testObject->second = 'The second value';
14$testObject->third  = 'The third value';

We can access data from the $testArray like so:

1<?php
2 
3// Retrieve the 'first' item
4$value = $testArray['first'];

The $value variable would now contain the value The first value. Similarly, data can be retrieved from the stdClass instance using object operator (often called the "arrow"):

1<?php
2 
3// Retrieve the 'first' property
4$value = $testObject->first;

Like in the previous example, the $value variable would now contain the value The first value. There is nothing surprising going on here. However, what happens when a developer needs to make assumptions about the data their code is working with? Uncertain developers often litter code with unwieldy if statements and similar constructs. Failure to do so generally results in fatal errors.

For example, attempting to retrieve data from an array that does not exist results in an instance of ErrorException being thrown:

1<?php
2 
3// Will raise an exception
4$value = $testArray['does_not_exist'];

The exact error message will differ between single or multi-dimensional arrays, but the principal is the same. PHP does not like it when code attempts to access array elements that do not exist.

The same can be said for accessing an object's properties:

1<?php
2 
3// Will raise an exception
4$value = $testObject->doesNotExist;

The above code example will again throw an instance of ErrorException, with the error message being something similar to "Undefined property: stdClass::$doesNotExit". To work around this, the following code can be written:

 1<?php
 2 
 3// Get a value from an array, or a default value
 4// if it does not exist.
 5 
 6if (array_key_exists('does_not_exist', $testArray))
 7{
 8    $value = $testArray['does_not_exist'];
 9} else {
10    $value = 'Some default value';
11}
12 
13 
14// Get a value from an object, or a default value
15// if it does not exist.
16 
17if (property_exists('doesNotExist', $testObject))
18{
19    $objectValue = $testObject->doesNotExist;
20} else {
21    $objectValue = 'Some default value';
22}

In the above code example, we checked to see if an object instance has a value by using the property_exists function instead of the isset function. This is because the property_exist function will return true if the property exists and has a value of null. The isset function will return false if the property exists but has a value of null.

Developers need to assume things about code quite often. In a perfect world, developers would know exactly what data an array or object their code interacts with contains. However, when dealing with remote data, such as data from external APIs, or when interfacing with code from multiple development teams, this is not always possible. The Fluent class can be used to simplify things for developers.

The following example will create a new Fluent instance with some data:

 1<?php
 2 
 3// Some example data, which could be obtained from
 4// any number of sources.
 5$testArray = [
 6    'first'  => 'The first value',
 7    'second' => 'The second value',
 8    'third'  => 'The third value'
 9];
10 
11// Create a new Fluent instance.
12$fluent = new Fluent($testArray);

Now that we have a Fluent instance, data can be retrieved just like an object or an array:

1<?php
2 
3// Accessing a value like an array.
4$value = $fluent['first'];
5 
6// Accessing a value like an object.
7$secondValue = $fluent->first;

Both $value and $secondValue would contain the value The first value. Accessing data that does not exist now simply returns null, without raising an error:

1<?php
2 
3$value = $fluent['does_not_exist'];
4 
5$secondValue = $fluent->doesNotExist;

Both $value and $secondValue would contain the value null. The Fluent class does expose public methods in its API to custom the default value returned.

∎