omnidocs / php
Omnidocs PHP: a PHP package's API reference, read from its sources - its namespaces, classes, interfaces, traits and enums, their public constants, properties and methods with their signatures and PHPDoc, and the options its factories' configuration takes - as an omnidocs manual (nikic/php-parser, p
Requires
- php: >=8.2
- nikic/php-parser: ^5.0
- omnisense/omnidocs: ^1.0
- phpdocumentor/reflection-docblock: ^5.4
Requires (Dev)
- omnisense/contracts: ^1.0
- phpunit/phpunit: ^11.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
A PHP package's API reference, read from its sources - never loaded, never run - as an
omnidocs manual: a home that lists every namespace and
its classes (a card per class: its kind, what it is, what it holds counted), then a page per namespace, each class with its declaration (final class Registry implements Drives), its PHPDoc, the options of its configuration (a factory's ->defaults([...])
keys and defaults, the ones it requires), its public constants, enum cases, properties (promoted ones
included) and methods - signature, text, parameters, return, exceptions - each at its anchor, each an
API entry the search finds, each linked to its line in the repository.
It stands on what exists: nikic/php-parser reads the files,
phpdocumentor/reflection-docblock the PHPDoc.
What is @internal, private or protected, or under Tests, vendor, docker, docs, is left out.
Installation and a first use
composer require omnidocs/php
It needs PHP 8.2 and no outside tool: the sources are parsed, never loaded nor run; no network, no account. A first reference, of omnisense/omnidocs itself, installed with it:
require __DIR__.'/vendor/autoload.php'; use Omnidocs\Model\Version; use Omnidocs\Php\PhpSourceFactory; $source = (new PhpSourceFactory())->create(['root' => __DIR__.'/vendor/omnisense/omnidocs', 'title' => 'API reference']); $version = new Version('1.x', $source); foreach ($version->pages() as $node) { echo $node->title, "\n"; } echo count($version->symbols()), " API entries\n";
Its tests (composer install then vendor/bin/phpunit in a checkout, or every package at once in
omnidocs' Docker harness)
read omnisense/omnidocs' own sources; nothing else is needed.
The options:
$api = (new Omnidocs\Php\PhpSourceFactory())->create(['root' => 'vendor/omnisense/omnidrive', 'title' => 'API reference']);
| Option | Default | Meaning |
|---|---|---|
root |
(required) | the package's folder |
title |
API reference |
the reference's title |
repository |
"" |
what root is in the repository: the links to the source |
exclude |
Tests, tests, vendor, docker, node_modules, var, docs | folder or file names left out |
labels |
English | the callouts' words |
Verified, and not
- Verified (omnidocs' harness, PHP 8.4): omnidocs' conformance suite on omnisense/omnidocs' own
sources (its classes, PHPDoc, promoted properties, the options of its "array" factory);
BareTest. - Verified in use: the Omnisense site's API reference of each of its 150 PHP packages (omnibase 4.x, the families, their providers), read at the commit each manual is pinned to.
- Not verified: options given otherwise than in an array literal (a constant, a method call); attributes
(
#[...]) are not shown; a package with two classes of the same name in one namespace (one wins).
Licence: MIT.