Usage guide
This guide is written as a series of short chapters. Each one answers a single question and builds on the one before it, so the fastest way through is simply top to bottom. By the end you'll have a typed JSON column working on a real Eloquent model, and you'll know every part of the package.
If you only have a minute, read Chapter 1 and Chapter 4 — that's the whole loop: define a shape, cast it on a model.
The chapters
- Define a shape — How do I describe the structure of a JSON column?
- Read values — How do I get typed values out of a shape?
- Write values — How do I change values and keep them typed?
- Cast it on a model — How do I use a shape as an Eloquent attribute?
- Create & combine shapes — How do I build shapes by hand, in tests and jobs?
- Type safety in depth — What does static analysis actually catch for me?
- Helpers, macros & errors — What else does a shape give me out of the box?
The running example
Every chapter uses one example: a TraceShape that models a structured log trace stored in a JSON column. It's deliberately realistic — it has required fields, an optional one, a nullable one, an enum, and a nested object — so each feature has somewhere to land. You'll define it in Chapter 1 and reuse it everywhere after.
Ready? Start with Chapter 1 →