Skip to content

Commit 1f47213

Browse files
SerafimArtsSerafimArts
committed
Improve documentation pages and add providers short documentation
1 parent de04183 commit 1f47213

13 files changed

+267
-111
lines changed

‎Writerside/tl.tree‎

Lines changed: 37 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -45,60 +45,65 @@
4545
<toc-element topic="standard-platform.md" />
4646
<toc-element topic="custom-platform.md" />
4747
</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">
48+
49+
<toc-element topic="type-metadata.md"
50+
toc-title="Metadata">
6551
<toc-element topic="meta-configuration.md"
66-
toc-title="Writing Metadata"/>
52+
toc-title="Writing Metadata"/>
6753
<toc-element topic="meta-reader.md">
6854
<toc-element topic="meta-reader-reflection.md"
69-
toc-title="Reflection" />
55+
toc-title="Reflection" />
7056
<toc-element topic="meta-reader-attribute.md"
71-
toc-title="Attributes" />
57+
toc-title="Attributes" />
7258
<toc-element topic="meta-reader-phpdoc.md"
73-
toc-title="PHPDoc" />
59+
toc-title="PHPDoc" />
7460
<toc-element topic="meta-reader-array.md"
75-
toc-title="PHP Array" />
61+
toc-title="PHP Array" />
7662
<toc-element topic="meta-reader-php-config.md"
77-
toc-title="PHP Config Files" />
63+
toc-title="PHP Config Files" />
7864
<toc-element topic="meta-reader-json-config.md"
79-
toc-title="JSON Config Files" />
65+
toc-title="JSON Config Files" />
8066
<toc-element topic="meta-reader-neon-config.md"
81-
toc-title="NEON Config Files" />
67+
toc-title="NEON Config Files" />
8268
<toc-element topic="meta-reader-yaml-config.md"
83-
toc-title="YAML Config Files"/>
69+
toc-title="YAML Config Files"/>
8470
<toc-element topic="meta-reader-null.md"
85-
toc-title="Null" />
71+
toc-title="Null" />
8672
</toc-element>
8773
<toc-element topic="meta-provider.md">
8874
<toc-element topic="meta-provider-in-memory.md"
89-
toc-title="InMemory" />
75+
toc-title="InMemory" />
9076
<toc-element topic="meta-provider-psr6-cache.md"
91-
toc-title="PSR-6 Cache" />
77+
toc-title="PSR-6 Cache" />
9278
<toc-element topic="meta-provider-psr16-cache.md"
93-
toc-title="PSR-16 Cache" />
79+
toc-title="PSR-16 Cache" />
9480
<toc-element topic="meta-provider-null.md"
95-
toc-title="Null" />
81+
toc-title="Null" />
9682
</toc-element>
9783
<toc-element topic="meta-expressions.md" />
9884
<toc-element topic="meta-clock.md" />
9985
<toc-element topic="meta-references.md" />
10086
</toc-element>
101-
<toc-element topic="type-extractors.md">
87+
<toc-element topic="types.md">
88+
<toc-element topic="mixed-type.md" />
89+
<toc-element topic="bool-type.md" />
90+
<toc-element topic="custom-type.md" />
91+
</toc-element>
92+
<toc-element topic="type-builders.md"
93+
toc-title="Builders">
94+
<toc-element topic="custom-type-builder.md" />
95+
</toc-element>
96+
<toc-element topic="type-coercers.md"
97+
toc-title="Type Coercion (Casting)">
98+
<toc-element topic="array-key-type-coercer.md" />
99+
<toc-element topic="bool-type-coercer.md" />
100+
<toc-element topic="float-type-coercer.md" />
101+
<toc-element topic="int-type-coercer.md" />
102+
<toc-element topic="string-type-coercer.md" />
103+
<toc-element topic="custom-type-coercer.md" />
104+
</toc-element>
105+
<toc-element topic="type-extractors.md"
106+
toc-title="Type Inference">
102107
<toc-element topic="native-type-extractor.md" />
103108
<toc-element topic="custom-type-extractor.md" />
104109
</toc-element>

‎Writerside/topics/mapper/metadata/meta-configuration.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -845,8 +845,11 @@ specific runtime values:
845845
- `{{line}}` - The line in the PHP code where the error occurred
846846
- `{{code}}` - An error code
847847

848-
Let's specify an error message for property `string $name`, like
849-
`The {{field}} is invalid`.
848+
Let's specify an error message for property `string $name`, like:
849+
850+
```text
851+
The {{field}} is invalid
852+
```
850853

851854
Thus, if you pass an empty array (`[]`) to `"name"` property, the following
852855
error should occur:

‎Writerside/topics/mapper/metadata/provider/meta-provider-in-memory.md‎

Lines changed: 34 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,36 @@
11
# InMemory Metadata Provider
22

