fractal maintained by saad
You can pull in the package via composer:
composer require saad/fractalThe package will automatically register itself.
this package is compatible with laravel versions >= 5.5
V 1.2.0
- Add Strict Mode, so for null resources instead of returning empty array it will return null, By Default strict mode is Enabled
Exactly as spatie except that this package is automatically parse includes or excludes from parameters first if defined, otherwise it will look for query string includes and excludes
Default serializer is ArraySerializer
you can generate a new transformer class using the following command
the following command will create "App\Transformers\UserTransformer.php"
php artisan make:transformer 'App\User'to create in nested folders "App\Transformers\Sub1\Sub2\UserTransformer.php"
php artisan make:transformer 'App\User' --nest='Sub1\Sub2'
# Nest Name could be:
# Sub1/Sub2
# /Sub1/Sub2/
# Sub1\\Sub2will include defined includes from
availableIncludesarray
// assume that Request Url = /countries?include=name,code,iso
$couintries = Country::all();
$transformed_data = \Saad\Fractal\Fractal::create($countries, new CountryTransformer());
// CountryTransformer will include name, code and iso
we could also pass includes to create method as the
4th argumentwhich will have the heighest periority than request include will include defined includes fromavailableIncludesarray
// assume that Request Url = /countries?include=name,code,iso
$couintries = Country::all();
$transformed_data = \Saad\Fractal\Fractal::create($countries, new CountryTransformer(), null, 'name,iso');
// CountryTransformer will include only name and iso
will exclude defined includes from
defaultIncludesarray
// assume that Request Url = /countries?exclude=name,code
$couintries = Country::all();
$transformed_data = \Saad\Fractal\Fractal::create($countries, new CountryTransformer());
// CountryTransformer will exclude name and code from default includes
we could also pass excludes to create method as the
5th argumentwhich will have the heighest periority than request include will include defined includes fromdefaultIncludesarray
// assume that Request Url = /countries?exclude=name,code,iso
$couintries = Country::all();
$transformed_data = \Saad\Fractal\Fractal::create($countries, new CountryTransformer(), null, null, 'name');
// CountryTransformer will exclude only name from defaultIncludes
this package has a base abstract Transformer Class Saad\Fractal\Transformers\TransformerAbstract you could use as the base class of your transformers, this class is based on extends League\Fractal\TransformerAbstract and adds the following features:
This mode added since V 1.2.0
null resources is returning empty array, when enable strict mode it will return NULL instead. By default strict mode is enabled
To control strict mode you could call one of these methods in one of the service providers boot method:
Enable Strict Mode (Enabled By Default):
TransformerAbstract::strictMode(true)
TransformerAbstract::enableStrictMode()
Disable Strict Mode:
TransformerAbstract::strictMode(false)
TransformerAbstract::disableStrictMode()
// Assume we have this transformer
class CountryTransformer extends TransformerAbstract {
...
includeRegions(Country $country) {
// assume there are no regions
return $this->null();
}
}
$transformer = new CountryTransformer();
$output = Fractal::create($country, $transformer);
// output when strict mode is enabled (default status)
[
...
'regions' => null,
]
// Disable Strict Mode
TransformerAbstract::disableStrictMode();
$output = Fractal::create($country, $transformer);
// output when strict mode is disabled
[
...
'regions' => [],
]
you should use
transforWithDefault()methodcinstead oftransform()method this is because the newaddEexternalfeature
you can add external value to output
$transformer = new CountryTransformer();
$output = Fractal::create($country, $transformer);
// assume this output of country is
[
'name' => 'Egypt',
'iso' => 'EG'
]
// If we want to add another key to output
$transformer->addExternal('new_key', 'Iam New Value');
$output = Fractal::create($country, $transformer);
// Then output of country will be
[
'name' => 'Egypt',
'iso' => 'EG',
'new_key' => 'Iam New Value',
]
// We can also add external which have a calculated value depends on transformed object
// assume we want to add new key to output named 'name_iso' which its value is the concatenation of both 'name' and 'iso' properies
$transformer->addExternal('name_iso', function ($country_object) {
return $country_object->name . '_' . $country_object->iso;
});
$output = Fractal::create($country, $transformer);
// Then output of country will be
[
'name' => 'Egypt',
'iso' => 'EG',
'name_iso' => 'Egypt_EG',
]
will add provided keys to defaultIncludes array
// assume that defaultIncludes are ['id', 'name']
$transformer = new CountryTransformer();
$transformer->addDefaultInclude(['iso']);
$output = Fractal::create($country, $transformer);
// assume this output of country is
[
'id' => 1,
'name' => 'Egypt',
'iso' => 'EG' // added to defaultIncludes
]this package also contains a singletone Saad\Fractal\FractalRequestParser
which is a helper class that provides usefull methods about Request includes and excludes
with the following methods :
Saad\Fractal\FractalRequestParser::includesHas($key_path)
Saad\Fractal\FractalRequestParser::excludesHas($key_path)
assume we have the following request URI
?include=name,sub.name:lang(ar),sub.country
$parser = Saad\Fractal\FractalRequestParser::getInstance();
// we can check the following
$parser->includesHas('name'); // true
$parser->includesHas('sub'); // true
$parser->includesHas('sub.name'); // true
$parser->includesHas('sub.country'); // true
$parser->includesHas('iso'); // false
$parser->includesHas('sub.country.name'); // falsethe same for excludesHas()