Download the PHP package brahmic/clientdto without Composer

ClientDTO

What does it do?

• ✅ Integration with external API
• ✅ Error and state handling, always predictable response
• ✅ Request grouping
• ✅ Working with files and archives
• ✅ Support for queries with pagination
• ✅ Additional query attempts with flexible configuration
• ✅ HTTP Request Caching - intelligent caching with RAW/DTO modes
• ✅ Simplifies working with API

Using examples

Custom client example

Resource example

Request example

File Request example

Resolved Data Handlers

ClientDTO allows you to register handlers that process resolved data after DTO creation. This provides a flexible way to modify or enhance response data before it's returned to the user.

Basic Usage

Handler Types

Function Handlers:

Class Handlers:

Caching Behavior

Resolved handlers work intelligently with ClientDTO's caching system:

RAW Cache Mode (requestCacheRaw(true)):

• Handlers execute every time data is accessed (even from cache)
• Raw HTTP response is cached, DTO is rebuilt each time
• Handlers always have fresh context

DTO Cache Mode (default):

• Handlers execute once before caching
• Processed DTO is cached with handler modifications
• Subsequent cache hits return pre-processed data

Handler Parameters

All handlers receive two parameters:

Benefits of Request Object Access

Passing the original request object to handlers provides several key advantages:

1. Conditional Processing Based on Request Type:

2. Access to Request Parameters:

3. Context-Aware Data Enhancement:

4. Request-Specific Validation:

Use Cases

Data Enhancement:

Conditional Processing:

Debug Information:

Human-Readable Labels for DTO Fields

ClientDTO provides automatic transformation of DTO fields into human-readable labeled format, perfect for frontend display and API responses.

Basic Usage

Add labels to DTO properties and enable automatic transformation:

Automatic Transformation

With #[WithLabels(autoTransform: true)], all labeled fields are automatically transformed when converting DTO to array:

Manual Labeled Access

Get labeled data without automatic transformation:

Working with Existing Transformers

Label functionality respects existing #[WithTransformer] attributes:

Frontend Integration Examples

Vue.js Template:

React Component:

Performance and Caching

Label functionality includes intelligent caching for optimal performance:

• Reflection caching - Class and property metadata cached automatically
• Production optimization - Full caching in production environment
• Development friendly - Automatic cache clearing in testing
• Process-scoped - Cache lives for request lifecycle

Cache Management

For rare edge cases, manual cache clearing is available:

Use Cases

API Responses:

Form Generation:

Data Tables:

Property-level WithLabels (Composite DTOs)

For complex DTOs containing other DTOs, you can control labeling behavior at the property level using #[WithLabels] attributes:

Result:

Priority System:

1. Property-level #[WithLabels] on parent DTO properties (HIGHEST priority)
2. Class-level #[WithLabels] on child DTO classes
3. Default behavior (no labels)

Key Features:

• Hierarchical control: Parent DTOs control how their child DTOs are transformed
• Automatic inheritance: Child DTOs inherit context from their parents
• Override capability: Property-level settings always override class-level settings
• Zero boilerplate: Just add attributes, no additional code needed

⚠️ Thread Safety Note: Property-level WithLabels uses static context and is not thread-safe in async PHP environments (Swoole, ReactPHP).

GroupedRequest - Composite API Calls

ClientDTO provides GroupedRequest functionality to combine multiple API calls into a single logical operation. This is useful when you need data from multiple endpoints to build a complete picture.

Basic GroupedRequest

Composite DTO Structure

Advanced: Data Processing with handle()

For cases where you need to process the collected data before creating the final DTO, use the handle() method:

Analytics DTO

Execution Flow

Standard GroupedRequest:

1. Execute child requests → HouseInfoDto + HousePassportDto
2. Collect data into composite DTO → HouseCompleteInfoDto
3. Return result → HouseCompleteInfoDto

GroupedRequest with handle():

1. Execute child requests → HouseInfoDto + HousePassportDto
2. Collect into intermediate DTO → HouseCompleteInfoDto
3. Call handle() method → Process intermediate data, return array
4. Create final DTO → HouseAnalyticsDto::from(array)
5. Return result → HouseAnalyticsDto

Usage Examples

Key Features

• No URI required - Virtual request that doesn't hit a single endpoint
• Automatic parameter passing - Public properties are passed to child requests
• Structured results - $groupedWithKeys = true creates properly keyed DTOs
• Data processing - Optional handle() method for custom data transformation
• Type safety - Full IDE support and type hints throughout the process

⚠️ Performance Note: GroupedRequest executes multiple HTTP requests. Consider API rate limits and use caching when appropriate.

HTTP Request Caching

ClientDTO provides intelligent HTTP request caching with support for both RAW and DTO modes.

Basic Configuration

Caching Methods

Caching Modes

DTO Caching (default):

• Caches resolved DTO objects
• Smaller memory footprint
• Faster access to structured data

RAW Caching:

• Caches original HTTP response body
• Preserves exact server response
• Useful for debugging or when raw data is needed

Per-Request Control

Use the #[Cacheable] attribute to control caching for specific requests:

Cache Behavior

Default Behavior:

• GET requests: Cached if requestCache() is enabled
• POST requests: Not cached unless postIdempotent() is called
• Cache keys include request class, method, URL, and parameters
• RAW and DTO caches are separate (different cache keys)

Priority Order:

1. #[Cacheable] attribute on request class
2. postIdempotent() setting for POST requests
3. Global requestCache() setting

Cache Management