3-
// TODO
3+
<link-summary>
4+
Caches metadata in RAM
5+
</link-summary>
6+
7+
<tldr>
8+
<p>
9+
Class:
10+
<code>TypeLang\Mapper\Mapping\Provider\InMemoryProvider</code>
11+
</p>
12+
</tldr>
13+
14+
The in-memory provider returns metadata objects with intermediate
15+
caching of types in RAM.
16+
17+
To create an in-memory provider you should create a new
18+
`InMemoryProvider` instance, parent another provider
19+
(or [metadata reader](meta-reader.md)) in the constructor.
20+
21+
```php
22+
use TypeLang\Mapper\Mapper;
23+
use TypeLang\Mapper\Platform\StandardPlatform;
24+
use TypeLang\Mapper\Mapping\Provider\InMemoryProvider;
25+
26+
$provider = new InMemoryProvider(
27+
delegate: new AnotherMetadataProvider(),
28+
);
29+
30+
$mapper = new Mapper(
31+
[[[platform: new StandardPlatform(|standard-platform.md]]]
32+
meta: $provider,
33+
// ...
34+
),
35+
);
36+
```

‎Writerside/topics/mapper/metadata/provider/meta-provider-null.md‎

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,27 @@
11
# Null Metadata Provider
22

3-
// TODO
3+
<link-summary>
4+
Returns empty metadata objects
5+
</link-summary>
6+
7+
<tldr>
8+
<p>
9+
Class:
10+
<code>TypeLang\Mapper\Mapping\Provider\NullProvider</code>
11+
</p>
12+
</tldr>
13+
14+
This provider returns an empty metadata object containing only
15+
the required class name.
16+
17+
```php
18+
use TypeLang\Mapper\Mapper;
19+
use TypeLang\Mapper\Platform\StandardPlatform;
20+
use TypeLang\Mapper\Mapping\Provider\NullProvider;
21+
22+
$mapper = new Mapper(
23+
[[[platform: new StandardPlatform(|standard-platform.md]]]
24+
meta: new NullProvider(),
25+
),
26+
);
27+
```

‎Writerside/topics/mapper/metadata/provider/meta-provider-psr16-cache.md‎

Lines changed: 36 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,38 @@
11
# PSR-16 Cache Metadata Provider
22

3-
// TODO
3+
4+
<link-summary>
5+
Returns metadata using intermediate caching in the PSR-16 cache
6+
</link-summary>
7+
8+
<tldr>
9+
<p>
10+
Class:
11+
<code>TypeLang\Mapper\Mapping\Provider\Psr16CacheProvider</code>
12+
</p>
13+
</tldr>
14+
15+
Returns metadata using intermediate caching in the PSR-16 cache
16+
17+
```php
18+
use TypeLang\Mapper\Mapper;
19+
use TypeLang\Mapper\Platform\StandardPlatform;
20+
use TypeLang\Mapper\Mapping\Provider\Psr16CacheProvider;
21+
22+
$provider = new Psr6CacheProvider(
23+
// required PSR-16 cache pool
24+
[[[psr16: $psr6cache|https://www.php-fig.org/psr/psr-16/]]],
25+
// optional prefix
26+
prefix: 'mapper_',
27+
// optional cache TTL
28+
ttl: -1,
29+
// Reference to parent reader or provider
30+
delegate: new AnotherMetadataProvider(),
31+
);
32+
33+
$mapper = new Mapper(
34+
[[[platform: new StandardPlatform(|standard-platform.md]]]
35+
meta: $provider,
36+
),
37+
);
38+
```

‎Writerside/topics/mapper/metadata/provider/meta-provider-psr6-cache.md‎

Lines changed: 35 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,37 @@
11
# PSR-6 Cache Metadata Provider
22

3-
// TODO
3+
<link-summary>
4+
Returns metadata using intermediate caching in the PSR-6 cache
5+
</link-summary>
6+
7+
<tldr>
8+
<p>
9+
Class:
10+
<code>TypeLang\Mapper\Mapping\Provider\Psr6CacheProvider</code>
11+
</p>
12+
</tldr>
13+
14+
Returns metadata using intermediate caching in the PSR-6 cache
15+
16+
```php
17+
use TypeLang\Mapper\Mapper;
18+
use TypeLang\Mapper\Platform\StandardPlatform;
19+
use TypeLang\Mapper\Mapping\Provider\Psr6CacheProvider;
20+
21+
$provider = new Psr6CacheProvider(
22+
// required PSR-6 cache pool
23+
[[[psr6: $psr6CachePool|https://www.php-fig.org/psr/psr-6/]]],
24+
// optional prefix
25+
prefix: 'mapper_',
26+
// optional cache TTL
27+
ttl: -1,
28+
// Reference to parent reader or provider
29+
delegate: new AnotherMetadataProvider(),
30+
);
31+
32+
$mapper = new Mapper(
33+
[[[platform: new StandardPlatform(|standard-platform.md]]]
34+
meta: $provider,
35+
),
36+
);
37+
```

