PHPackages                             saad/fractal - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. saad/fractal

ActiveLibrary[API Development](/categories/api)

saad/fractal
============

Wraper for spatie fractal package

1.2.0(7y ago)28.9k2MITPHP

Since Aug 31Pushed 7y ago1 watchersCompare

[ Source](https://github.com/ahmad-sa3d/saad-fractal)[ Packagist](https://packagist.org/packages/saad/fractal)[ RSS](/packages/saad-fractal/feed)WikiDiscussions master Synced today

READMEChangelogDependencies (1)Versions (16)Used By (2)

An easy to use Fractal wrapper built for Laravel applications upon Spatie/Fractal Package
=========================================================================================

[](#an-easy-to-use-fractal-wrapper-built-for-laravel-applications-upon-spatiefractal-package)

[Spatie/Fractal](https://github.com/spatie/laravel-fractal)

Install
-------

[](#install)

You can pull in the package via composer:

```
	composer require saad/fractal
```

The package will automatically register itself.

### Laravel Version

[](#laravel-version)

this package is compatible with laravel versions `>= 5.5`

### Changelog

[](#changelog)

> **V 1.2.0**

1. Add Strict Mode, so for null resources instead of returning empty array it will return null, By Default strict mode is Enabled

use
---

[](#use)

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`

### `Console Generator`

[](#console-generator)

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\\Sub2
```

### `Request Includes`

[](#request-includes)

> will include defined includes from **`availableIncludes`** array

```

	// 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

```

### `Force Includes`

[](#force-includes)

> we could also pass includes to create method as the `4th argument` which will have the heighest periority than request include will include defined includes from **`availableIncludes`** array

```

	// 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

```

### `Request Excludes`

[](#request-excludes)

> will exclude defined includes from **`defaultIncludes`** array

```

	// 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

```

### `Force Excludes`

[](#force-excludes)

> we could also pass excludes to create method as the `5th argument` which will have the heighest periority than request include will include defined includes from **`defaultIncludes `** array

```

	// 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

```

Transformer Abstract Class
--------------------------

[](#transformer-abstract-class)

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:

### *`TransformerAbstract::strictMode(bool)`*

[](#transformerabstractstrictmodebool)

> 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' => [],
    ]

```

### *`transform()`* replaced by *`transforWithDefault()`*

[](#transform-replaced-by-transforwithdefault)

> you should use **`transforWithDefault()`** methodcinstead of **`transform()`** method this is because the new `addEexternal` feature

### *`addExternal($key, $value)`*

[](#addexternalkey-value)

> 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',
	]

```

### *`addDefaultInclude(string|array $defaults_to_add)`*

[](#adddefaultincludestringarray-defaults_to_add)

> 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
	]
```

Fractal Request Parser Singletone
---------------------------------

[](#fractal-request-parser-singletone)

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');  // false
```

the same for **`excludesHas()`**

###  Health Score

34

—

LowBetter than 77% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity21

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity71

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~24 days

Recently: every ~7 days

Total

15

Last Release

2831d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/7927d2c9296987c6329eeda722cee82eb4622cff56b2b628f6a698a05e9ddad1?d=identicon)[ahmad-sa3d](/maintainers/ahmad-sa3d)

---

Top Contributors

[![ahmad-sa3d](https://avatars.githubusercontent.com/u/8466669?v=4)](https://github.com/ahmad-sa3d "ahmad-sa3d (31 commits)")

---

Tags

spatieapilaravellumentransformfractallaravel-fractal

### Embed Badge

![Health badge](/badges/saad-fractal/health.svg)

```
[![Health](https://phpackages.com/badges/saad-fractal/health.svg)](https://phpackages.com/packages/saad-fractal)
```

###  Alternatives

[spatie/laravel-fractal

An easy to use Fractal integration for Laravel applications

1.9k15.1M99](/packages/spatie-laravel-fractal)[spatie/fractalistic

A developer friendly wrapper around Fractal

38715.3M8](/packages/spatie-fractalistic)[flugger/laravel-responder

A Laravel Fractal package for building API responses, giving you the power of Fractal and the elegancy of Laravel.

8901.5M5](/packages/flugger-laravel-responder)[mollie/laravel-mollie

Mollie API client wrapper for Laravel & Mollie Connect provider for Laravel Socialite

3624.1M28](/packages/mollie-laravel-mollie)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)