README

PHP implementation of the DocsDog specification.

Installation

composer require docsdog/docsdog-php

Annotation Format

Relationships are declared inside PHP docblocks using the @docsdog annotation:

@docsdog <predicate> <namespace>:<kind>:<identifier>

Example:

/**
 * Handles creation of invoices from purchase orders.
 *
 * @docsdog implements docsdog:usecase:UC-001
 * @docsdog decision docsdog:adr:ADR-004
 */
final class CreateInvoiceService
{
    /**
     * @docsdog requires docsdog:requirement:REQ-014
     */
    public function __construct(
        private readonly InvoiceRepository $repository,
        private readonly EventBus $eventBus,
    ) {}

    /**
     * @docsdog validates docsdog:rule:BR-008
     */
    public function execute(CreateInvoiceCommand $command): Invoice
    {
        $invoice = Invoice::create($command);
        $this->repository->save($invoice);
        return $invoice;
    }

    /**
     * @docsdog emits docsdog:event:InvoiceCreated
     */
    private function dispatchEvents(Invoice $invoice): void
    {
        foreach ($invoice->releaseEvents() as $event) {
            $this->eventBus->publish($event);
        }
    }
}

Annotations are associated with the next code element (class, method, function, interface, trait, or enum) following the docblock. Multiple annotations per docblock are supported.

CLI

php vendor/bin/docsdog scan [options]

Options

Examples

# Scan src/ directory, write to file with pretty output
php vendor/bin/docsdog scan --src=src --output=docsdog-scan.json --pretty

# Scan app/ directory, print to stdout
php vendor/bin/docsdog scan --src=app

# Pipe into another tool
php vendor/bin/docsdog scan --src=src | your-tool

Output Format

The scanner produces a JSON document conforming to the scan schema:

{
  "version": "1.0",
  "relationships": [
    {
      "source": "php://src/Application/CreateInvoiceService.php#L13",
      "predicate": "implements",
      "target": "docsdog:usecase:UC-001"
    },
    {
      "source": "php://src/Application/CreateInvoiceService.php#L13",
      "predicate": "decision",
      "target": "docsdog:adr:ADR-004"
    }
  ]
}

Programmatic API

Scanning files

use Docsdog\DocsdogPhp\Scanner\PhpFileScanner;

$scanner = new PhpFileScanner();
$relationships = $scanner->scan('src/Application/CreateInvoiceService.php');

foreach ($relationships as $rel) {
    echo $rel->source()->toString();   // php://src/...php#L13
    echo $rel->predicate()->value;     // implements
    echo $rel->target()->toString();   // docsdog:usecase:UC-001
}

Building relationships manually

use Docsdog\DocsdogPhp\Identifier\DocsDogNamespace;
use Docsdog\DocsdogPhp\Identifier\SourceIdentifier;
use Docsdog\DocsdogPhp\Identifier\TargetIdentifier;
use Docsdog\DocsdogPhp\Model\Relationship;
use Docsdog\DocsdogPhp\Model\Scan;
use Docsdog\DocsdogPhp\Predicate;

$rel = Relationship::create(
    SourceIdentifier::parse('php://src/Service.php#L42'),
    Predicate::implements(),
    DocsDogNamespace::usecase('UC-001'),
    ['since' => '2.1'], // optional metadata
);

$scan = Scan::of('1.0', [$rel]);
echo $scan->toJson(JSON_PRETTY_PRINT);

Working with identifiers

use Docsdog\DocsdogPhp\Identifier\DocsDogNamespace;
use Docsdog\DocsdogPhp\Identifier\TargetIdentifier;

// Built-in docsdog namespace (typed helpers)
$t1 = DocsDogNamespace::requirement('REQ-014');    // docsdog:requirement:REQ-014
$t2 = DocsDogNamespace::api('post', '/invoices');   // docsdog:api:POST:/invoices
$t3 = DocsDogNamespace::table('invoices');          // docsdog:table:invoices

// External namespaces (generic parser)
$t4 = TargetIdentifier::parse('jira:issue:ERP-123');
$t5 = TargetIdentifier::parse('github:repo:company/project#15');

Running Tests

php test-suite.php