@@ -18,110 +18,139 @@ its definition.
18
18
19
19
Data objects can be simple, holding just a scalar value:
20
20
21
+ ```
21
22
$simple_data->value = 42;
22
23
$simple_data->value = 'cake';
23
24
$simple_data->value = TRUE;
25
+ ```
24
26
25
27
or complex, with child properties which are in turn simple:
26
28
29
+ ```
27
30
$complex_data->alpha = 42;
28
31
$complex_data->beta = 'cake;
29
32
$complex_data->gamma = TRUE;
33
+ ```
30
34
31
35
or can be complex themselves:
32
36
37
+ ```
33
38
$complex_data->child->grandchild->alpha = 42;
39
+ ```
34
40
35
41
Both simple or complex data may be multiple-valued:
36
42
43
+ ```
37
44
$multiple_simple_data[] = 'adding new value';
38
45
$multiple_simple_data[0] = 'changing existing value';
39
46
40
47
$multiple_complex_data[]->alpha = 'adding new value';
41
48
$multiple_complex_data[0]->beta = 'changing existing value';
49
+ ```
42
50
43
51
Complex data can be mutable, which means that its child properties change in
44
52
response to a controlling property's value:
45
53
54
+ ```
46
55
$animal->type = 'mammal';
47
56
$animal->gestation_period = '12 months';
48
57
$animal->type = 'reptile';
49
58
// The gestation_period property is removed; other properties may now have been
50
59
added.
60
+ ```
51
61
52
62
## Accessing data
53
63
54
64
Simple data is always accessed with the 'value' property:
55
65
66
+ ```
56
67
$simple_data->value = 'cake';
57
68
print $simple_data->value;
69
+ ```
58
70
59
71
Complex data is accessed with the child property names, which can be chained
60
72
until reaching the simple values at the tips of the structure:
61
73
74
+ ```
62
75
$complex_data->alpha->value = 'cake';
63
76
print $complex_data->alpha->value;
64
77
65
78
$complex_data->also_complex->value = 'cake';
66
79
print $complex_data->also_complex->alpha->value;
80
+ ```
67
81
68
82
As a shorthand, simple child values can be set with just the property name:
69
83
84
+ ```
70
85
$complex_data->alpha = 'cake';
86
+ ```
71
87
72
88
Multiple data can be used as a numeric array:
73
89
90
+ ```
74
91
$multiple_simple_data[0] = 'zero';
75
92
$multiple_simple_data[1] = 'one';
76
93
$multiple_simple_data[] = 'append';
94
+ ```
77
95
78
96
Note that the deltas must remain consistent:
79
97
98
+ ```
80
99
$multiple_simple_data[0] = 'zero';
81
100
$multiple_simple_data[42] = 'delta too high'; // throws Exception
101
+ ```
82
102
83
103
Whether multiple data is simple or complex, accessing the array produces a
84
104
data object:
85
105
106
+ ```
86
107
print $multiple_simple_data[0]->value;
87
108
print $multiple_complex_data[0]->alpha->value;
109
+ ```
88
110
89
111
### Iterating
90
112
91
113
All data objects can be iterated over.
92
114
93
115
Simple data has no effect:
94
116
117
+ ```
95
118
foreach ($simple_data as $item) {
96
119
// Nothing.
97
120
}
121
+ ```
98
122
99
123
Complex data iterates over its child properties:
100
124
125
+ ```
101
126
foreach ($complex_data as $name => $item) {
102
127
print $item->value;
103
128
}
129
+ ```
104
130
105
131
Multiple data iterates over the delta items:
106
132
133
+ ```
107
134
foreach ($multiple_data as $delta => $item) {
108
135
print $item->value;
109
136
}
137
+ ```
110
138
111
139
Because iterating simple items has no effect, iterating data items like this is
112
140
safe to do recursively into the data structure.
113
141
114
142
Alternatively, the items() method on data objects allows iteration that is
115
143
agnostic of cardinality:
116
144
145
+ ```
117
146
foreach ($simple_data->items() as $item) {
118
147
print $item->value; // Same as $simple_data->value
119
148
}
120
149
121
150
foreach ($multiple_simple_data->items() as $item) {
122
151
print $item->value;
123
152
}
124
-
153
+ ```
125
154
This is useful when working with a property that may be either single or
126
155
multiple, as it gives all the values in either case. However, it should not be
127
156
used recursively, as iterating on the value in the iteration for a simple item
@@ -175,12 +204,15 @@ have entered. See Drupal's Module Builder for an example of doing this.
175
204
176
205
Data is defined with a fluent interface:
177
206
207
+ ```
178
208
$definition = \MutableTypedData\Definition\DataDefinition::create('string')
179
209
->setLabel('Label')
180
210
->setRequired(TRUE);
211
+ ```
181
212
182
213
Complex data is defined by nesting properties:
183
214
215
+ ```
184
216
$definition = \MutableTypedData\Definition\DataDefinition::create('complex')
185
217
->setLabel('Label')
186
218
->setProperties([
@@ -190,12 +222,14 @@ $definition = \MutableTypedData\Definition\DataDefinition::create('complex')
190
222
'child_property_beta' => \MutableTypedData\Definition\DataDefinition::create('string')
191
223
->setLabel('Beta'),
192
224
]);
225
+ ```
193
226
194
227
### Options
195
228
196
229
Options can be defined with an array, or with objects, which allow options to
197
230
have descriptions as well as labels:
198
231
232
+ ```
199
233
$definition = \MutableTypedData\Definition\DataDefinition::create('string')
200
234
->setLabel('Label')
201
235
->setOptionsArray([
@@ -211,12 +245,14 @@ $definition = \MutableTypedData\Definition\DataDefinition::create('string')
211
245
\MutableTypedData\Definition\OptionDefinition::create('red', 'Magenta', 'A deep red'),
212
246
\MutableTypedData\Definition\OptionDefinition::create('grey', 'Grey', 'Not very colourful')
213
247
);
248
+ ```
214
249
215
250
### Mutable data
216
251
217
252
Mutable data needs a single property to control the variants, and then a
218
253
definition for each variant:
219
254
255
+ ```
220
256
$definition = \MutableTypedData\Definition\DataDefinition::create('mutable')
221
257
->setLabel('Label')
222
258
->setProperties([
@@ -241,6 +277,7 @@ $definition = \MutableTypedData\Definition\DataDefinition::create('mutable')
241
277
->setLabel('B2'),
242
278
]),
243
279
]);
280
+ ```
244
281
245
282
The variants automatically define the options for the type property.
246
283
0 commit comments