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.
composer require xlient/doc-php
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();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'
],
...
);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.
baseNamespace: [],baseNamespace: [
'\\Xlient'
],With baseNamespace: ['\\Xlient'], the resulting directory path of \\Xlient\\Doc\\Php will become /doc/php.
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.
basePaths: [],basePaths: [
'\\Xlient' => '/help'
],With basePaths: ['\\Xlient' => '/help'], the resulting path of \\Xlient\\Doc\\Php\Configuration will become {destDir}/help/doc/php/configuration.md
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.
baseUrls: [],baseUrls: [
'\\Xlient' => 'https://xlient.com'
],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.
pathFixes: [],pathFixes: [
'MyName' => 'myname'
],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
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.
A more precise method of providing external URLs.
urlCallback: null,$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;
},A method of providing external URLs for external class methods.
methodUrlCallback: null,methodUrlCallback: function(string $class, string $method): ?string {
$url = null;
// ...
return $url;
},When true, public class items will be included.
classPublic: true,When true protected class items will be included.
classProtected: true,When true private class items will be included.
classPrivate: true,A string value to use to separate class names in the inheritance list.
classSeparator: ' » ',When true, separate files will be generated for each class method.
methodFiles: true,When true, separate files will be generated for each function.
functionFiles: true,When true, function files will be placed in a sub directory with the same name as the functions file.
functionDir: true,A value to prepend to a class documentation filename.
classFilenamePrefix: '',classFilenamePrefix: 'class-',A value to append to a class documentation filename.
classFilenameSuffix : '',A value to prepend to an enum documentation filename.
enumFilenamePrefix : '',A value to append to an enum documentation filename.
enumFilenameSuffix : '',A value to prepend to an interface documentation filename.
interfaceFilenamePrefix : '',A value to append to an interface documentation filename.
interfaceFilenameSuffix : '',A value to prepend to a trait documentation filename.
traitFilenamePrefix : '',A value to append to a trait documentation filename.
traitFilenameSuffix : '',A value to prepend to a method documentation filename.
methodFilenamePrefix : '',A value to append to a method documentation filename.
methodFilenameSuffix : '',A value to prepend to a function documentation filename.
functionFilenamePrefix : '',A value to append to a function documentation filename.
functionFilenameSuffix : '',The filename to use for a constants documentation file.
constantsFilename : 'constants',The filename to use for a functions documentation file.
functionsFilename : 'functions',A value to prepend to a class documentation dirname.
classPathPrefix: '',classPathPrefix: 'class-',A value to append to a class documentation dirname.
classPathSuffix : '',A value to prepend to an enum documentation dirname.
enumPathPrefix : '',A value to append to an enum documentation dirname.
enumPathSuffix : '',A value to prepend to an interface documentation dirname.
interfacePathPrefix : '',A value to append to an interface documentation dirname.
interfacePathSuffix : '',A value to prepend to a trait documentation dirname.
traitPathPrefix : '',A value to append to a trait documentation dirname.
traitPathSuffix : '',An array of key value pairs to use for documentation labels.
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.
When true, the class documentation will include a description of the class.
makeClassDescription: true,When true, the class documentation will include a list of parent classes.
makeClassExtends: true,When true, the class documentation will include a list of implemented interfaces.
makeClassImplements: true,When true, the class documentation will include a list of traits used by the class.
makeClassUses: true,When true, the class constructor will have its own section in the documentation file.
makeClassConstructor: true,When true, a php.net style class index will be generated.
makeClassSynopsis: true,When true, any case statements in an enum will be documented.
makeClassCases: true,When true, a more detailed overview of each case in an enum will be documented.
makeClassCaseDetails: true,When true, any constants in a class will be documented.
makeClassConstants: true,When true, a more detailed overview of each constant in a class will be documented.
makeClassConstantDetails: true,When true, any properties in a class will be documented.
makeClassProperties: true,When true, a more detailed overview of each property in a class will be documented.
makeClassPropertyDetails: true,When true, any methods in a class will be documented.
makeClassMethods: true,When true, a more detailed overview of each method in a class will be documented.
makeClassMethodDetails: true,When true, any constants that are direct children of a namespace will be documented.
makeConstants: true,When true, the constant documentation will include a description of each constant.
makeConstantsDescription: true,When true, a PHP code synopsis of the constants will be generated.
makeConstantSynopsis: true,When true, a more detailed overview of each constant will be documented.
makeConstantDetails: true,When true, constants defined with the define function will be included in the constant documentation.
makeDefines: true,When true, any functions that are direct children of a namespace will be documented.
makeFunctions: true,When true, the function documentation will include a description for each function.
makeFunctionsDescription: true,When true, a PHP code synopsis of the functions will be generated.
makeFunctionSynopsis: true,When true, a more detailed overview of each function will be documented.
makeFunctionDetails: true,When true, a JSON meta file will be generated with snyopsis URL metadata to allow for injecting links after code highlighting.
makeSynopsisMeta: true,When true, deprecated items will be included in the documentation.
showDeprecated: true,When true, a deprecated label will appear under deprecated items in the documentation.
showDeprecatedLabel: true,When true, internal items will be included in the documentation.
showInternal: true,When true, an internal label will appear under internal items in the documentation.
showInternalLabel: true,When true, generated items will be included in the documentation.
showGenerated: true,When true, a generated label will appear under generated items in the documentation.
showGeneratedLabel: true,An array of PHP access modifiers in the order in which they are to appear in.
use Xlient\Php\Doc\PhpAccessModifier;
//...
accessModifierOrder: [
PhpAccessModifier::PUBLIC,
PhpAccessModifier::PROTECTED,
PhpAccessModifier::PRIVATE,
],An array of PHP types in the order in which they are to appear in.
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,
],When true, items will be sorted by name.
sortByName: true,When true, items will be sorted by the specified accessModifierOrder order.
sortByAccessModifier: true,When true, items will be grouped by access modifiers.
groupByAccessModifier: true,When true, types will be sorted by the specified typeOrder order.
sortByType: true,When true, child class PHPDoc comments will inherit missing information from its corresponding parent PHPDoc comment.
@inheritDoc and {@inheritDoc} will also be handled accordingly.
Will inherit the entire parent PHPDoc comment.
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.
inheritDocComments: true,When true, the information contained in the PHPDoc comment will take precedence over the information gotten from reflection.
prioritizeDocComments: true,When true, PHPDoc comment text will be escaped to not interfere with Markdown.
escapeDocComments = false,When true, ? will be used instead of null where appropriate.
useNullableSyntax: true,When true, certain information will be placed in tables instead of a more mobile friendly headings and paragraphs.
enableTables: true,The length in spaces to indent code by.
indentLength: 4,The maximum length in characters a code line should be.
lineLength: 80,When true, any existing generated docs in the destDir will be removed before making.
override = false,