Skip to content

Commit

Permalink
Merge pull request #26 from Planetbiru/fearure/2.4
Browse files Browse the repository at this point in the history 
Fearure/2.4
  • Loading branch information
@kamshory
kamshory authored Oct 24, 2024
2 parents 7a7f300 + d317de9 commit 4e91298
Show file tree
Hide file tree
Showing 7 changed files with 569 additions and 24 deletions.
78 changes: 76 additions & 2 deletions manual/includes/_magic-dto.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,12 +27,30 @@ In modern applications, especially those that interact with third-party services

- The MagicDto class utilizes PHP annotations to clarify the purpose of each property. These annotations enhance code readability and provide useful metadata for serialization.

4. **XML Support**
- MagicDto provides support for both XML input and output. This feature allows seamless integration with systems that utilize XML as their primary data format, making it easier to work with various data sources and services.

To parse XML string, use method `MagicTdo::xmlToObject(string $xmlString)`. This method takes an XML string as input and returning it as a stdClass object.

### Class Structure

The `MagicDto` class is designed with properties that have protected access levels, ensuring encapsulation while still allowing derived classes to access these properties. Each property is annotated with `@var`, which specifies its data type. This structured approach enhances type safety and improves code quality.

#### Key Annotations

**Class Annotations**

1. **@JSON**

The `@JSON` annotation controls whether the JSON format should be prettified. Using `@JSON(prettify=true)` will format the output in a more readable way, while `@JSON(prettify=false)` will minimize the format

2. **@XML**

The `@XML` annotation controls whether the XML format should be prettified. Using `@XML(prettify=true)` will format the output in a more readable way, while `@XML(prettify=false)` will minimize the format


**Property Annotations**

1. **@Source**

The `@Source` annotation indicates the source property that maps to a specific field in the incoming data. If this annotation is omitted, MagicDto will default to using the property name that matches the class property name. This allows for flexibility in cases where the external API may use different naming conventions.
Expand All @@ -48,7 +66,7 @@ protected $title;
2. **@JsonProperty**

The `@JsonProperty` annotation specifies the output property name when data is serialized to JSON. If this annotation is not provided, MagicDto will serialize the property using its class property name. This ensures that data sent to third-party applications adheres to their expected format.

```php
/**
* @JsonProperty("album_title")
Expand All @@ -72,6 +90,26 @@ In this example, `@Source("album_name")` indicates that the incoming data will u

To facilitate bidirectional communication, we need two different DTOs. The `@Source` annotation in the first DTO corresponds to the `@JsonProperty` annotation in the second DTO, while the `@JsonProperty` in the first DTO maps to the `@Source` in the second DTO.

3. **@JsonFormat**

The @JsonFormat annotation specifies the output date-time format when data is serialized to JSON. The property type must be `DateTime`. It is written as `@JsonFormat(pattern="Y-m-d H:i:s")`. If this annotation is not provided, MagicDto will serialize the property using the default format Y-m-d H:i:s. This ensures that data sent to third-party applications adheres to their expected format.

Format the date and time according to the conventions used in the PHP programming language. This includes utilizing the built-in date and time functions, which allow for various formatting options to display dates and times in a way that is both readable and compatible with PHP's standards. Ensure that you adhere to formats such as 'Y-m-d H:i:s' for complete timestamps or 'd/m/Y' for more localized representations, depending on the specific requirements of your application.

MagicDto automatically parses input as both strings and integers. The integer is a unique timestamp, while the string date-time format must be one of the following:

- **'Y-m-d'**, // ISO 8601: 2024-10-24
- **'Y-m-d H:i:s'**, // ISO 8601: 2024-10-24 15:30:00
- **'Y-m-d\TH:i:s'**, // ISO 8601: 2024-10-24T15:30:00
- **'Y-m-d\TH:i:s\Z'**, // ISO 8601: 2024-10-24T15:30:00Z
- **'D, d M Y H:i:s O'**, // RFC 2822: Thu, 24 Oct 2024 15:30:00 +0000
- **'d/m/Y'**, // Local format: 24/10/2024
- **'d F Y'**, // Format with month name: 24 October 2024
- **'l, d F Y'** // Format with day of the week: Thursday, 24 October 2024




**Example:**

DTO on the Input Side
Expand All @@ -96,7 +134,8 @@ class AlbumDtoInput extends MagicDto
/**
* @Source("date_release")
* @JsonProperty("releaseDate")
* @var string
* @JsonFormat(pattern="Y-m-d H:i:s")
* @var DateTime
*/
protected $release;

Expand Down Expand Up @@ -384,6 +423,8 @@ class AgencyDto extends MagicDto

**Usage**

1. JSON Format

```php
$song = new Song(null, $database);
$song->find("1234");
Expand All @@ -393,6 +434,39 @@ header("Content-type: application/json");
echo $songDto;
```

2. XML Format

```php
$song = new Song(null, $database);
$song->find("1234");
$songDto = new SongDto($song);

header("Content-type: application/xml");
echo $songDto->toXml("root");
```

3. Parse XML

```php
$albumDto = new AlbumDto();
$obj = $albumDto->xmlToObject($xmlString);
// $obj is stdClass
header("Content-type: application/json");
echo json_encode($obj);
```

3. Load from XML

```php
$albumDto = new AlbumDtoInput();
$albumDto->loadXml($xmlString);
header("Content-type: application/json");
echo $albumDto;
```

`loadXml` method will load data from XML to `AlbumDtoInput`. `AlbumDtoInput` is the inverse of `AlbumDto`, where values of the `@JsonProperty` and `@Source` annotations are swapped. This inversion also applies to the objects contained within it.


#### Explanation

- **@Source**: This annotation specifies the path to the property within the nested object structure. In this case, `artist->agency->name` indicates that the `agencyName` will pull data from the `name` property of the `Agency` object linked to the `Artist`.
Expand Down
68 changes: 67 additions & 1 deletion manual/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1353,10 +1353,29 @@ <h3>Features of MagicDto</h3>
<li>The MagicDto class utilizes PHP annotations to clarify the purpose of each property. These annotations enhance code readability and provide useful metadata for serialization.</li>
</ul>
</li>
<li>
<p><strong>XML Support</strong></p>
<ul>
<li>MagicDto provides support for both XML input and output. This feature allows seamless integration with systems that utilize XML as their primary data format, making it easier to work with various data sources and services.</li>
</ul>
<p>To parse XML string, use method <code>MagicTdo::xmlToObject(string $xmlString)</code>. This method takes an XML string as input and returning it as a stdClass object.</p>
</li>
</ol>
<h3>Class Structure</h3>
<p>The <code>MagicDto</code> class is designed with properties that have protected access levels, ensuring encapsulation while still allowing derived classes to access these properties. Each property is annotated with <code>@var</code>, which specifies its data type. This structured approach enhances type safety and improves code quality.</p>
<h4>Key Annotations</h4>
<p><strong>Class Annotations</strong></p>
<ol>
<li>
<p><strong>@JSON</strong></p>
<p>The <code>@JSON</code> annotation controls whether the JSON format should be prettified. Using <code>@JSON(prettify=true)</code> will format the output in a more readable way, while <code>@JSON(prettify=false)</code> will minimize the format</p>
</li>
<li>
<p><strong>@XML</strong></p>
<p>The <code>@XML</code> annotation controls whether the XML format should be prettified. Using <code>@XML(prettify=true)</code> will format the output in a more readable way, while <code>@XML(prettify=false)</code> will minimize the format </p>
</li>
</ol>
<p><strong>Property Annotations</strong></p>
<ol>
<li>
<p><strong>@Source</strong></p>
Expand Down Expand Up @@ -1388,6 +1407,24 @@ <h4>Key Annotations</h4>
protected $title;</code></pre>
<p>In this example, <code>@Source("album_name")</code> indicates that the incoming data will use <code>album_name</code>, while <code>@JsonProperty("album_title")</code> specifies that when the data is serialized, it will be output as <code>album_title</code>.</p>
<p>To facilitate bidirectional communication, we need two different DTOs. The <code>@Source</code> annotation in the first DTO corresponds to the <code>@JsonProperty</code> annotation in the second DTO, while the <code>@JsonProperty</code> in the first DTO maps to the <code>@Source</code> in the second DTO.</p>
<ol start="3">
<li>
<p><strong>@JsonFormat</strong></p>
<p>The @JsonFormat annotation specifies the output date-time format when data is serialized to JSON. The property type must be <code>DateTime</code>. It is written as <code>@JsonFormat(pattern="Y-m-d H:i:s")</code>. If this annotation is not provided, MagicDto will serialize the property using the default format Y-m-d H:i:s. This ensures that data sent to third-party applications adheres to their expected format.</p>
<p>Format the date and time according to the conventions used in the PHP programming language. This includes utilizing the built-in date and time functions, which allow for various formatting options to display dates and times in a way that is both readable and compatible with PHP's standards. Ensure that you adhere to formats such as 'Y-m-d H:i:s' for complete timestamps or 'd/m/Y' for more localized representations, depending on the specific requirements of your application.</p>
<p>MagicDto automatically parses input as both strings and integers. The integer is a unique timestamp, while the string date-time format must be one of the following:</p>
<ul>
<li><strong>'Y-m-d'</strong>, // ISO 8601: 2024-10-24</li>
<li><strong>'Y-m-d H:i:s'</strong>, // ISO 8601: 2024-10-24 15:30:00</li>
<li><strong>'Y-m-d\TH:i:s'</strong>, // ISO 8601: 2024-10-24T15:30:00</li>
<li><strong>'Y-m-d\TH:i:s\Z'</strong>, // ISO 8601: 2024-10-24T15:30:00Z</li>
<li><strong>'D, d M Y H:i:s O'</strong>, // RFC 2822: Thu, 24 Oct 2024 15:30:00 +0000</li>
<li><strong>'d/m/Y'</strong>, // Local format: 24/10/2024</li>
<li><strong>'d F Y'</strong>, // Format with month name: 24 October 2024</li>
<li><strong>'l, d F Y'</strong> // Format with day of the week: Thursday, 24 October 2024</li>
</ul>
</li>
</ol>
<p><strong>Example:</strong></p>
<p>DTO on the Input Side</p>
<pre><code class="language-php">class AlbumDtoInput extends MagicDto
Expand All @@ -1409,7 +1446,8 @@ <h4>Key Annotations</h4>
/**
* @Source("date_release")
* @JsonProperty("releaseDate")
* @var string
* @JsonFormat(pattern="Y-m-d H:i:s")
* @var DateTime
*/
protected $release;

Expand Down Expand Up @@ -1668,12 +1706,40 @@ <h4>Code Implementation</h4>
}
</code></pre>
<p><strong>Usage</strong></p>
<ol>
<li>JSON Format</li>
</ol>
<pre><code class="language-php">$song = new Song(null, $database);
$song-&gt;find("1234");
$songDto = new SongDto($song);

header("Content-type: application/json");
echo $songDto;</code></pre>
<ol start="2">
<li>XML Format</li>
</ol>
<pre><code class="language-php">$song = new Song(null, $database);
$song-&gt;find("1234");
$songDto = new SongDto($song);

header("Content-type: application/xml");
echo $songDto-&gt;toXml("root");</code></pre>
<ol start="3">
<li>Parse XML</li>
</ol>
<pre><code class="language-php">$albumDto = new AlbumDto();
$obj = $albumDto-&gt;xmlToObject($xmlString);
// $obj is stdClass
header("Content-type: application/json");
echo json_encode($obj);</code></pre>
<ol start="3">
<li>Load from XML</li>
</ol>
<pre><code class="language-php">$albumDto = new AlbumDtoInput();
$albumDto-&gt;loadXml($xmlString);
header("Content-type: application/json");
echo $albumDto;</code></pre>
<p><code>loadXml</code> method will load data from XML to <code>AlbumDtoInput</code>. <code>AlbumDtoInput</code> is the inverse of <code>AlbumDto</code>, where values of the <code>@JsonProperty</code> and <code>@Source</code> annotations are swapped. This inversion also applies to the objects contained within it.</p>
<h4>Explanation</h4>
<ul>
<li>
Expand Down
Loading

0 comments on commit 4e91298

Please sign in to comment.