README

Spatie/Fractal

安装

您可以通过composer引入此包

	composer require saad/fractal

该包将自动注册自身。

Laravel版本

此包与laravel版本>= 5.5兼容

变更日志

V 1.2.0

1. 添加严格模式，对于null资源，它将返回null而不是空数组，默认情况下严格模式已启用

使用

与spatie完全相同，只不过此包会自动解析参数中的包含或排除，如果已定义，否则它将查找查询字符串中的包含和排除

默认序列化器为ArraySerializer

控制台生成器

您可以使用以下命令生成新的转换器类

以下命令将创建 "App\Transformers\UserTransformer.php"

	php artisan make:transformer 'App\User'

要创建嵌套文件夹 "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

请求包含

将包含来自 availableIncludes 数组的定义的包含项

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

强制包含

我们还可以将包含项传递给创建方法作为 第4个参数，这将具有比请求包含更高的优先级，将包含来自 availableIncludes 数组的定义的包含项

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

请求排除

将排除来自 defaultIncludes 数组的定义的包含项

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

强制排除

我们还可以将排除项传递给创建方法作为 第5个参数，这将具有比请求包含更高的优先级，将包含来自 defaultIncludes 数组的定义的包含项

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

转换器抽象类

此包有一个基本的抽象转换器类 Saad\Fractal\Transformers\TransformerAbstract，您可以用作转换器的基础类，此类基于扩展 League\Fractal\TransformerAbstract 并添加以下功能

TransformerAbstract::strictMode(bool)

此模式自V 1.2.0版开始添加

当启用严格模式时，null资源将返回NULL而不是空数组，默认情况下严格模式已启用

要控制严格模式，您可以在某个服务提供者的boot方法中调用以下方法之一

启用严格模式（默认启用）
TransformerAbstract::strictMode(true)
TransformerAbstract::enableStrictMode()

禁用严格模式
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() 已替换为 transforWithDefault()

您应该使用 transforWithDefault() 方法而不是 transform() 方法，因为这涉及到新的 addEexternal 功能

addExternal($key, $value)

您可以将外部值添加到输出中

	$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)

将提供的键添加到defaultIncludes数组中

	// 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请求解析器单例

此包还包含一个单例 Saad\Fractal\FractalRequestParser，它是一个辅助类，提供有关请求包含和排除的有用方法，以下方法如下

Saad\Fractal\FractalRequestParser::includesHas($key_path)

Saad\Fractal\FractalRequestParser::excludesHas($key_path)

假设我们有一个以下请求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

对于 excludesHas() 也是一样