julien-boudry/php-reference

Installs: 0

Dependents: 0

Suggesters: 0

Security: 0

Stars: 0

Watchers: 1

Forks: 0

Open Issues: 0

pkg:composer/julien-boudry/php-reference

dev-main 2025-10-21 15:18 UTC

This package is auto-updated.

Last update: 2025-10-21 15:43:19 UTC


README

License Packagist

Main Author: Julien Boudry
License: BSD-3-Clause - Please say hello if you like or use this code!
Donation:bc1q3jllk3qd9fjvvuqy07tawkv7t6h7qjf55fc2gh or GitHub Sponsor Page

PhpReference

PhpReference is a powerful documentation generator for PHP projects. It analyzes your codebase using reflection and generates comprehensive Markdown documentation for your namespaces, classes, methods, properties, and constants.

Workflow

  • Automatic Documentation Generation - Analyzes PHP namespaces using reflection to extract classes, methods, properties, constants, and their metadata
  • PHPDoc Integration - Parses and renders PHPDoc blocks including descriptions, parameters, return types, and custom tags
  • Cross-Referencing - Generates internal links between classes, methods, and properties
  • Public API Focus - Control what gets documented using @api tags or visibility rules
  • Markdown Output - Clean, readable documentation in Markdown format ready for GitHub, GitLab, or your documentation site

Features

  • Full Reflection Analysis - Classes, interfaces, traits, enums, methods, properties, constants
  • PHPDoc Parsing - Descriptions, @param, @return, @throws, @see, custom tags
  • Type Resolution - Automatic linking to documented types
  • Cross-References - Internal links between elements
  • Inheritance Tracking - Shows declaring class for inherited members
  • Custom Public API Rules - Define what gets documented
  • Source Links - Optional links back to source code

Quick Start

Installation

Install PhpReference via Composer:

composer require --dev julien-boudry/php-reference

Basic Usage

Generate documentation for a namespace:

php vendor/bin/php-reference MyNamespace\\MyProject

This will analyze all classes in MyNamespace\MyProject and generate Markdown documentation in the ./output directory.

Generate with Output Directory

Specify a custom output directory:

php vendor/bin/php-reference MyNamespace\\MyProject --output=./docs/api

Include All Public Elements

By default, only elements marked with @api are documented. To include all public elements:

php vendor/bin/php-reference MyNamespace\\MyProject --all-public

Or use the shorthand:

php vendor/bin/php-reference MyNamespace\\MyProject -p

Append Mode

By default, PhpReference cleans the output directory before generation. To append without cleaning:

php vendor/bin/php-reference MyNamespace\\MyProject --append

Or use the shorthand:

php vendor/bin/php-reference MyNamespace\\MyProject -a

Command-Line Options

Option Shortcut Description Example
namespace - Namespace to analyze (required) MyNamespace\\MyProject
--output -o Output directory --output=./docs/api
--append -a Do not clean output directory before generation --append
--all-public -p Include all public code (not just @api tagged) --all-public
--config -c Path to configuration file --config=./my-config.php

Configuration File

For repeated usage, create a reference.php configuration file at your project root to avoid typing arguments every time.

📖 Full Configuration Documentation

Public API Control

PhpReference lets you control what gets documented:

Using @api Tags (Default)

Mark elements for documentation with the @api PHPDoc tag:

/**
 * This class will be documented.
 * @api
 */
class MyClass
{
    /**
     * This method will be documented.
     * @api
     */
    public function myMethod(): void
    {
    }
    
    // This method will NOT be documented (no @api tag)
    public function internalMethod(): void
    {
    }
}

Include All Public Elements

Use --all-public (or -p) to document all public classes, methods, and properties regardless of @api tags.

Output Structure

PhpReference generates a structured documentation hierarchy:

output/
├── README.md                          # API summary with all documented classes
└── ref/
    └── MyNamespace/                   # First namespace level
        └── SubNamespace/              # Second namespace level
            ├── MyClass/               # Directory for MyClass
            │   ├── class_MyClass.md        # Class documentation
            │   ├── method_myMethod.md      # Method documentation
            │   └── property_myProperty.md  # Property documentation
            └── AnotherClass/          # Directory for another class
                └── class_AnotherClass.md   # Another class documentation

Requirements

  • PHP 8.4 or higher
  • Composer for dependency management

Contributing

Contributions are welcome! See CONTRIBUTING.md for development setup and guidelines.

Credits

Created and maintained by Julien Boudry.

If you find this project useful, please consider: