Skip to content

Commit 8607920

Browse files
SerafimArtsSerafimArts
committed
Add simple mapper docs
1 parent 98b8046 commit 8607920

File tree

10 files changed

+442
-7
lines changed

10 files changed

+442
-7
lines changed

‎.github/workflows/deploy.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ env:
1717
# Replace HI with the ID of the instance in capital letters
1818
ARTIFACT: webHelpTL2-all.zip
1919
# Writerside docker image version
20-
DOCKER_VERSION: '243.21565'
20+
DOCKER_VERSION: '2025.04.8412'
2121
ALGOLIA_ARTIFACT: 'algolia-indexes-TL.zip'
2222
ALGOLIA_APP_NAME: 'CZXH99BXN1'
2323
ALGOLIA_INDEX_NAME: 'Writerside'

‎Writerside/cfg/buildprofiles.xml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@
3636
</icons>
3737

3838
<footer>
39-
<social href="https://github.com/php-type-language" type="blog">GitHub</social>
39+
<social href="https://github.com/php-type-language" type="github">GitHub</social>
4040
<link href="https://packagist.org/packages/type-lang/parser">Packagist</link>
4141
<link href="https://github.com/php-type-language/parser/issues">Issue tracker</link>
4242
<link href="https://github.com/php-type-language/parser/pulls">Submit request</link>

‎Writerside/cfg/static/custom.css‎

Lines changed: 91 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,23 @@
1+
@import url('https://fonts.googleapis.com/css2?family=Roboto+Condensed:ital,wght@0,200;1,200&display=swap');
2+
13
:root {
24
--wh-color-accent-substrate-bg: #222330 !important;
35
--wh-color-border-hover: #4f57a7 !important;
46
--wh-color-backlight-pale: none;
57
--wh-color-backlight-pale-dark: none;
68
}
79

10+
h1, h2 {
11+
font-family: "Roboto Condensed", "JetBrains Sans Bundled", Inter, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, Cantarell, "Droid Sans", "Helvetica Neue", Arial, sans-serif !important;
12+
font-optical-sizing: auto !important;
13+
font-weight: 200 !important;
14+
font-style: normal !important;
15+
}
16+
17+
h1 {
18+
font-size: 48px !important;
19+
}
20+
821
.wh-header__product-logo {
922
width: 32px;
1023
height: 32px;
@@ -43,7 +56,33 @@
4356
}
4457

4558
.toc-item--highlighted {
46-
// background: none;
59+
background: none !important;
60+
}
61+
62+
.toc-item--theme-light:hover {
63+
background: rgba(25, 25, 28, .05) !important;
64+
background: var(--wh-color-backlight-main) !important;
65+
}
66+
67+
.toc-item--theme-dark:hover {
68+
background: hsla(0, 0%, 100%, .1) !important;
69+
background: var(--wh-color-white-t10) !important;
70+
}
71+
72+
.toc-item--selected.toc-item--theme-dark {
73+
cursor: default;
74+
background-color: #252528 !important;
75+
background-color: var(--wh-color-backlight-secondary-dark) !important;
76+
}
77+
78+
.toc-item--selected.toc-item--theme-light {
79+
cursor: default;
80+
background-color: #6b57ff !important;
81+
background-color: var(--wh-color-primary-light-theme) !important;
82+
}
83+
84+
.toc--theme-dark {
85+
background: none;
4786
}
4887

4988
.article__list + .code-block__wrapper,
@@ -59,9 +98,58 @@ p + .code-collapse__wrapper,
5998
border-radius: 7px;
6099
}
61100

62-
.starting-page-card:hover {
101+
.app__breadcrumbs {
102+
width: 706px;
103+
background: rgba(0, 0, 0, 0.05);
104+
border-radius: 7px;
105+
padding: 10px 0 10px 16px;
106+
}
107+
108+
html.theme-dark .app__breadcrumbs {
109+
background: rgba(255, 255, 255, 0.05);
110+
}
111+
112+
.theme-dark .starting-page-card {
113+
background: #1c2329 !important;
114+
}
115+
116+
.theme-dark .starting-page-card:hover {
117+
background: #252f37 !important;
118+
}
119+
120+
.article img {
121+
border-radius: 7px;
63122
}
64123

65124
#mermaid .flowchart-link {
66-
stroke: #59595c6b !important;
125+
stroke: #4f57a7 !important;
126+
}
127+
128+
#mermaid .node polygon,
129+
#mermaid .node rect {
130+
fill: rgba(0, 0, 0, .05) !important;
131+
stroke: transparent !important;
132+
rx: 7px !important;
67133
}
134+
135+
#mermaid .divider {
136+
stroke: rgba(0, 0, 0, .1) !important;
137+
}
138+
139+
html.theme-dark #mermaid .node polygon,
140+
html.theme-dark #mermaid .node rect {
141+
fill: rgba(255, 255, 255, .05) !important;
142+
}
143+
144+
html.theme-dark #mermaid .node span {
145+
color: #a9b7c6 !important;
146+
font-size: 95%;
147+
}
148+
149+
html.theme-dark #mermaid .divider {
150+
stroke: #1c2329 !important;
151+
}
152+
153+
.code-comparer__code-line {
154+
border-radius: 3px;
155+
}

‎Writerside/labels.list‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,11 @@
77
The implementation of the functionality available for installation
88
of "type-lang/parser" component.
99
</primary-label>
10+
<primary-label href="https://packagist.org/packages/type-lang/mapper"
11+
id="mapper-component" name="type-lang/mapper" short-name="m" color="red">
12+
The implementation of the functionality available for installation
13+
of "type-lang/mapper" component.
14+
</primary-label>
1015
<primary-label href="https://packagist.org/packages/type-lang/printer"
1116
id="printer-component" name="type-lang/printer" short-name="c" color="purple">
1217
The implementation of the functionality available for installation

‎Writerside/tl.tree‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,8 @@
55
<instance-profile id="tl" name="PHP TypeLang" is-library="true" start-page="overview.topic">
66
<toc-element topic="overview.topic" />
77

8-
<toc-element toc-title="Language">
8+
<toc-element toc-title="Language"
9+
topic="introduction.md">
910
<toc-element topic="basic-types.md"
1011
toc-title="Basic types"/>
1112
<toc-element topic="logical-types.md"
@@ -29,14 +30,22 @@
2930
<toc-element topic="comparison.md"
3031
toc-title="Comparison of syntax between different tools" />
3132

32-
<toc-element toc-title="Other tools">
33+
<toc-element toc-title="See also">
3334
<toc-element toc-title="PHPStan" href="https://phpstan.org/writing-php-code/phpdoc-types" />
3435
<toc-element toc-title="Psalm" href="https://psalm.dev/docs/annotating_code/typing_in_psalm/" />
3536
<toc-element toc-title="PhpStorm" href="https://www.jetbrains.com/help/phpstorm/php-type-checking.html" />
3637
<toc-element toc-title="phpDocumentor" href="https://docs.phpdoc.org/guide/guides/types.html" />
3738
</toc-element>
3839
</toc-element>
3940

41+
<toc-element toc-title="Mapper"
42+
topic="data-mapper.md">
43+
<toc-element topic="mapper-configuration.md" />
44+
<toc-element topic="platforms.md">
45+
<toc-element topic="standard-platform.md" />
46+
</toc-element>
47+
</toc-element>
48+
4049
<toc-element toc-title="Components">
4150
<toc-element topic="parser.md" toc-title="Parser">
4251
<toc-element topic="features.md"

‎Writerside/topics/data-mapper.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# Data Mapper
2+
3+
<primary-label ref="mapper-component"/>
4+
<show-structure for="chapter" depth="2"/>
5+
6+
A mapper is a system that transforms internal data into external data
7+
(normalization) and vice versa (denormalization) using a set of declarative
8+
transformation rules.
9+
10+
A mapper can be used in the ACL layer (anti-corruption) for transforming DTOs
11+
or for interacting with the database (converting primitive data into full-fledged
12+
entities and value objects). It can also be used for serialization and
13+
deserialization of data in command or query buses. It can also be used to
14+
transform JSON data in APIs into full-fledged DTOs, and much more.
15+
16+
## Installation
17+
18+
<tldr>
19+
<p>
20+
Via <a href="https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies">Composer</a>:
21+
<code lang="bash">composer require type-lang/mapper</code>
22+
</p>
23+
</tldr>
24+
25+
**Requirements:**
26+
* `PHP >= 8.1`
27+
* `ext-pcre`
28+
29+
## Usage
30+
31+
To create a mapper, you should use instantiation of the `TypeLang\Mapper\Mapper`
32+
object, after which the code is ready to use.
33+
34+
```php
35+
$mapper = new TypeLang\Mapper\Mapper();
36+
```
37+
38+
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
49+
$mapper = new TypeLang\Mapper\Mapper();
50+
51+
$result = $mapper->denormalize($data, Example::class);
52+
```
53+
54+
As you can see, the denormalization process requires information about the type
55+
to which the incoming data will be converted.
56+
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.
60+
61+
```php
62+
$mapper->normalize(new Example(), Example::class);
63+
```
64+
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.
68+
69+
```php
70+
$result = $mapper->normalize(new Example(), <<<'PHP'
71+
object{
72+
field: non-empty-string,
73+
another: int<0, max>,
74+
}
75+
PHP);
76+
```
77+
78+
The types themselves, their availability, capabilities, functionality and
79+
behavior depend on the selected platform.
80+
81+
<note>
82+
The general <b>standard</b> <a href="platforms.md">platform</a> one is used by default
83+
</note>

‎Writerside/topics/language/introduction.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Introduction
2+
3+
The vast majority of PHP developers encounter the type system used in docblocks
4+
on a daily basis. For example, you may have seen constructs like these:
5+
6+
```php
7+
/**
8+
* @param int[] $param Example array parameter
9+
*
10+
* @return int An example return type
11+
*
12+
* @throws \OutOfBoundsException in case of something went wrong
13+
*/
14+
function example(array $param): int {}
15+
```
16+
17+
There are many possible variations of tags (identifiers starting with the `@`
18+
symbol) in docblocks (phpdoc), however, they all share one common feature: the
19+
use of type declaration syntax. For example, in the case of the `@param` tag,
20+
the type is `int[]`, while in the case of `@throws`, it is `\OutOfBoundsException`.
21+
22+
The TypeLang and grammar describes exclusively the syntax of such types, which can
23+
be used for various tasks; In the vast majority of cases, these will be docblocks,
24+
but other use cases are possible.
25+
26+
On the documentation pages you will find both a description of the syntax of this
27+
type description language and a comparison table of supported features between
28+
different tools: TypeLang, PHPStan, Psalm, etc.

0 commit comments

Comments
 (0)