Data Laravel Package

Getting Started

1. Install with composer require psx/data and immediately check the installed version and PHP constraint with composer show psx/data.
2. Read these first, in order:
   • README.md for the supported reader/writer/processor flow.
   • src/ for the actual interfaces and concrete reader/writer classes.
   • tests/ for working payload-to-POPO examples, especially nested objects, arrays, dates, and null handling.
3. Treat the package as a boundary mapper, not a replacement for Laravel validation, Eloquent, or API Resources.
4. First useful use case: accept a JSON request body, map it into a typed DTO/POPO, validate/process it in application code, then serialize a POPO response.

Typical first endpoint shape:

use PSX\Data\Reader\Json as JsonReader;
use PSX\Data\Writer\Json as JsonWriter;

$reader = new JsonReader();
$writer = new JsonWriter();

$payload = $reader->read($request->getContent());

// The processor class/API varies by version; verify against vendor/psx/data/src.
$dto = $processor->process($payload, CreateOrder::class);

return response(
    $writer->write($dto),
    200,
    ['Content-Type' => 'application/json']
);

If the processor constructor has dependencies, bind it in a Laravel service provider rather than constructing it ad hoc in controllers. Keep the first integration small: one DTO, one reader, one writer, one round-trip test.

Implementation Patterns

• DTO-first mapping. Define POPOs with public typed properties or clear docblocks. Keep them separate from Eloquent models so serialization concerns do not leak into persistence.
• Reader/writer factory by content type. Resolve a reader from Content-Type and a writer from Accept/route suffix. This is where psx/data is most useful: JSON, XML, CSV, or other formats feeding the same POPO layer.
• Controller boundary pattern.
  1. Read raw request body.
  2. Map to DTO with the package processor.
  3. Validate the DTO or its array form with Laravel’s validator.
  4. Pass the DTO to an action/service.
  5. Map a response DTO back through the writer.
• Service provider bindings. Register readers, writers, and the processor as container bindings. Prefer named bindings/contexts for formats rather than a single global processor with conditional logic everywhere.
• Import/export jobs. Process rows or records one at a time, catch per-record mapping errors, and collect structured errors. For large exports, keep package serialization per chunk and stream the response outside the package.
• Round-trip tests. For every DTO used at an API boundary, test read -> process -> write and write -> read fixtures. Include nested objects, arrays of objects, empty arrays, null, missing fields, and date/time values.
• Do not serialize Eloquent models directly. Map models to explicit response POPOs. This avoids lazy-loading surprises, hidden attributes, and tight coupling to database structure.
• Extension points to prefer. Use custom readers/writers for formats the package does not cover, and custom visitors/type handlers for dates, enums, money, or identifiers. Wrap these behind application interfaces so the package can be replaced later.
• Format negotiation example. A route can choose JsonReader/JsonWriter, XmlReader/XmlWriter, or a CSV writer based on request headers. Unknown formats should return 406 Not Acceptable, not fall through to an accidental default.

Gotchas and Tips

• Low adoption risk. With very few stars and no dependents, expect sparse examples and possible version-specific API differences. Pin the version in composer.json and isolate usage behind a small adapter layer.
• Verify class names in src/. The package’s processor/reader/writer names and constructor signatures may differ from examples found online. Use composer show psx/data, inspect vendor/psx/data/src, and follow the tests rather than guessing.
• Reflection/metadata performance. POPO mapping often relies on reflection or metadata. If you map many objects per request, check whether metadata caching is available and enabled; otherwise benchmark before using it in hot paths.
• Type coercion is not validation. A mapper may convert "1" to 1 or turn missing values into null. Validate required fields and ranges explicitly before business logic.
• Null vs missing vs empty. Test these separately. A missing key, an explicit null, an empty array, and an empty string often take different paths in mapping and serialization.
• Nested objects and collections. Confirm how the installed version represents collections and nested POPOs. Add fixtures for arrays of objects and recursive structures; watch for circular references.
• XML and CSV security. For XML input, ensure external entity expansion is disabled or not supported. For CSV export, guard against spreadsheet formula injection by sanitizing cells beginning with =, +, -, or @.
• Laravel exception handling. Catch package mapping exceptions and convert them into 422 validation-style responses. Do not let raw serialization errors become 500 responses or leak internal class names.
• Response handling. Writer output is usually a string. Return it through Laravel’s response() with the correct Content-Type; do not echo it directly from a controller or middleware.
• Composer conflicts. Check the package’s PSR/Symfony dependency constraints against your Laravel version. Because the package is niche, dependency conflicts are more likely than with first-party Laravel packages.
• Debugging order. Log the raw payload, then the reader output, then the processor input, then the final DTO. Most issues are at the boundary between raw array/object structures and POPO metadata.
• Keep an exit path. Put psx/data behind an application-level PayloadMapper interface. If the package becomes unmaintained or conflicts with a future Laravel/Symfony upgrade, you can swap in Symfony Serializer or manual mapping without rewriting controllers.