‎Writerside/topics/mapper/metadata/reader/meta-reader-array.md‎

Lines changed: 9 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -9,17 +9,6 @@ Reads metadata using passed PHP array
99
Class:
1010
<code>TypeLang\Mapper\Mapping\Reader\ArrayReader</code>
1111
</p>
12-
Arguments:
13-
<list>
14-
<li>
15-
(optional) <code>$config</code>:
16-
<code>array&lt;array-key, mixed></code>
17-
</li>
18-
<li>
19-
(optional) <code>$delegate</code>:
20-
<code>TypeLang\Mapper\Mapping\Reader\ReaderInterface</code>
21-
</li>
22-
</list>
2312
</tldr>
2413

2514
The PHP Array reader allows you to specify metadata declaratively using simple
@@ -39,6 +28,8 @@ create a new `ArrayReader` instance, passing the settings in the `$config`
3928
property.
4029

4130
```php
31+
use TypeLang\Mapper\Mapper;
32+
use TypeLang\Mapper\Platform\StandardPlatform;
4233
use TypeLang\Mapper\Mapping\Reader\ArrayReader;
4334

4435
$reader = new ArrayReader(config: [
@@ -50,6 +41,13 @@ $reader = new ArrayReader(config: [
5041
],
5142
],
5243
]);
44+
45+
$mapper = new Mapper(
46+
[[[platform: new StandardPlatform(|standard-platform.md]]]
47+
meta: $reader,
48+
// ...
49+
),
50+
);
5351
```
5452

5553
<tip>

‎Writerside/topics/mapper/metadata/reader/meta-reader-attribute.md‎

Lines changed: 32 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -9,17 +9,42 @@ Reads metadata using PHP attributes
99
Class:
1010
<code>TypeLang\Mapper\Mapping\Reader\AttributeReader</code>
1111
</p>
12-
Arguments:
13-
<list>
14-
<li>
15-
(optional) <code>$delegate</code>:
16-
<code>TypeLang\Mapper\Mapping\Reader\ReaderInterface</code>
17-
</li>
18-
</list>
1912
</tldr>
2013

2114
This reader is used to read PHP attributes to construct metadata.
2215

16+
To create it, it is enough to instantiate `AttributeReader` class:
17+
18+
```php
19+
use TypeLang\Mapper\Mapper;
20+
use TypeLang\Mapper\Platform\StandardPlatform;
21+
use TypeLang\Mapper\Mapping\Reader\AttributeReader;
22+
23+
$reader = new AttributeReader();
24+
25+
$mapper = new Mapper(
26+
[[[platform: new StandardPlatform(|standard-platform.md]]]
27+
meta: $reader,
28+
// ...
29+
),
30+
);
31+
```
32+
33+
After this, you will have access to the description of the types
34+
in the PHP Attributes:
35+
36+
```php
37+
use TypeLang\Mapper\Mapping\MapType;
38+
39+
final class UserInfo
40+
{
41+
public function __construct(
42+
#[MapType('non-empty-string')]
43+
public mixed $name,
44+
) {}
45+
}
46+
```
47+
2348
By default, it supports the following attributes:
2449
- `#[DiscriminatorMap]` - Allows to specify [a discriminator map](meta-configuration.md#discriminator-map)
2550
for a class or interface
@@ -40,14 +65,6 @@ By default, it supports the following attributes:
4065
- `#[SkipWhenNull]` - Allows to specify a ["when null" rule](meta-configuration.md#when-null)
4166
that will exclude a property during normalization
4267

43-
To create this reader, it is enough to instantiate `AttributeReader` class:
44-
45-
```php
46-
use TypeLang\Mapper\Mapping\Reader\AttributeReader;
47-
48-
$reader = new AttributeReader();
49-
```
50-
5168
<tip>
5269
You can find more information about <b>metadata configuration</b> rules
5370
in the <a href="meta-configuration.md">"metadata configuration" section</a>.

‎Writerside/topics/mapper/metadata/reader/meta-reader-null.md‎

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -9,19 +9,15 @@ Reads only the minimum required data (class name) from the class definition.
99
Class:
1010
<code>TypeLang\Mapper\Mapping\Reader\NullReader</code>
1111
</p>
12-
<p>
13-
Arguments:
14-
<code>~</code>
15-
</p>
1612
</tldr>
1713

1814
This reader returns an empty metadata object containing only
1915
the required class name.
2016

2117
```php
2218
use TypeLang\Mapper\Mapper;
23-
use TypeLang\Mapper\Mapping\Reader\NullReader;
2419
use TypeLang\Mapper\Platform\StandardPlatform;
20+
use TypeLang\Mapper\Mapping\Reader\NullReader;
2521

2622
$mapper = new Mapper(
2723
[[[platform: new StandardPlatform(|standard-platform.md]]]

0 commit comments

Comments
 (0)