157 lines
3.4 KiB
Markdown
157 lines
3.4 KiB
Markdown
# PHP DTO Library
|
|
|
|
Simple and lightweight PHP library for representing Data Transfer Objects (DTOs) with property value tracking.
|
|
|
|
## Features
|
|
|
|
- Easy to use abstract `Dto` class for creating data transfer objects
|
|
- Property value tracking with `Property` wrapper class
|
|
- Support for creating DTOs from arrays with automatic property name conversion
|
|
- Track whether properties are initialized or not
|
|
- Automatic conversion between kebab-case and camelCase
|
|
- Type-safe with PHP 7.4+ and PHP 8.0+
|
|
|
|
## Installation
|
|
|
|
Install the library via Composer:
|
|
|
|
```bash
|
|
composer require diffhead/php-dto
|
|
```
|
|
|
|
## Testing
|
|
|
|
Run the test suite:
|
|
|
|
```bash
|
|
composer test
|
|
```
|
|
|
|
## Requirements
|
|
|
|
- PHP 7.4 or higher
|
|
- `diffhead/php-interfaces` ^1.0
|
|
- `jawira/case-converter` ^3.6
|
|
|
|
## Quick Start
|
|
|
|
Create a DTO class by extending the `Dto` abstract class:
|
|
|
|
```php
|
|
<?php
|
|
|
|
use Diffhead\PHP\Dto\Dto;
|
|
use Diffhead\PHP\Dto\Property;
|
|
|
|
/**
|
|
* Properties inside the Dto class
|
|
* should be camelCase named and
|
|
* protected
|
|
*/
|
|
class UserCreate extends Dto
|
|
{
|
|
protected Property $firstName;
|
|
protected Property $lastName;
|
|
protected Property $email;
|
|
}
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Creating a DTO from Array
|
|
|
|
```php
|
|
/**
|
|
* But inside the source array you can use
|
|
* camelCase, pascal_case, kebab-case, etc
|
|
*/
|
|
$data = [
|
|
'first_name' => 'John',
|
|
'lastName' => 'Doe',
|
|
'email' => 'john@example.com'
|
|
];
|
|
|
|
$user = UserCreate::fromArray($data);
|
|
```
|
|
|
|
### Accessing Properties
|
|
|
|
Access properties using magic methods.
|
|
Each property returns a `Property` object that
|
|
tracks both the value and whether it exists:
|
|
|
|
```php
|
|
/**
|
|
* Get the property object
|
|
*/
|
|
$firstName = $user->firstName;
|
|
|
|
/**
|
|
* Check property exists and set
|
|
*/
|
|
if ($firstName->exists()) {
|
|
echo $firstName->value(); // Output: John
|
|
}
|
|
```
|
|
|
|
### Working with Property Objects
|
|
|
|
The `Property` class wraps values and tracks their existence:
|
|
|
|
```php
|
|
$property = new \Diffhead\PHP\Dto\Property('1', true);
|
|
|
|
$property->value(); // Returns: '1'
|
|
$property->exists(); // Returns: true
|
|
$property->toInt(); // Returns: 1
|
|
$property->toFloat(); // Returns: 1.0
|
|
$proprety->toBool(); // Returns: true
|
|
$property->toArray(); // Returns: ['1']
|
|
$property->toString(); // Returns: '1'
|
|
|
|
$property = new \Diffhead\PHP\Dto\Property(null, false);
|
|
|
|
$property->value(); // Returns: null
|
|
$property->exists(); // Returns: false
|
|
```
|
|
|
|
### Retrieving Values
|
|
|
|
Get multiple property values at once:
|
|
|
|
```php
|
|
/**
|
|
* Get all properties values
|
|
*
|
|
* output: ['first_name' => 'John', 'lastName' => 'Doe', 'email' => 'john@example.com', 'age' => null]
|
|
*/
|
|
$values = $user->getValues(['first_name', 'lastName', 'email', 'age']);
|
|
|
|
/**
|
|
* Get only existing properties values
|
|
*
|
|
* output: ['first-name' => 'John', 'last.name' => 'Doe', 'email' => 'john@example.com']
|
|
*/
|
|
$values = $user->getValues(['first-name', 'last.name', 'email', 'age'], true);
|
|
```
|
|
|
|
## Property Name Conversion
|
|
|
|
The library automatically handles
|
|
class property name conversion:
|
|
|
|
- **dot.case** (e.g., `first.name`) → **camelCase** (e.g., `firstName`)
|
|
- **kebab-case** (e.g., `first-name`) → **camelCase** (e.g., `firstName`)
|
|
- **snake_case** (e.g., `first_name`) → **camelCase** (e.g., `firstName`)
|
|
|
|
This makes it easy to work with API responses and
|
|
form data that might use different naming conventions.
|
|
|
|
But `Diffhead\PHP\Dto\Dto::getValues` method
|
|
returns raw array keys as they was been passed.
|
|
|
|
## License
|
|
|
|
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
|
|
|