phpdocumentor/reflectioncommon

phpDocumentor

What is phpDocumentor?

phpDocumentor stands as the de-facto documentation tool for PHP projects, offering a robust solution for generating comprehensive documentation effortlessly. By analyzing your PHP source code and DocBlock comments, phpDocumentor generates a complete set of API documentation, making it an indispensable tool for developers striving for clear and well-documented codebases.

Beyond its prowess in API documentation, phpDocumentor goes further by providing additional features. It is equipped with the ability to create UML diagrams, making it a versatile tool for visualizing code structure. Additionally, phpDocumentor offers a full-featured markup language parser, supporting both RestructuredText and Markdown syntax. This flexibility allows you to document your project using the markup language that best suits your preferences.

A notable feature of phpDocumentor is its capability to include parts of your API documentation directly into your RestructuredText documentation. This integration ensures that your documentation and code remain in sync, saving you time and effort in maintaining accurate and up-to-date project documentation.

Inspired by its predecessors, phpDocumentor 1 and JavaDoc, phpDocumentor continues to innovate, staying up-to-date with the latest technologies and PHP language features. This commitment ensures that developers have access to the best possible documentation experience, aligning with modern development practices.

In this guide, we will explore the various features of phpDocumentor, from its core functionality in generating API documentation to its advanced capabilities in parsing markup languages. Whether you're a beginner or an experienced developer, phpDocumentor is your ally in creating well-documented, maintainable, and understandable PHP projects.

phpDocumentor v3 (Stable)

v3 is the latest stable release.

Documentation

For more detailed information, you can check our online documentation at https://docs.phpdoc.org/.

Features

phpDocumentor supports the following:

• PHP 7.0+ compatible, full support for Namespaces, Closures and more are provided.
• Docblock over types, docblocks can be more explicit about types not all formats are supported by native php.
• Shows any tag, some tags add additional functionality to phpDocumentor (such as @link).
• Low memory usage, peak memory usage for small projects is less than 20MB, medium projects 40MB, and large frameworks 100MB.
• Incremental parsing, if you kept the Structure file from a previous run, you get an additional performance boost of up to 80% on top of the mentioned processing speed increase above.
• Easy template building, if you want to make a branding you only have to call 1 task and edit 3 files.
• Two-step process, phpDocumentor first generates a cache with your application structure before creating the output. If you'd like you can use that to power your own tools or formatters!
• Generics support, with more static analysis in php types have become more complex. phpDocumentor understand these types. And will render them as first class types.

Installation

PhpDocumentor requires PHP 8.1 or higher to run. However, code of earlier PHP versions can be analyzed.

All templates provided with phpDocumentor have support for Class diagrams based on the read code base. This will require the application [PlantUml] to be installed on the machine running phpDocumentor. Rendering the class diagrams using [PlantUml] is optional, and warnings about missing [PlantUml] can be ignored. However, your documentation will contain some dead links in this case. Class diagram will be created with option --setting=graphs.enabled=true.

There are 4 ways to install phpDocumentor:

1. Using phive (recommended)
2. Using the PHAR (manual install)
3. Via Docker
4. Via Composer

Using Phive

$ phive install phpDocumentor --trust-gpg-keys 8AC0BAA79732DD42

For more information about phive have a look at their website. Now you have phpDocumentor installed, it can be executed like this:

php tools/phpDocumentor

Using the PHAR

1. Download the phar file from https://github.com/phpDocumentor/phpDocumentor/releases
2. You can execute the phar like this: php phpDocumentor.phar

Via Docker

1. $ docker pull phpdoc/phpdoc
2. $ docker run --rm -v $(pwd):/data phpdoc/phpdoc

Via Composer (not recommended)

But wait? What about composer?

Ah, you discovered our secret. There is a phpdocumentor composer package that you can use to install phpDocumentor.

However: phpDocumentor is a complex application, and its libraries are used in countless other libraries and applications (2 of our libraries have more than 150 million downloads each); and this means that the chances for a conflict between one of our dependencies and yours is high. And when I say high, it is really high.

So, because of the above: we do not endorse nor actively support installing phpDocumentor using Composer.

How to use phpDocumentor?

The easiest way to run phpDocumentor is by running the following command:

$ phpdoc run -d <SOURCE_DIRECTORY> -t <TARGET_DIRECTORY>

This command will parse the source code provided using the -d argument and output it to the folder indicated by the -t argument.

phpDocumentor supports a whole range of options to configure the output of your documentation. You can execute the following command, or check our website, for a more detailed listing of available command-line options.

$ phpdoc run -h

Configuration file(s)

phpDocumentor also supports the use of configuration files (named phpdoc.xml or phpdoc.dist.xml by default). Please consult the documentation to see the format and supported options.

Nightly builds

