Payload - viames/pair GitHub Wiki

Pair framework: Payload

Pair\Data\Payload is a minimal explicit read model used mainly as a Pair v4 migration bridge.

It wraps an associative array or an ActiveRecord::toArray() result so legacy code can stop relying on implicit raw-object serialization before a proper application read model is written.

For new Pair v4 code, prefer an application-specific readonly ReadModel.

From an array

use Pair\Data\Payload;
use Pair\Http\JsonResponse;

$payload = Payload::fromArray([
	'id' => 7,
	'name' => 'Alice',
	'meta' => ['active' => true],
]);

return new JsonResponse($payload);

Payload implements ReadModel, so JsonResponse normalizes it through toArray().

From an ActiveRecord

use Pair\Data\Payload;

$user = new User(7);
$payload = Payload::fromRecord($user);

return \Pair\Api\ApiResponse::jsonResponse($payload->toArray());

This is explicit, but it still mirrors the persistence array shape. Replace it with a real read model when the API contract is known.

Temporary CRUD bridge

The Pair v4 upgrader may add Payload::class as a conservative fallback when an existing CRUD model has no explicit read contract yet:

use Pair\Api\ApiExposable;
use Pair\Data\Payload;
use Pair\Orm\ActiveRecord;

/**
 * Legacy model exposed during a staged v4 migration.
 */
final class Faq extends ActiveRecord {

	use ApiExposable;

	/**
	 * Return the temporary CRUD API contract.
	 *
	 * @return	array<string, mixed>
	 */
	public static function apiConfig(): array {

		return [
			'readModel' => Payload::class,
		];

	}

}

Treat this as a bridge. The final shape should usually be:

return [
	'readModel' => FaqReadModel::class,
];

Notes

Payload::fromArray() preserves the array as-is.
Payload::fromRecord() delegates to ActiveRecord::toArray().
jsonSerialize() reuses toArray() through ArraySerializableData.
Do not use Payload to hide unclear API contracts; use it to make an incremental migration explicit.