Download the PHP package baraja-core/service-method-invoker without Composer

Service Method Invoker

A robust PHP library for safely invoking methods on services with automatic parameter validation, type coercion, and entity hydration. Perfect for API endpoints, command handlers, and any scenario where you need to dynamically call methods with user-provided data.

🎯 Key Features

• Safe method invocation with automatic parameter validation and type checking
• Automatic type coercion for scalar types (bool, int, float, string, array)
• Entity hydration - automatically converts array data to typed objects/DTOs
• PHP 8.1+ enum support with case-insensitive matching
• Nullable parameter handling with proper default value support
• Tracy Debugger integration with custom BlueScreen panels for debugging
• Circular reference detection in nested entity hydration
• Custom entity repository support for resolving entities by ID
• Detailed exception messages with context about the failing service and method

🏗️ Architecture

The package consists of several components working together to provide safe method invocation:

🔧 Components

📦 Installation

It's best to use Composer for installation, and you can also find the package on Packagist and GitHub.

To install, simply use the command:

You can use the package manually by creating an instance of the internal classes, or register a DIC extension to link the services directly to the Nette Framework.

Requirements: PHP 8.1 or higher

🚀 Basic Usage

Simple Method Invocation

Think of a simple service as an API endpoint with a public method for hydrating your data:

And your endpoint can be:

Getting Invoke Arguments Without Execution

If you need to prepare the arguments without actually invoking the method:

🎭 Type Coercion

The invoker automatically handles type conversion based on method parameter types:

Scalar Types

Nullable Parameters

When a parameter is nullable and receives an empty or falsy value, it's converted to null:

Boolean Conversion

The following string values are treated as true: "1", "true", "yes" (case-insensitive). All other values are converted to false.

📊 Entity Hydration

One of the most powerful features is automatic entity/DTO hydration from array data:

Simple Entity

Nested Entities

The invoker supports nested entity hydration:

Property Hydration via Setters

If an entity has setter methods, they will be used for hydration:

Circular Reference Detection

The invoker detects and prevents circular references in entity hydration:

🔢 PHP 8.1+ Enum Support

The invoker fully supports PHP enums with case-insensitive matching:

If an invalid enum value is provided, a helpful error message is shown:

🔍 Custom Entity Repository

For integrating with ORMs like Doctrine, implement the ProjectEntityRepository interface:

This allows automatic entity resolution from IDs:

📑 The Data Parameter

When dataMustBeArray is true, a parameter named data must be typed as array and will receive all input parameters:

🐛 Tracy Debugger Integration

When Tracy Debugger is available, the package automatically registers a custom BlueScreen panel that provides:

• Service class name and the exact method being called
• Source code highlighting of the failing method
• Input parameters table showing all passed values
• Direct editor link to open the file at the exact line

This integration is automatic when Tracy is installed - no configuration needed.

⚠️ Exception Handling

The RuntimeInvokeException provides rich context for debugging:

Common Exceptions

🎨 Service Interface

Implement the Service interface on your services for better error messages:

📋 DateTime Handling

DateTimeInterface implementations are automatically instantiated:

🔒 Default Values for Empty Inputs

When a non-nullable parameter receives an empty value, appropriate defaults are used:

👤 Author

Jan Barasek - https://baraja.cz

📄 License

baraja-core/service-method-invoker is licensed under the MIT license. See the LICENSE file for more details.