# Typed metadata

HTML: [altophp.com/frontmatter/metadata](https://altophp.com/frontmatter/metadata/)

`Metadata` is a read-only accessor over the decoded top-level mapping. Values
are typed during decoding, and getters validate rather than broadly coerce them.

| Method | Result |
| --- | --- |
| `get(string $key, $default = null)` | Raw value or the default |
| `all(?string $key = null)` | All values or the nested array at a key |
| `has(string $key)` | Whether a top-level key exists |
| `keys()` | Top-level keys |
| `getString(string $key, ?string $default = null)` | String, with integers and floats converted |
| `getInt(string $key, ?int $default = null)` | Integer |
| `getFloat(string $key, ?float $default = null)` | Float, with integers widened |
| `getBoolean(string $key, ?bool $default = null)` | Boolean |
| `getEnum(string $key, string $class, ?BackedEnum $default = null)` | Backed enum case |
| `getDate(string $key, ?DateTimeImmutable $default = null)` | Parsed date |
| `count()` and `getIterator()` | Collection access |

A missing key returns its default. A present value with the wrong type throws
`UnexpectedTypeError`.

```php
$title = $metadata->getString('title', 'Untitled');
$weight = $metadata->getInt('weight', 0);
$published = $metadata->getDate('published');
```

`getDate()` parses a string only when requested. Dates remain strings during
decoding, leaving calendar semantics under application control.

`getEnum()` accepts a backed enum class and checks both the backing type and
the value:

```php
enum Status: string
{
    case Draft = 'draft';
    case Published = 'published';
}

$status = $metadata->getEnum('status', Status::class, Status::Draft);
```

Access is limited to top-level keys. Use `all('author')` to retrieve a nested
mapping; dot notation is intentionally not supported.

The original block is located by `sourceOffset()` and `sourceLength()`. The
offset is `0`, or `3` after a UTF-8 byte-order mark. A zero length means the
source had no front matter.

---

Previous: [Getting started](https://altophp.com/frontmatter/getting-started.md)
Next: [Decoding](https://altophp.com/frontmatter/decoding.md)

---

ALTO\FRONT MATTER: [altophp.com/frontmatter](https://altophp.com/frontmatter/)
ALTO(PHP): [altophp.com](https://altophp.com/)