README.md

API Documentation Guide

Overview

This directory contains the API documentation for the HashId Bundle v4.x. The documentation is automatically generated from PHPDoc comments in the source code.

Documentation Structure

Generated Documentation

• HTML Documentation: Available in build/api-docs/index.html
• Source PHPDoc: Embedded in all PHP source files in src/
• Configuration: phpdoc.dist.xml (phpDocumentor config)

Key Documentation Files

• docs/rector-rules.md - Custom Rector rules for migration automation
• docs/MIGRATION_TO_ATTRIBUTES.md - Attribute migration guide
• docs/migration-faq.md - Common migration questions and answers
• UPGRADE-4.0.md - Complete upgrade guide from v3.x to v4.x

Generating Documentation

Using the Documentation Generator

# Generate HTML documentation
php bin/generate-docs.php

# Output will be in build/api-docs/
open build/api-docs/index.html

Documentation Coverage

Run the documentation coverage tests to ensure all public APIs are documented:

# Check documentation completeness
vendor/bin/phpunit tests/Documentation/

# Specific tests:
vendor/bin/phpunit tests/Documentation/DocblockValidationTest.php
vendor/bin/phpunit tests/Documentation/ApiCoverageTest.php

Documentation Standards

PHPDoc Requirements

All public classes, methods, and properties must include:

1. Class Documentation:

   • Brief description (one line)
   • Detailed description (if needed)
   • @package tag
   • @since tag for version tracking
   • @deprecated tag if applicable

2. Method Documentation:

   • Brief description
   • @param for all parameters with types
   • @return with type information
   • @throws for exceptions
   • @example for key public methods

3. Property Documentation:

   • Brief description
   • @var with type information

Example PHPDoc

/**
 * Router decorator that automatically encodes route parameters.
 *
 * This decorator wraps the Symfony router to transparently encode
 * integer parameters marked with Hash attributes.
 *
 * @package Pgs\HashIdBundle\Decorator
 * @since 3.0.0
 */
class RouterDecorator
{
    /**
     * Generates a URL with automatic parameter encoding.
     *
     * @param string $name The route name
     * @param array<string, mixed> $parameters Route parameters
     * @param int $referenceType The type of reference
     *
     * @return string The generated URL with encoded parameters
     *
     * @throws RouteNotFoundException If the route doesn't exist
     *
     * @example
     * ```php
     * $url = $router->generate('user_profile', ['id' => 123]);
     * // Result: /user/abc123
     * ```
     */
    public function generate(string $name, array $parameters = [], int $referenceType = self::ABSOLUTE_PATH): string
    {
        // Implementation
    }
}

API Documentation Coverage

Current documentation coverage statistics:

Component	Coverage	Status
Core Classes	100%	✅ Complete
Interfaces	100%	✅ Complete
Public Methods	95%	✅ Excellent
Usage Examples	85%	✅ Good
Migration Notes	100%	✅ Complete

Key API Components

Core Bundle

• PgsHashIdBundle - Main bundle class

Router Decoration

• RouterDecorator - Intercepts URL generation

Annotations/Attributes

• Attribute\Hash - Modern PHP 8 attribute (recommended)
• Annotation\Hash - Legacy annotation (deprecated)

Parameter Processing

• ParametersProcessorInterface - Core processing interface
• Encode - Encodes integers to hashes
• Decode - Decodes hashes to integers

Converters

• ConverterInterface - Conversion abstraction
• HashidsConverter - Default Hashids implementation

Services

• HasherFactory - Creates hashers with different strategies
• CompatibilityLayer - Backward compatibility support

Contributing to Documentation

When adding new features or modifying existing ones:

1. Update PHPDoc in the source files
2. Run documentation tests to ensure completeness
3. Generate new documentation using the generator
4. Update this README if structure changes

Resources

• Symfony Documentation Standards
• phpDocumentor Guide
• PHPDoc Reference