Download the PHP package holiq/action-data without Composer

Laravel Action Data

A Laravel package that provides an elegant way to generate and use Actions and Data Transfer Objects (DTOs) in your Laravel projects. This package promotes clean architecture by separating business logic into reusable Action classes and ensuring type-safe data handling with DTOs.

Table of Contents

• Features
• Requirements
• Installation
• Quick Start
• Usage
  • Generating Actions
  • Generating DTOs
  • Working with DTOs
  • Validation
  • Nested DTOs
  • Data Transformations
• Real-world Examples
• API Reference
• Testing
• Contributing
• License

Features

• 🚀 Simple Command Generation: Generate Actions and DTOs with simple Artisan commands
• 🔒 Type Safety: Built with PHP 8.3+ readonly classes for immutable data structures
• 🏗️ Clean Architecture: Promotes separation of concerns and clean code practices
• 🔄 Automatic Data Mapping: Seamless conversion between arrays, Form Requests, and Models
• ✅ Attribute-Based Validation: Use PHP attributes for declarative validation rules
• 🔧 Custom Validation: Support for custom validation callbacks and pipelines
• 🌳 Nested DTOs: Automatic resolution of nested DTOs and arrays of DTOs
• 🔄 Data Transformations: Built-in data transformation pipeline for clean data processing
• 📁 Customizable Paths: Configure custom paths for Actions and DTOs
• 🧪 Well Tested: Comprehensive test suite ensuring reliability
• 📖 Rich Documentation: Extensive documentation and examples

Requirements

• PHP 8.3 or higher
• Laravel 12.0 or 13.0

Installation

You can install the package via Composer:

The package will automatically register its service provider.

Optionally, you can publish the configuration file:

After publishing, you can customize the paths in config/action-data.php:

Quick Start

1. Generate an Action with DTO:

2. Define your DTO with validation:

3. Implement your Action:

4. Use in your controller:

Configuration

After publishing the configuration file, you can customize the paths where Actions and DTOs are generated:

Usage

Generating Actions

Generate Actions using the Artisan command with various options:

Basic Action structure:

Action with DTO parameter:

Generating DTOs

Generate DTOs using the Artisan command:

Generated DTO structure:

Working with DTOs

Creating and Resolving DTOs

DTOs can be created from various data sources:

Array Conversion

Convert DTOs to arrays with different formatting options:

Property Exclusion

Control which properties are included in specific contexts:

Validation

Laravel Action Data provides powerful validation through PHP attributes and custom callbacks.

Attribute-Based Validation

Use PHP attributes for declarative validation rules:

Available validation attributes:

• #[Required] - Field cannot be null, empty string, or empty array
• #[Email] - Validates email format
• #[Length(min: int, max: int)] - Validates string length
• #[Range(min: int|float, max: int|float)] - Validates numeric ranges
• #[Pattern(regex: string)] - Validates against regular expression

Custom Validation Callbacks

Use custom validation logic with chainable callbacks:

Custom Validation Attributes

You can create your own PHP attributes by implementing Holiq\ActionData\Contracts\Validator:

Nested DTOs

Laravel Action Data automatically resolves nested DTOs and arrays of DTOs:

Simple Nested DTOs

Arrays of DTOs

Data Transformations

Apply automatic data transformations during DTO resolution to clean and format your data:

Complex transformations example:

Real-world Examples

Complete User Management with Validation

When validation fails, Laravel will automatically convert the ValidationException to a standard 422 Unprocessable Entity response.

Nested DTOs Example: Order Management

Advanced Example with Service Dependencies

API Reference

Action Class

resolve(array $parameters = []): static

Resolves an Action instance from Laravel's container with optional parameters.

DataTransferObject Class

Core Methods

resolve(array $data): static
Creates a DTO instance from an array with automatic key transformation and data transformations.

resolveFrom(FormRequest|Model|array $abstract): static
Creates a DTO instance from various data sources.

Array Conversion

toArray(): array - Converts to snake_case array
toCamelCase(): array - Converts to camelCase array
toArrayForCreate(): array - Excludes properties from toExcludedPropertiesOnCreate()
toArrayForUpdate(): array - Excludes properties from toExcludedPropertiesOnUpdate()
toJson(int $options = 0): string - Converts to JSON string toCamelJson(int $options = 0): string - Converts to camelCase JSON string

Validation

validate(callable $validator, string $message): static
Validates using a custom callback.

validateAttributes(): static
Validates using PHP attributes.

Property Access

has(string $property): bool - Checks if property exists
get(string $property, mixed $default = null): mixed - Gets property value

Immutable Update Helpers

with(mixed ...$values): static - Returns a cloned DTO with named-argument overrides
withArray(array $overrides): static - Returns a cloned DTO with snake_case/camelCase key overrides
without(string ...$properties): static - Returns a cloned DTO with nullable properties set to null

Utility Methods

clone(): static - Creates a clone
tap(callable $callback): static - Executes callback and returns instance
dump(): static - Dumps data for debugging
dd(): never - Dumps data and dies

Protected Methods (Override in your DTOs)

toExcludedPropertiesOnCreate(): array - Properties to exclude in create context
toExcludedPropertiesOnUpdate(): array - Properties to exclude in update context
transforms(): array - Data transformations for resolve()

Artisan Commands

make:action [name]

Generates a new Action class.

Options:

• --with-dto=DtoName - Auto-generate corresponding DTO
• --force - Overwrite existing files

make:dto [name]

Generates a new Data Transfer Object class.

Options:

• --force - Overwrite existing files

Testing

Run the test suite:

Run static analysis:

Run code formatting:

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

The MIT License (MIT). Please see License File for more information.