README

Standard attributes for documenting types in PHP.

Overview

Typedocs provides a set of PHP attributes that allow you to add human-readable documentation directly to your custom types. These attributes can be reflected at runtime to generate documentation, validate schemas, or provide metadata for API documentation.

Installation

composer require foundation/typedocs

Available Attributes

#[Name]

A human-readable name for the type.

#[Example]

Example(s) of valid value(s) for the type.

#[Description]

A detailed description of what the type represents.

Usage

<?php

use Fasano\Typedocs as Doc;
use Fasano\PHPrimitives\AbstractString;

#[Doc\Name('Email')]
#[Doc\Example('john.doe@example.com')]
#[Doc\Description('The user\'s email address.')]
readonly class UserEmail extends AbstractString
{
    protected static function validate(string $value): void
    {
        if (!filter_var($value, FILTER_VALIDATE_EMAIL)) {
            throw new InvalidArgumentException(
                sprintf('Invalid email: %s', $value)
            );
        }
    }
}

Reading Attributes

Use PHP's reflection API to read the documentation attributes:

<?php

use ReflectionClass;
use Fasano\Typedocs\Name;
use Fasano\Typedocs\Example;
use Fasano\Typedocs\Description;

$reflection = new ReflectionClass(UserEmail::class);

$name = $reflection->getAttributes(Name::class)[0]->newInstance();
$example = $reflection->getAttributes(Example::class)[0]->newInstance();
$description = $reflection->getAttributes(Description::class)[0]->newInstance();

echo $name->value;        // "Email"
echo $example->value;     // "john.doe@example.com"
echo $description->value; // "The user's email address."