- How do I install and register apie/type-converter in a Laravel application?
- Install it with Composer using composer require apie/type-converter. The package is framework-agnostic and ships no Laravel service provider, so no auto-discovery or config publishing is required; it only needs PHP 8.0 or newer. In most Laravel apps you bind the converter returned by DefaultConvertersFactory::create() as a singleton in a service provider and inject it where mapping happens. That keeps one converter instance available to controllers, actions, and jobs via the container.
- How does the convertTo() method work in apie/type-converter?
- You call convertTo() on a converter instance built by DefaultConvertersFactory::create(), passing the source value and the target type. Scalar conversions are straightforward casts, for example turning the integer 12 into the string '12'. For objects, the converter maps matching constructor parameters and public properties from the source onto the target, so a DTO with public description and name properties fills a domain object that expects those same names.
- Which PHP and Laravel versions does apie/type-converter support?
- The package requires PHP 8.0 or higher and has no framework dependencies beyond PHP core. Because it does not integrate with Laravel internals, it works with Laravel 10 and 11 and any other release running on PHP 8.0+. That also means there is no Laravel-version lock-in to worry about when you upgrade your app.
- How do I map a DTO to a domain object and back again with apie/type-converter?
- Create the converter with DefaultConvertersFactory::create(), then call convertTo($dto, DomainObject::class) to hydrate the domain object from the DTO. The reverse direction works the same way: convertTo($domainObject, Dto::class) produces the DTO by reading the matching getters, constructor arguments, and public properties. Conversion succeeds when the property and parameter names line up on both sides, which keeps your mapping classes small and explicit.
- How do I create a custom converter for apie/type-converter?
- You write your own converter class for the source and target type pair that the default converters cannot handle, then register it with the factory so it takes priority for that pair. The built-in converters remain in place for all other types. This is the recommended way to deal with special formatting rules, value objects, or types that need extra logic during conversion.
- Can apie/type-converter handle nested objects, collections, or deep object graphs?
- The default converters focus on flat mappings between a source object and a target object; deeply nested graphs such as User to Posts to Comments are not converted automatically. For those cases you either write custom converters that recurse into child objects or convert each level explicitly in your service layer. Laravel collections and arrays should also be looped and converted item by item rather than passed in whole.
- Does apie/type-converter validate data during conversion?
- No. The package performs type conversion only and does not enforce business rules, required fields, or value constraints, so invalid data can still be mapped. Validate incoming data first with Laravel's Validator or form requests, then convert the already-validated values. Error handling is also limited, so wrapping conversions in try-catch blocks and throwing your own domain exceptions is a sensible safeguard.
- What is the performance impact of apie/type-converter compared with manual mapping or Laravel API Resources?
- Runtime conversion uses reflection to match properties and constructor parameters, so it is slower than hand-written assignment code. For typical request-level mapping the difference is negligible, but for bulk operations or high-throughput pipelines you should benchmark against manual mapping. Laravel API Resources solve a different problem, producing JSON arrays for responses, whereas this package builds objects, so they often complement each other rather than compete.
- Is apie/type-converter actively maintained, and what are the alternatives?
- It is part of the Apie domain-objects-first suite, but it has relatively few downloads and dependents and no stable major release, so the API can still change. Pin an exact version in composer.json, start with a proof of concept in a non-critical module, and review changelogs before upgrading. Alternatives worth comparing include spatie/array-to-object, Laravel API Resources, or small custom mapper classes if you need a more established dependency.
- How should I test apie/type-converter conversions in a Laravel application?
- Write unit tests that convert a representative DTO into its domain object and assert each property, then test the reverse direction to catch naming mismatches. Add integration tests for the conversion paths that touch persistence or third-party payloads, since coverage of real-world edge cases is not guaranteed. Include tests for invalid or incomplete input so you know exactly which exceptions your try-catch blocks will see.