Skip to content

Commit 124d7ad

Browse files
SerafimArtsSerafimArts
committed
Add more data mapper documentation pages
1 parent 6521fd3 commit 124d7ad

27 files changed

+3088
-56
lines changed

‎Writerside/cfg/glossary.xml‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,14 +3,20 @@
33
<terms>
44
<term name="FQN">Fully Qualified Name</term>
55
<term name="Identifier">A sequence that begins with a letter and contains
6-
letters, numbers, underscores, and dashes.</term>
6+
letters, numbers, underscores, and dashes</term>
77
<term name="publicity-or-privacy">The use of a work free of known copyright
88
restrictions may be otherwise regulated or limited. The work or its use
99
may be subject to personal data protection laws, publicity, image, or
1010
privacy rights that allow a person to control how their voice, image or
1111
likeness is used, or other restrictions or limitations under applicable
12-
law.</term>
12+
law</term>
1313
<term name="endorsement">In some jurisdictions, wrongfully implying that an
1414
author, publisher or anyone else endorses your use of a work may be
15-
unlawful.</term>
15+
unlawful</term>
16+
<term name="normalize">Normalization: The process of "simplifying" data;
17+
Transforming from an internal "PHP Type" to a simpler "External Type"
18+
</term>
19+
<term name="denormalize">Denormalization: The process of "enriching" data;
20+
Transforming an abstract "External Type" into a more concrete "PHP Type"
21+
</term>
1622
</terms>

‎Writerside/cfg/static/custom.css‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
--wh-color-border-hover: #4f57a7 !important;
66
--wh-color-backlight-pale: none;
77
--wh-color-backlight-pale-dark: none;
8+
--app-link-color-dark: #848CD5 !important;
89
}
910