PhpDocumentor doesn't have nightly releases. However, during each pipeline a phar artifact is built. If you want to test the bleeding edge version of phpDocumentor, have a look in the actions section of this repository. Each successful QA workflow has an Artifacts section at the bottom with the phar artifact built.

Contact

Reaching out to us is easy, and can be done with:

• Twitter: @phpDocumentor
• Website: https://www.phpdoc.org
• GitHub: https://www.github.com/phpDocumentor/phpDocumentor
• E-mail: [email protected]

reflectioncommon's Issues

CI review for PHP 8.1/decisions requested

Hi @jaapio,

As discussed, I've done a review of the CI setup with an eye on getting the tests running on PHP 8.1.

Aside from some obvious fixes which are needed, I also found a number of things for which there are multiple solution directions available and I would like to ask you for guidance as to what is your preferred solution.

I have a (passing) WIP branch prepared and will pull the various PRs once I receive your replies.

Psalm

At this moment, there is an inconsistency between the Psalm version for local dev use and the Psalm version used in CI.

For local dev, Psalm is installed via Phive and fixed at version 3.11.2 which yields no issues. An upgrade to version 3.18.2 (last 3.x release) would be needed due to the age of the version, but that is an update without consequence.

For CI, Psalm is installed via the tools option of the setup-php action without fixed version, which in practice means that the latest version of Psalm is used, which is version 4.6.1, which would yield one issue.

Options:

• Manage Psalm via Phive and change the CI workflow for Psalm to use the Phive installed version of Psalm.
• Use setup-php to install Psalm in CI, but fix the version being installed to the same version as installed via Phive.
  This would add a maintenance burden as the version numbers in phive.xml and in the push.yml workflow file would need to be manually kept in sync.
• Always use the latest version of Psalm, no changes needed in CI, one fix needed in the code base, update of Phive version for Psalm needed.
  Note: I'm not sure how to ensure that Phive will always install the latest version and haven't been able to find information on the XML schema to figure out if I can just remove the installed key or set it to latest or something.

Additional question:

• Do you want to upgrade from Psalm 3.x to Psalm 4.x ? (option 3 already implies this)

Test workflow

In the phpunit job, the actual running of the tests has a continue-on-error directive. This means that even when a test build fails, the workflow will continue and not be marked as "failed", nor will email notification about the failed build be send out.
Individual builds will still be marked as failed.

I suspect this may have been set-up this way to make sure that all matrix variations of test builds will actually be run ?

I'm proposing to change this now by:

• Removing the continue-on-error for the test run step.
• Adding the fail-fast key and setting it to false.
  By default this key is set to true, which means that if any individual build within the job fails, all other builds within the job will be cancelled.
  By setting it to false, all builds in the matrix will still be run, but if any of them fail, the workflow will be marked as "failed".

PHPUnit vs PHP 8.1

The latest release of the PHPUnit 9.5 Phar still contains an incompatibility with PHP 8.1-beta1 (and higher).
Using the PHPUnit Phar will therefore fail the build, even though the tests do actually pass on PHP 8.1.

The next Phar release of PHPUnit (9.5.8) will contain a fix for the above mentioned issue.

Options:

• For the time being, allow the test builds against PHP 8.1 to fail.
• For the time being, use a Composer installed version of PHPUnit for the test run against PHP 8.1.

General

In various jobs in the workflow, steps are included to cache the Composer downloads directory and run composer install. However, this package has no dependencies, so these steps are redundant.

Options:

• Remove these steps and replace them with a single step to run composer dumpautoload.
• Replace these steps with the ramsey/composer-install action to clean up the script and maintain the existing behaviour.
• Leave as-is.

Please let me know what action you'd prefer for each of these issues.

Failing tests

https://travis-ci.org/phpDocumentor/ReflectionCommon/jobs/627700228

Upgrade to phpunit 9 and drop php 7.2 support

We are currently using phpunit 8, and should upgrade to phpunit 9. and drop support for php 7.2.

Please exclude the /tests directory with .gitattributes

Please add a .gitattributes that excludes the /tests directory and any other files that aren't needed in production (e.g.: README.txt).

Thanks 😃

Official release of 2.0?

seem to make a year its beta and no new commit. can it be marked stable?

FQSEN constructor does not accept all valid PHP Class Names

FQSEN constructor accepts only alphanumeric characters, but a lot more are allowed in PHP.
This makes parsing in ReflectionDocBlock fail with valid php class names.

From PHP Documentation:

A valid class name starts with a letter or underscore, followed by any number of letters, numbers, or underscores. As a regular expression, it would be expressed thus: ^[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*$.

For example Option«T» is a valid Interface Name, but is not a valid FQSEN name.

In a library I am working on I need to handle this special chars, and to do so I committed a small patch to the regexp in a fork: nicmart@9f3d9ea

If you agree that this is an issue that has to be fixed, I can open a pull request with the fix.

Thanks!