xlient / doc-php
A PHP library for generating markdown files from PHPDoc comments and reflection.
Requires
- phpstan/phpdoc-parser: ^1.16
Requires (Dev)
- phpstan/phpstan: ^1.10
This package is auto-updated.
Last update: 2024-04-07 04:49:27 UTC
README
This library is a PHP documentor used to generate documentation files for your PHP code in GitHub compatible Markdown.
Requires PHP 8.1 or higher.
Install
composer require xlient/doc-php
Setup
Any php files you wish to generate documents for must be already loaded or autoloadable.
It is recommended to install them with composer and then point the srcDir parameter to your package folder in /vendor.
use Xlient\Doc\Php\Configuration; use Xlient\Doc\Php\PhpDocumentor; use const DIRECTORY_SEPARATOR as DS; // Set current working directory to composer.json directory. chdir(dirname(__DIR__)); // Include composer autoload file. require_once getcwd() . DS . 'vendor' . DS . 'autoload.php'; // Configure the documentor. $config = new Configuration(...); // Instanciate the documentor. $documentor = new PhpDocumentor( srcDirs: [ getcwd() . '/vendor/package/name1/src', getcwd() . '/vendor/package/name2/src', ], destDir: getcwd() . '/docs', config: $config, ); // Generate the documentation files. $files = $documentor->make();
Configuration
All configuration is set using the Configuration class.
The parameter order of the Configuration class __construct method is not guaranteed to remain consistent between versions. For this reason it is recommended to use named parameters.
$config = new Configuration( baseNamespaces: [ '\\Xlient' ], basePaths [ '\\Xlient' => 'xlient' ], ... );
baseNamespaces
Only files within these namespaces will be documented.
When creating directories, the equivalent directory path of this namespace will be trimmed from the start of the path.
Default
baseNamespace: [],
Example
baseNamespace: [
'\\Xlient'
],
With baseNamespace: ['\\Xlient'], the resulting directory path of \\Xlient\\Doc\\Php will become /doc/php.
basePaths
These paths will be prepended to the start of any resulting relative documentation file path.
The array key is the namespace and the value the corresponding path.
Default
basePaths: [],
Example
basePaths: [
'\\Xlient' => '/help'
],
With basePaths: ['\\Xlient' => '/help'], the resulting path of \\Xlient\\Doc\\Php\Configuration will become {destDir}/help/doc/php/configuration.md
baseUrls
This URL will be prepended to any URL paths generated for items that match a base namespace.
The array key is the namespace to match and the value the corresponding URL.
Default
baseUrls: [],
Example
baseUrls: [
'\\Xlient' => 'https://xlient.com'
],
pathFixes
An array of key value pairs to override the default path name generation.
By default, namespaces will be broken up based on case. So MyName will become my-name.
This isn't always the desirable outcome, so this option allows you to modify the namespace value to an alternative.
Default
pathFixes: [],
Example
pathFixes: [
'MyName' => 'myname'
],
namespaceUrls
An array of URLs to use for linking to items outside the base namespaces.
{php_doc} will get replaced with a php.net style document path.
With \\Random\\Engine\\Secure, the resulting filename will be class.random-engine-secure.php
Default
namespaceUrls: [
'\\' => 'https://www.php.net/manual/en/{php_doc}',
'\\Random\\' => 'https://www.php.net/manual/en/{php_doc}',
'\\Psr\\' => 'https://www.php-fig.org',
'\\Psr\\Cache\\' => 'https://www.php-fig.org/psr/psr-6',
'\\Psr\\Clock\\' => 'https://www.php-fig.org/psr/psr-20',
'\\Psr\\Container\\' => 'https://www.php-fig.org/psr/psr-11',
'\\Psr\\EventDispatcher\\' => 'https://www.php-fig.org/psr/psr-14',
'\\Psr\\Http\\Client\\' => 'https://www.php-fig.org/psr/psr-18',
'\\Psr\\Http\\Message\\RequestFactoryInterface' => 'https://www.php-fig.org/psr/psr-17',
'\\Psr\\Http\\Message\\ResponseFactoryInterface' => 'https://www.php-fig.org/psr/psr-17',
'\\Psr\\Http\\Message\\ServerRequestFactoryInterface' => 'https://www.php-fig.org/psr/psr-17',
'\\Psr\\Http\\Message\\StreamFactoryInterface' => 'https://www.php-fig.org/psr/psr-17',
'\\Psr\\Http\\Message\\UploadedFileFactoryInterface' => 'https://www.php-fig.org/psr/psr-17',
'\\Psr\\Http\\Message\\UriFactoryInterface' => 'https://www.php-fig.org/psr/psr-17',
'\\Psr\\Http\\Message\\' => 'https://www.php-fig.org/psr/psr-7',
'\\Psr\\Http\\Server\\' => 'https://www.php-fig.org/psr/psr-15',
'\\Psr\\Link\\' => 'https://www.php-fig.org/psr/psr-13',
'\\Psr\\Log\\' => 'https://www.php-fig.org/psr/psr-3',
'\\Psr\\SimpleCache\\' => 'https://www.php-fig.org/psr/psr-16',
],
Any namespaceUrls set in the configuration will be merged with the default.
urlCallback
A more precise method of providing external URLs.
Default
urlCallback: null,
Example
$url will contain the any matching namespaceUrls value or null if no matches.
urlCallback: function(string $name, ?string $url): ?string { if (str_starts_with($name, '\\Psr\\')) { $url = 'https://www.php-fig.org'; } return $url; },
methodUrlCallback
A method of providing external URLs for external class methods.
Default
methodUrlCallback: null,
Example
methodUrlCallback: function(string $class, string $method): ?string { $url = null; // ... return $url; },
classPublic
When true, public class items will be included.
Default
classPublic: true,
classProtected
When true protected class items will be included.
Default
classProtected: true,
classPrivate
When true private class items will be included.
Default
classPrivate: true,
classSeparator
A string value to use to separate class names in the inheritance list.
Default
classSeparator: ' » ',
methodFiles
When true, separate files will be generated for each class method.
Default
methodFiles: true,
functionFiles
When true, separate files will be generated for each function.
functionFiles: true,
functionDir
When true, function files will be placed in a sub directory with the same name as the functions file.
functionDir: true,
classFilenamePrefix
A value to prepend to a class documentation filename.
Default
classFilenamePrefix: '',
Example
classFilenamePrefix: 'class-',
classFilenameSuffix
A value to append to a class documentation filename.
Default
classFilenameSuffix : '',
enumFilenamePrefix
A value to prepend to an enum documentation filename.
Default
enumFilenamePrefix : '',
enumFilenameSuffix
A value to append to an enum documentation filename.
Default
enumFilenameSuffix : '',
interfaceFilenamePrefix
A value to prepend to an interface documentation filename.
Default
interfaceFilenamePrefix : '',
interfaceFilenameSuffix
A value to append to an interface documentation filename.
Default
interfaceFilenameSuffix : '',
traitFilenamePrefix
A value to prepend to a trait documentation filename.
Default
traitFilenamePrefix : '',
traitFilenameSuffix
A value to append to a trait documentation filename.
Default
traitFilenameSuffix : '',
methodFilenamePrefix
A value to prepend to a method documentation filename.
Default
methodFilenamePrefix : '',
methodFilenameSuffix
A value to append to a method documentation filename.
Default
methodFilenameSuffix : '',
functionFilenamePrefix
A value to prepend to a function documentation filename.
Default
functionFilenamePrefix : '',
functionFilenameSuffix
A value to append to a function documentation filename.
Default
functionFilenameSuffix : '',
constantsFilename
The filename to use for a constants documentation file.
Default
constantsFilename : 'constants',
functionsFilename
The filename to use for a functions documentation file.
Default
functionsFilename : 'functions',
classPathPrefix
A value to prepend to a class documentation dirname.
Default
classPathPrefix: '',
Example
classPathPrefix: 'class-',
classPathSuffix
A value to append to a class documentation dirname.
Default
classPathSuffix : '',
enumPathPrefix
A value to prepend to an enum documentation dirname.
Default
enumPathPrefix : '',
enumPathSuffix
A value to append to an enum documentation dirname.
Default
enumPathSuffix : '',
interfacePathPrefix
A value to prepend to an interface documentation dirname.
Default
interfacePathPrefix : '',
interfacePathSuffix
A value to append to an interface documentation dirname.
Default
interfacePathSuffix : '',
traitPathPrefix
A value to prepend to a trait documentation dirname.
Default
traitPathPrefix : '',
traitPathSuffix
A value to append to a trait documentation dirname.
Default
traitPathSuffix : '',
labels
An array of key value pairs to use for documentation labels.
Default
labels: [
'class' => 'Class',
'extends' => 'Extends',
'implements' => 'Implements',
'uses' => 'Uses',
'class_synopsis' => 'Class Synopsis',
'constructor' => 'Constructor',
'cases' => 'Cases',
'case_details' => 'Case Details',
'constants' => 'Constants',
'constant_synopsis' => 'Constant Synopsis',
'constant_details' => 'Constant Details',
'properties' => 'Properties',
'property_details' => 'Property Details',
'methods' => 'Methods',
'method_details' => 'Method Details',
'functions' => 'Functions',
'function_synopsis' => 'Function Synopsis',
'function_details' => 'Function Details',
'public' => 'Public',
'protected' => 'Protected',
'private' => 'Private',
'name' => 'Name',
'value' => 'Value',
'type' => 'Type',
'description' => 'Description',
'returns' => 'Returns',
'throws' => 'Throws',
'deprecated' => 'Deprecated',
'internal' => 'Internal',
'generated' => 'Generated',
],
Any labels set in the configuration will be merged with the default.
makeClassDescription
When true, the class documentation will include a description of the class.
Default
makeClassDescription: true,
makeClassExtends
When true, the class documentation will include a list of parent classes.
Default
makeClassExtends: true,
makeClassImplements
When true, the class documentation will include a list of implemented interfaces.
Default
makeClassImplements: true,
makeClassUses
When true, the class documentation will include a list of traits used by the class.
Default
makeClassUses: true,
makeClassConstructor
When true, the class constructor will have its own section in the documentation file.
Default
makeClassConstructor: true,
makeClassSynopsis
When true, a php.net style class index will be generated.
Default
makeClassSynopsis: true,
makeClassCases
When true, any case statements in an enum will be documented.
Default
makeClassCases: true,
makeClassCaseDetails
When true, a more detailed overview of each case in an enum will be documented.
Default
makeClassCaseDetails: true,
makeClassConstants
When true, any constants in a class will be documented.
Default
makeClassConstants: true,
makeClassConstantDetails
When true, a more detailed overview of each constant in a class will be documented.
Default
makeClassConstantDetails: true,
makeClassProperties
When true, any properties in a class will be documented.
Default
makeClassProperties: true,
makeClassPropertyDetails
When true, a more detailed overview of each property in a class will be documented.
Default
makeClassPropertyDetails: true,
makeClassMethods
When true, any methods in a class will be documented.
Default
makeClassMethods: true,
makeClassMethodDetails
When true, a more detailed overview of each method in a class will be documented.
Default
makeClassMethodDetails: true,
makeConstants
When true, any constants that are direct children of a namespace will be documented.
Default
makeConstants: true,
makeConstantsDescription
When true, the constant documentation will include a description of each constant.
Default
makeConstantsDescription: true,
makeConstantSynopsis
When true, a PHP code synopsis of the constants will be generated.
Default
makeConstantSynopsis: true,
makeConstantDetails
When true, a more detailed overview of each constant will be documented.
Default
makeConstantDetails: true,
makeDefines
When true, constants defined with the define function will be included in the constant documentation.
Default
makeDefines: true,
makeFunctions
When true, any functions that are direct children of a namespace will be documented.
Default
makeFunctions: true,
makeFunctionsDescription
When true, the function documentation will include a description for each function.
Default
makeFunctionsDescription: true,
makeFunctionSynopsis
When true, a PHP code synopsis of the functions will be generated.
Default
makeFunctionSynopsis: true,
makeFunctionDetails
When true, a more detailed overview of each function will be documented.
Default
makeFunctionDetails: true,
makeSynopsisMeta
When true, a JSON meta file will be generated with snyopsis URL metadata to allow for injecting links after code highlighting.
Default
makeSynopsisMeta: true,
showDeprecated
When true, deprecated items will be included in the documentation.
Default
showDeprecated: true,
showDeprecatedLabel
When true, a deprecated label will appear under deprecated items in the documentation.
Default
showDeprecatedLabel: true,
showInternal
When true, internal items will be included in the documentation.
Default
showInternal: true,
showInternalLabel
When true, an internal label will appear under internal items in the documentation.
Default
showInternalLabel: true,
showGenerated
When true, generated items will be included in the documentation.
Default
showGenerated: true,
showGeneratedLabel
When true, a generated label will appear under generated items in the documentation.
Default
showGeneratedLabel: true,
accessModifierOrder
An array of PHP access modifiers in the order in which they are to appear in.
Default
use Xlient\Php\Doc\PhpAccessModifier; //... accessModifierOrder: [ PhpAccessModifier::PUBLIC, PhpAccessModifier::PROTECTED, PhpAccessModifier::PRIVATE, ],
typeOrder
An array of PHP types in the order in which they are to appear in.
Default
use Xlient\Php\Doc\PhpType; //... typeOrder: [ PhpType::NULL, PhpType::BOOL, PhpType::TRUE, PhpType::FALSE, PhpType::INT, PhpType::FLOAT, PhpType::STRING, PhpType::ARRAY, PhpType::ITERABLE, PhpType::CALLABLE, PhpType::OBJECT, PhpType::CLASS_NAME, PhpType::VOID, PhpType::SELF, PhpType::STATIC, PhpType::NEVER, ],
sortByName
When true, items will be sorted by name.
Default
sortByName: true,
sortByAccessModifier
When true, items will be sorted by the specified accessModifierOrder order.
Default
sortByAccessModifier: true,
groupByAccessModifier
When true, items will be grouped by access modifiers.
Default
groupByAccessModifier: true,
sortByType
When true, types will be sorted by the specified typeOrder order.
Default
sortByType: true,
inheritDocComments
When true, child class PHPDoc comments will inherit missing information from its corresponding parent PHPDoc comment.
@inheritDoc and {@inheritDoc} will also be handled accordingly.
@inheritdoc / @inheritDoc
Will inherit the entire parent PHPDoc comment.
{@inheritdoc} / {@inheritDoc}
Will only inherit the description and inline it in accordance with the standard.
If it is the only text / tag in the PHPDoc comment, it will instead inherit the entire parent PHPDoc comment. This is non-standard, but a lot of code uses {@inheritdoc} this way.
Default
inheritDocComments: true,
prioritizeDocComments
When true, the information contained in the PHPDoc comment will take precedence over the information gotten from reflection.
Default
prioritizeDocComments: true,
escapeDocComments
When true, PHPDoc comment text will be escaped to not interfere with Markdown.
Default
escapeDocComments = false,
useNullableSyntax
When true, ? will be used instead of null where appropriate.
Default
useNullableSyntax: true,
enableTables
When true, certain information will be placed in tables instead of a more mobile friendly headings and paragraphs.
Default
enableTables: true,
indentLength
The length in spaces to indent code by.
Default
indentLength: 4,
lineLength
The maximum length in characters a code line should be.
Default
lineLength: 80,
override
When true, any existing generated docs in the destDir will be removed before making.
Default
override = false,