1011
h1, h2 {

‎Writerside/tl.tree‎

Lines changed: 26 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,8 +41,33 @@
4141
<toc-element toc-title="Mapper"
4242
topic="data-mapper.md">
4343
<toc-element topic="mapper-configuration.md" />
44-
<toc-element topic="platforms.md">
44+
<toc-element topic="mapper-platforms.md">
4545
<toc-element topic="standard-platform.md" />
46+
<toc-element topic="custom-platform.md" />
47+
</toc-element>
48+
<toc-element topic="types.md">
49+
<toc-element topic="mixed-type.md" />
50+
<toc-element topic="bool-type.md" />
51+
<toc-element topic="custom-type.md" />
52+
</toc-element>
53+
<toc-element topic="type-builders.md">
54+
<toc-element topic="custom-type-builder.md" />
55+
</toc-element>
56+
<toc-element topic="type-coercers.md">
57+
<toc-element topic="array-key-type-coercer.md" />
58+
<toc-element topic="bool-type-coercer.md" />
59+
<toc-element topic="float-type-coercer.md" />
60+
<toc-element topic="int-type-coercer.md" />
61+
<toc-element topic="string-type-coercer.md" />
62+
<toc-element topic="custom-type-coercer.md" />
63+
</toc-element>
64+
<toc-element topic="type-metadata.md">
65+
<toc-element topic="meta-reader.md" />
66+
<toc-element topic="meta-provider.md" />
67+
</toc-element>
68+
<toc-element topic="type-extractors.md">
69+
<toc-element topic="native-type-extractor.md" />
70+
<toc-element topic="custom-type-extractor.md" />
4671
</toc-element>
4772
</toc-element>
4873

‎Writerside/topics/data-mapper.md‎

Lines changed: 58 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Data Mapper
22

3-
<primary-label ref="mapper-component"/>
3+
<primary-label ref="mapper-component" xmlns=""/>
44
<show-structure for="chapter" depth="2"/>
55

66
A mapper is a system that transforms internal data into external data
@@ -36,35 +36,40 @@ $mapper = new TypeLang\Mapper\Mapper();
3636
```
3737

3838
The mapper contains two transformation directions:
39-
- **Normalization** - the process of converting complex internal application
40-
data to external data (API, database, etc.)
41-
```php
42-
$mapper = new TypeLang\Mapper\Mapper();
43-
44-
$result = $mapper->normalize(new Example());
45-
```
46-
- **Denormalization** - the process of converting primitive data to
47-
application data types
48-
```php
39+
- <tooltip term="normalize">**Normalization**</tooltip> - the process of
40+
converting complex internal application data to external data (API,
41+
database, etc.)
42+
<code-block lang="PHP">
43+
$mapper = new TypeLang\Mapper\Mapper();
44+
45+
$result = $mapper->normalize(new Example());
46+
</code-block>
47+
- <tooltip term="denormalize">**Denormalization**</tooltip> - the process of
48+
converting simple external data to internal application data types
49+
<code-block lang="PHP">
4950
$mapper = new TypeLang\Mapper\Mapper();
5051

5152
$result = $mapper->denormalize($data, Example::class);
52-
```
53+
</code-block>
5354

54-
As you can see, the denormalization process requires information about the type
55-
to which the incoming data will be converted.
55+
As you can see, the <tooltip term="denormalize">denormalization process</tooltip>
56+
requires information about the type to which the incoming data will be converted.
5657

57-
With normalization, the type is optional, as it can be determined automatically
58-
based on the incoming data, but can also be explicitly specified as a
59-
second argument.
58+
With <tooltip term="normalize">normalization</tooltip>, the type is optional,
59+
as it can be [determined automatically](type-extractors.md) based on the
60+
incoming data, but can also be explicitly specified as a second argument.
6061

6162
```php
6263
$mapper->normalize(new Example(), Example::class);
6364
```
6465

65-
The type specified in the second argument of the normalization and
66-
denormalization methods can be arbitrary, as described in the
67-
[language grammar](introduction.md) section.
66+
The type specified in the second argument of the
67+
<tooltip term="normalize">normalization</tooltip> and
68+
<tooltip term="denormalize">denormalization</tooltip> methods can be arbitrary,
69+
as described in the [language grammar](introduction.md) section.
70+
71+
An example of this "type definition" is shown below. However, the capabilities
72+
(and existence) of this type depend on [the platform](mapper-platforms.md).
6873

6974
```php
7075
$result = $mapper->normalize(new Example(), <<<'PHP'
@@ -79,5 +84,36 @@ The types themselves, their availability, capabilities, functionality and
7984
behavior depend on the selected platform.
8085

8186
<note>
82-
The general <b>standard</b> <a href="platforms.md">platform</a> one is used by default
83-
</note>
87+
The general <a href="standard-platform.md"><b>standard</b> platform</a>
88+
one is used by default
89+
</note>
90+
91+
92+
## Customization
93+
94+
The `Mapper` can also take several additional arguments.
95+
96+
```php
97+
$mapper = new TypeLang\Mapper\Mapper(
98+
[[[platform: ...,|mapper-platforms.md]]]
99+
[[[config: ...,|mapper-configuration.md]]]
100+
[[[typeExtractorFactory: ...,|type-extractors.md]]]
101+
typeParserFactory: ...,
102+
typeRepositoryFactory: ...,
103+
);
104+
```
105+
106+
- `platform` - Allows to specify a set of specific types, type coercers,
107+
and syntax rules
108+
<tip>For more details, see the
109+
<a href="mapper-platforms.md">"platform" documentation</a></tip>
110+
- `config` - Allows to specify a custom configuration
111+
<tip>For more details, see the
112+
<a href="mapper-configuration.md">"configuration" documentation</a></tip>
113+
- `typeExtractorFactory` - Allows to specify custom rules for inferring types
114+
from values
115+
<tip>For more details, see the
116+
<a href="type-extractors.md">"type extractors" documentation</a></tip>
117+
- `typeParserFactory` - Allows to specify custom type parsing rules
118+
- `typeRepositoryFactory` - Allows to specify a custom implementation of
119+
the type registry (repository)

‎Writerside/topics/mapper/builders/custom-type-builder.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Custom Type Builder
2+
3+
// TODO

‎Writerside/topics/mapper/coercers/array-key-type-coercer.md‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
# Array Key Coercion
2+
3+
<link-summary>
4+
Cast passed value into a PHP "array key" type.
5+
</link-summary>
6+
7+
<tldr>
8+
<p>
9+
Class:
10+
<code>TypeLang\Mapper\Type\Coercer\ArrayKeyTypeCoercer</code>
11+
</p>
12+
<p>
13+
Output Type:
14+
<code>int|string</code>
15+
</p>
16+
</tldr>
17+
18+
Cast passed value into a PHP "array key" type. An "array key" in PHP it can be
19+
one of two types, either a `string` or an `int` number.
20+
21+
<table>
22+
<tr>
23+
<td>Input Value</td>
24+
<td>Output Result</td>
25+
<td>Description</td>
26+
</tr>
27+
<tr>
28+
<td>
29+
<code>string(T)</code>
30+
</td>
31+
<td>
32+
<code>string(T)</code>
33+
</td>
34+
<td>
35+
Returns string value &quot;as is&quot;
36+
</td>
37+
</tr>
38+
<tr>
39+
<td>
40+
<code>int(T)</code>
41+
</td>
42+
<td>
43+
<code>int(T)</code>
44+
</td>
45+
<td>
46+
Returns int value &quot;as is&quot;
47+
</td>
48+
</tr>
49+
<tr>
50+
<td>
51+
<code>bool(false)</code>
52+
</td>
53+
<td>
54+
<code>int(0)</code>
55+
</td>
56+
<td></td>
57+
</tr>
58+
<tr>
59+
<td>
60+
<code>bool(true)</code>
61+
</td>
62+
<td>
63+
<code>int(1)</code>
64+
</td>
65+
<td></td>
66+
</tr>
67+
<tr>
68+
<td>
69+
<code>null</code>
70+
</td>
71+
<td>
72+
<code>int(0)</code>
73+
</td>
74+
<td></td>
75+
</tr>
76+
<tr>
77+
<td>
78+
<code>float(T)</code>
79+
</td>
80+
<td>
81+
<code>int(T)</code>
82+
</td>
83+
<td>
84+
Converts float to an int without losing precision
85+
<sup><a href="array-key-type-coercer.md#t1-p1">[1]</a></sup>
86+
</td>
87+
</tr>
88+
<tr>
89+
<td>
90+
<code>Stringable</code>
91+
</td>
92+
<td>
93+
<code>string(T)</code>
94+
</td>
95+
<td>
96+
Converts <code>Stringable</code> object to a string
97+
<sup><a href="array-key-type-coercer.md#t1-p2">[2]</a></sup>
98+
</td>
99+
</tr>
100+
<tr>
101+
<td>
102+
<code>BackedEnum</code>
103+
</td>
104+
<td>
105+
<code>string(BackedEnum::$value)</code>
106+
</td>
107+
<td>
108+
Returns the value of the backed enum's case
109+
</td>
110+
</tr>
111+
<tr>
112+
<td>
113+
<code>UnitEnum</code>
114+
</td>
115+
<td>
116+
<code>string(UnitEnum::$name)</code>
117+
</td>
118+
<td>
119+
Returns the name of the unit enum's case
120+
</td>
121+
</tr>
122+
<tr>
123+
<td>Other</td>
124+
<td>
125+
<code>never</code>
126+
</td>
127+
<td>
128+
Throws <code>InvalidValueException</code> exception
129+
</td>
130+
</tr>
131+
</table>
132+
133+
<procedure title="Notes" collapsible="true">
134+
<step id="t1-p1">
135+
The float value must satisfy the following rules:
136+
<list>
137+
<li>
138+
Must not be more than <code>PHP_INT_MAX</code>
139+
</li>
140+
<li>
141+
Must not be less than <code>PHP_INT_MIN</code>
142+
</li>
143+
<li>
144+
The mantissa should be <code>0</code> (should be no loss of
145+
precision)
146+
</li>
147+
</list>
148+
</step>
149+
<step id="t1-p2">
150+
For objects implementing the <code>Stringable</code> interface, the
151+
<code>__toString()</code> method will be called.
152+
</step>
153+
</procedure>

‎Writerside/topics/mapper/coercers/bool-type-coercer.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# Bool Coercion
2+
3+
<link-summary>
4+
Cast passed value into a PHP boolean type.
5+
</link-summary>
6+
7+
<tldr>
8+
<p>
9+
Class:
10+
<code>TypeLang\Mapper\Type\Coercer\BoolTypeCoercer</code>
11+
</p>
12+
<p>
13+
Output Type:
14+
<code>bool</code>
15+
</p>
16+
</tldr>
17+
18+
Cast passed value into a PHP boolean type.
19+
20+
| Input Value | Output Result |
21+
|---------------|---------------|
22+
| `bool(false)` | `bool(false)` |
23+
| `string("")` | `bool(false)` |
24+
| `string("0")` | `bool(false)` |
25+
| `array([])` | `bool(false)` |
26+
| `null` | `bool(false)` |
27+
| `int(0)` | `bool(false)` |
28+
| `float(0.0)` | `bool(false)` |
29+
| Other | `bool(true)` |
30+
31+
<note>
32+
This type coercer does not cause type errors. All values not provided
33+
by the type coercer will be cast to the `bool(true)`.
34+
</note>
35+
36+
<warning>
37+
Note that the behavior deviates from PHP's built-in casts in
38+
favor of explicitness.
39+
40+
This means that the behavior of `(bool) $value`, `filter_var($value, FILTER_VALIDATE_BOOLEAN)`
41+
and the rules from `BoolTypeCoercer` will be different.
42+
43+
<code-block lang="PHP">
44+
$value = new \SimpleXMLElement('&lt;xml />');
45+
46+
// Built-in PHP behaviour:
47+
(bool) $value;
48+
// bool(false)
49+
50+
// Built-in "ext-filter" behaviour:
51+
filter_var($value, FILTER_VALIDATE_BOOLEAN);
52+
// bool(false)
53+
54+
// Bool coercer behaviour:
55+
$coercer->coerce($value);
56+
// bool(true)
57+
</code-block>
58+
</warning>

‎Writerside/topics/mapper/coercers/custom-type-coercer.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
# Custom Coercion
2+

0 commit comments

Comments
 (0)