A Laravel library for creating and managing Data Transfer Objects (DTOs) with validation and an Artisan command for easy DTO generation.
- DTO Class: A base class for creating DTOs with validation.
- Artisan Command: A command to easily generate new DTO classes.
To install the library, add it to your composer.json file or run the following command:
composer require afonsoogomes/laravel-dtoTo create a new DTO class, use the provided Artisan command:
php artisan make:dto {name}Replace {name} with the desired name for your DTO class. The command will generate a new DTO class in the app/DTO directory.
Here's an example of how to use the DTO class:
namespace App\DTO;
use AfonsoOGomes\LaravelDTO\DTO;
class UserDTO extends DTO
{
/**
* @var string
*/
public $name;
/**
* @var string
*/
public $email;
protected function rules(): array
{
return [
'name' => ['required', 'string', 'max:255'],
'email' => ['required', 'email'],
];
}
}You can create an instance of the DTO and access its properties like so:
$userDTO = UserDTO::make([
'name' => 'John Doe',
'email' => '[email protected]',
]);
echo $userDTO->name; // John DoeThe defaults method allows you to define default values for the DTO fields. Here's an example:
namespace App\DTO;
use AfonsoOGomes\LaravelDTO\DTO;
class ProductDTO extends DTO
{
/**
* @var string
*/
public $name;
/**
* @var float
*/
public $price;
/**
* @var integer
*/
public $stock;
protected function rules(): array
{
return [
'name' => ['required', 'string', 'max:255'],
'price' => ['required', 'numeric'],
'stock' => ['required', 'integer'],
];
}
protected function defaults(): array
{
return [
'stock' => 0, // Default stock value
];
}
}
// Using the DTO with default values
$data = [
'name' => 'Product Name',
'price' => 19.99,
];
$productDTO = ProductDTO::make($data);
echo $productDTO->name; // Product Name
echo $productDTO->price; // 19.99
echo $productDTO->stock; // 0 (default value)The transform method allows you to process data before validation. For example, to clean up a phone number:
namespace App\DTO;
use AfonsoOGomes\LaravelDTO\DTO;
class UserDTO extends DTO
{
/**
* @var string
*/
public $name;
/**
* @var string
*/
public $email;
/**
* @var string
*/
public $phone;
protected function rules(): array
{
return [
'name' => ['required', 'string', 'max:255'],
'email' => ['required', 'email'],
'phone' => ['required', 'string', 'size:10'], // Example: must be 10 digits
];
}
protected function transform(): array
{
return [
'phone' => preg_replace('/\D/', '', $this->phone) // Remove non-numeric characters from phone
];
}
}
// Using the DTO with data transformation
$data = [
'name' => 'John Doe',
'email' => '[email protected]',
'phone' => '(123) 456-7890', // Original format
];
$userDTO = UserDTO::make($data);
echo $userDTO->name; // John Doe
echo $userDTO->email; // [email protected]
echo $userDTO->phone; // 1234567890 (transformed to 10 digits)Here is an example that uses both defaults and transform:
namespace App\DTO;
use AfonsoOGomes\LaravelDTO\DTO;
class OrderDTO extends DTO
{
/**
* @var string
*/
public $order_id;
/**
* @var float
*/
public $amount;
/**
* @var string
*/
public $currency;
protected function rules(): array
{
return [
'order_id' => ['required', 'string'],
'amount' => ['required', 'numeric'],
'currency' => ['required', 'string', 'size:3'], // Example: 3-letter currency code
];
}
protected function defaults(): array
{
return [
'currency' => 'USD', // Default currency value
];
}
protected function transform(): array
{
return [
'order_id' => strtoupper($this->order_id), // Transform order ID to uppercase
];
}
}
// Using the DTO with default values and data transformation
$data = [
'order_id' => 'abc123',
'amount' => 99.99,
];
$orderDTO = OrderDTO::make($data);
echo $orderDTO->order_id; // ABC123 (transformed to uppercase)
echo $orderDTO->amount; // 99.99
echo $orderDTO->currency; // USD (default value)The whitelist parameter allows you to restrict the DTO to only accept properties that are explicitly defined in the class. When set to true, any properties in the input data that are not defined as class properties will be ignored. Here's an example:
namespace App\DTO;
use AfonsoOGomes\LaravelDTO\DTO;
class OrderDTO extends DTO
{
/**
* @var string
*/
public $order_id;
/**
* @var float
*/
public $amount;
/**
* @var string
*/
public $currency;
protected function rules(): array
{
return [
'order_id' => ['required', 'string'],
'amount' => ['required', 'numeric'],
'currency' => ['required', 'string', 'size:3'], // Example: 3-letter currency code
];
}
protected function defaults(): array
{
return [
'currency' => 'USD', // Default currency value
];
}
protected function transform(): array
{
return [
'order_id' => strtoupper($this->order_id), // Transform order ID to uppercase
];
}
}
// Using the DTO with default values and data transformation
$data = [
'order_id' => 'abc123',
'amount' => 99.99,
'unknown_field' => 'this will be ignored'
];
// Whitelist is set to true as the second parameter
$orderDTO = OrderDTO::make($data, true);
// Only defined properties are set
echo $orderDTO->order_id; // abc123
echo $orderDTO->amount; // 99.99
echo $orderDTO->unknown_field; // undefinedname: The name of the DTO class to be created. You can use forward slashes to create nested directories.
Example:
php artisan make:dto UserProfileDTOThis will create a UserProfileDTO.php file in the app/DTO directory.
The DTO constructor accepts the following parameter:
array $items: The initial data for the DTO.
__construct(array $items = []): Constructor to initialize the DTO with data and perform validation.rules(): Method to define validation rules for the DTO. Override this method in your DTO classes.messages(): Get the validation error messages for the DTO.transform(): Method to preprocess the data before validation.defaults(): Method to define default values for the DTO.get($key, $default = null): Method to get a value from the DTO by key.only(array $keys): * Get only the specified keys from the collection.except(array $keys): Method to get all items in the collection except for those with the specified keys..all(): Method to get all the data in the DTO.has(string $key): Method to check if a key exists in the DTO.set(string $key, $value): Method to set a value in the DTO by key.remove(string $key): Method to remove a value from the DTO by key.count(): Method to count the number of items in the DTO.toArray(): Method to convert the DTO to an array.toJson(): Method to convert the DTO to a JSON string.make(array $data): Static method to create a new DTO instance from an array.
To test the library, make sure you have Laravel installed and configured. Create a new DTO class using the Artisan command and verify that it works as expected.
If you would like to contribute to the library, please submit a pull request on GitHub. Ensure that you follow the coding standards and include tests for new features.
This library is licensed under the MIT License. See the LICENSE file for more information.