travelpayouts / src / interfaces / Arrayable.php

Arrayable.php in Travelpayouts trunk, at src/interfaces/Arrayable.php

94 lines 3.9 KB

Raw Download Zip

1	<?php
2
3	/**
4	* @link http://www.yiiframework.com/
5	* @copyright Copyright (c) 2008 Yii Software LLC
6	* @license http://www.yiiframework.com/license/
7	*/
8
9	namespace Travelpayouts\interfaces;
10
11	/**
12	* Arrayable is the interface that should be implemented by classes who want to support customizable representation of their instances.
13	*
14	* For example, if a class implements Arrayable, by calling [[toArray()]], an instance of this class
15	* can be turned into an array (including all its embedded objects) which can then be further transformed easily
16	* into other formats, such as JSON, XML.
17	*
18	* The methods [[fields()]] and [[extraFields()]] allow the implementing classes to customize how and which of their data
19	* should be formatted and put into the result of [[toArray()]].
20	*
21	* @author Qiang Xue <qiang.xue@gmail.com>
22	* @since 2.0
23	*/
24	interface Arrayable
25	{
26	/**
27	* Returns the list of fields that should be returned by default by [[toArray()]] when no specific fields are specified.
28	*
29	* A field is a named element in the returned array by [[toArray()]].
30	*
31	* This method should return an array of field names or field definitions.
32	* If the former, the field name will be treated as an object property name whose value will be used
33	* as the field value. If the latter, the array key should be the field name while the array value should be
34	* the corresponding field definition which can be either an object property name or a PHP callable
35	* returning the corresponding field value. The signature of the callable should be:
36	*
37	* ```php
38	* function ($model, $field) {
39	* // return field value
40	* }
41	* ```
42	*
43	* For example, the following code declares four fields:
44	*
45	* - `email`: the field name is the same as the property name `email`;
46	* - `firstName` and `lastName`: the field names are `firstName` and `lastName`, and their
47	* values are obtained from the `first_name` and `last_name` properties;
48	* - `fullName`: the field name is `fullName`. Its value is obtained by concatenating `first_name`
49	* and `last_name`.
50	*
51	* ```php
52	* return [
53	* 'email',
54	* 'firstName' => 'first_name',
55	* 'lastName' => 'last_name',
56	* 'fullName' => function ($model) {
57	* return $model->first_name . ' ' . $model->last_name;
58	* },
59	* ];
60	* ```
61	*
62	* @return array the list of field names or field definitions.
63	* @see toArray()
64	*/
65	public function fields();
66
67	/**
68	* Returns the list of additional fields that can be returned by [[toArray()]] in addition to those listed in [[fields()]].
69	*
70	* This method is similar to [[fields()]] except that the list of fields declared
71	* by this method are not returned by default by [[toArray()]]. Only when a field in the list
72	* is explicitly requested, will it be included in the result of [[toArray()]].
73	*
74	* @return array the list of expandable field names or field definitions. Please refer
75	* to [[fields()]] on the format of the return value.
76	* @see toArray()
77	* @see fields()
78	*/
79	public function extraFields();
80
81	/**
82	* Converts the object into an array.
83	*
84	* @param array $fields the fields that the output array should contain. Fields not specified
85	* in [[fields()]] will be ignored. If this parameter is empty, all fields as specified in [[fields()]] will be returned.
86	* @param array $expand the additional fields that the output array should contain.
87	* Fields not specified in [[extraFields()]] will be ignored. If this parameter is empty, no extra fields
88	* will be returned.
89	* @param bool $recursive whether to recursively return array representation of embedded objects.
90	* @return array the array representation of the object
91	*/
92	public function toArray(array $fields = [], array $expand = [], $recursive = true);
93	}
94