PHPackages                             equidna/laravel-docbot - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. equidna/laravel-docbot

ActiveLibrary[API Development](/categories/api)

equidna/laravel-docbot
======================

Laravel package that generates API documentation and lists custom Artisan commands.

0.2.0(7mo ago)0328MITPHPPHP ^8.1

Since Jul 25Pushed 6mo agoCompare

[ Source](https://github.com/EquidnaMX/laravel-docbot)[ Packagist](https://packagist.org/packages/equidna/laravel-docbot)[ RSS](/packages/equidna-laravel-docbot/feed)WikiDiscussions master Synced 3w ago

READMEChangelog (2)Dependencies (8)Versions (4)Used By (0)

Laravel Docbot
==============

[](#laravel-docbot)

Generate beautiful API documentation and custom command listings for your Laravel 12 projects (PHP 8.1+) — effortlessly.

🚀 Introduction
--------------

[](#-introduction)

**Laravel Docbot** is a developer-focused package that automates the generation of API route documentation (Markdown, Postman collections & OpenAPI/Swagger) and lists all custom Artisan commands in your Laravel project. Designed for modern teams, it streamlines onboarding, API sharing, and internal documentation.

Main Use Cases
--------------

[](#main-use-cases)

- **API Documentation:** Instantly generate Markdown, Postman v2.1 collections, and OpenAPI 3.0 specifications for all your API routes, segmented by prefix.
- **Custom Command Listing:** List all custom Artisan commands, excluding built-in Laravel commands, for easy project overview.
- **Configurable Output:** Customize output directories, route segments, and command exclusions via `config/docbot.php`.

Quick Installation
------------------

[](#quick-installation)

```
composer require equidna/laravel-docbot
```

> The package uses Laravel's auto-discovery. To customize configuration:

```
php artisan vendor:publish --tag=laravel-docbot:config
```

Usage Examples
--------------

[](#usage-examples)

### Generate API Documentation

[](#generate-api-documentation)

```
php artisan docbot:routes
```

- Outputs Markdown, Postman JSON, and OpenAPI YAML files to `doc/routes//`
- Use `--segment=api` (repeatable) to limit generation to specific segment keys.
- Use `--format=markdown`, `--format=postman`, or `--format=openapi` to generate only the required artifact type (defaults to all).
- Use `--continue-on-error` to keep processing the remaining writers even if one format fails (Docbot still reports the failure at the end).

### List Custom Artisan Commands

[](#list-custom-artisan-commands)

```
php artisan docbot:commands
```

- Outputs Markdown to `doc/commands/project_commands.md`

Configuration
-------------

[](#configuration)

Edit `config/docbot.php` to:

- Set output directories
- Define route segments (prefixes, domains, middleware filters)
- Configure default hosts/authentication for route documentation
- Exclude namespaces/commands from listings
- Register custom route writers and command filters/writers

Example segment config:

```
'segments' => [
  [
    'key' => 'api',
    'prefix' => 'api/',
    'host_variable' => 'API_HOST',
    'host_value' => env('DOCBOT_API_HOST', 'https://api.example.com'),
    'auth' => [
      'type' => 'bearer',
      'token_variable' => 'API_TOKEN',
      'header' => 'Authorization',
    ],
  ],
    // ...
],
```

Use the `route_defaults` section to define fallback host placeholders and authentication schemes for segments that do not override them. Set `auth.type` to `none` for public segments such as `web`.

### OpenAPI (Swagger) Documentation

[](#openapi-swagger-documentation)

The OpenAPI writer generates industry-standard OpenAPI 3.0 specifications in YAML format. These can be:

- Imported into **Swagger UI** for interactive API documentation
- Used with **Redoc** for beautiful, customizable API docs
- Imported into **Postman** or **Insomnia** for API testing
- Used for **client SDK generation** with tools like OpenAPI Generator
- Integrated with **API gateways** and monitoring tools

**Features:**

- Automatically extracts route parameters and converts them to OpenAPI format
- Generates security schemes from your auth configuration (Bearer, API Key)
- Groups endpoints by tags derived from route names
- Includes standard HTTP response codes (200, 400, 401, 404, 500)
- Adds request bodies for POST/PUT/PATCH endpoints
- Extracts descriptions from controller docblocks

**Example output file:** `doc/routes/api/api.yaml`

You can serve this file with Swagger UI in your Laravel app or use it with external documentation tools. The specification follows the OpenAPI 3.0 standard, ensuring broad compatibility with the API tooling ecosystem.

### Output directory safety

[](#output-directory-safety)

Path traversal remains a common attack vector in Laravel apps ([StackHawk](https://www.stackhawk.com/blog/laravel-path-traversal-guide-examples-and-prevention/), [OWASP](https://owasp.org/www-community/attacks/Path_Traversal), [HackerOne](https://www.hackerone.com/blog/preventing-directory-traversal-attacks-techniques-and-tips-secure-file-access)). To align with that guidance, Docbot now canonicalizes `docbot.output_dir` using a dedicated `PathGuard` helper and refuses to write outside `base_path()`. If the configured path escapes your project root, Docbot aborts early with a descriptive error so you can correct the value (for example, `DOCBOT_OUTPUT_DIR=doc` or `storage/docs`). This keeps generated Markdown/Postman files inside your repository while still letting you reorganize folders safely.

### Sanitization policy (filenames)

[](#sanitization-policy-filenames)

Docbot sanitizes segment keys when producing filesystem artifacts (for example `doc/routes//`). The behavior is centralized in `\Equidna\LaravelDocbot\Routing\Support\Sanitizer::filename()` and can be customized via `config/docbot.php` under the `sanitization.filename` keys.

Example — override the default pattern/replacement/fallback in your published config:

```
// config/docbot.php
'sanitization' => [
  'filename' => [
    // PCRE pattern used to find runs of disallowed characters
    'pattern' => '/[^A-Za-z0-9._-]+/',
    // Replacement for matched runs
    'replacement' => '-',
    // Fallback name when the sanitized result would be empty
    'fallback' => 'unknown',
  ],
],
```

Quick example — expected effect

```
// Suppose you configure a segment key like this:
$segmentKey = 'My API / v1';

// With the default sanitization the filename becomes:
// Sanitizer::filename('My API / v1') === 'My-API-v1'

// If you prefer underscores instead of hyphens, set replacement => '_':
// 'sanitization.filename.replacement' => '_'
// Sanitizer::filename('My API / v1') === 'My_API_v1'
```

Notes:

- The default pattern replaces any character that is not A-Z, a-z, 0-9, dot, underscore or hyphen with `-`.
- The `fallback` value is used when the sanitized result would be empty or ambiguous (for example when the configured key is `.` or `..`).
- `Sanitizer::filename()` will fall back to sensible defaults if the config system is not available (for example during early boot or in non-Laravel contexts).

### Swapping Writers & Filters

[](#swapping-writers--filters)

Docbot now exposes explicit extension points via `config/docbot.php`:

- `routes.writers`: array of classes implementing `Equidna\LaravelDocbot\Contracts\RouteWriter`. The package includes Markdown, Postman, and OpenAPI writers out of the box. Provide your own class to output alternative formats (e.g., HTML, AsyncAPI).
- `routes.collector`: class implementing `Equidna\LaravelDocbot\Contracts\RouteCollector`. Swap out the default router-based collector if you source routes from elsewhere.
- `routes.segment_resolver`: class implementing `Equidna\LaravelDocbot\Contracts\RouteSegmentResolver` to alter how segments are built.
- `commands.filters`: array of classes implementing `Equidna\LaravelDocbot\Contracts\CommandFilter`. Use this to skip framework-specific namespaces or generated commands.
- `commands.writer`: class implementing `Equidna\LaravelDocbot\Contracts\CommandWriter`. Replace the Markdown writer with JSON, HTML, etc.
- `commands.output_filename`: tweak the Markdown filename without replacing the writer.

Each writer/filter is resolved through the Laravel service container, so you may leverage dependency injection for config, loggers, HTTP clients, etc.

Technical Overview
------------------

[](#technical-overview)

- **Command-based workflow:** All features are implemented as Artisan commands.
- **API docs:** Reads route definitions directly from Laravel's router, segments them via configurable prefixes/middleware, and extracts controller docblocks for descriptions.
- **Multiple formats:**
    - Markdown tables for human-readable documentation
    - Postman v2.1 collections for API testing
    - OpenAPI 3.0 specifications for industry-standard API documentation and tooling integration
- **Custom command listing:** Filters out built-in commands using config-driven lists.
- **Extensibility:** Route/command pipelines resolve contracts (`RouteCollector`, `RouteSegmentResolver`, `RouteWriter`, `CommandFilter`, `CommandWriter`) so projects can override behavior via config bindings.
- **Output:**
    - API docs: `doc/routes//`
    - Command docs: `doc/commands/`

Additional internals (recent changes):

- **Centralized file I/O:** Writers now delegate filesystem writes to a shared `WriterFilesystem` helper which ensures directories exist, centralizes error handling, and provides consistent behavior across Markdown/Postman/OpenAPI/Command writers.
- **Safer output paths:** `PathGuard` canonicalizes and validates configured output directories and will refuse to write files outside `base_path()`, preventing accidental path traversal or writes to unexpected locations.

Development Instructions
------------------------

[](#development-instructions)

- **Code Style:** PSR-12 (see Coding Standards)
- **Configuration:** Edit `config/docbot.php` for custom output and exclusions.

---

For more details, see the source code and configuration files. Contributions welcome!

Changelog
---------

[](#changelog)

All notable changes to this project are documented in `CHANGELOG.md`.

### Unreleased

[](#unreleased)

See `CHANGELOG.md` for full release history. The most recent release is `0.2.0` (2025-11-20), which includes:

- Centralized filesystem writes via `WriterFilesystem` and improved filesystem error handling in all writers.
- Safer output path canonicalization and enforcement via `PathGuard` (prevents writes outside `base_path()`).
- PHPStan & docblock fixes and other quality improvements.

Future, unreleased changes will be tracked under the `Unreleased` heading in `CHANGELOG.md`.

###  Health Score

33

—

LowBetter than 72% of packages

Maintenance65

Regular maintenance activity

Popularity14

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity37

Early-stage or recently created project

 Bus Factor1

Top contributor holds 88.2% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~119 days

Total

2

Last Release

216d ago

PHP version history (2 changes)0.1PHP >=8.0

0.2.0PHP ^8.1

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/984800?v=4)[gruelas](/maintainers/gruelas)[@gruelas](https://github.com/gruelas)

---

Top Contributors

[![gruelasjr](https://avatars.githubusercontent.com/u/40619710?v=4)](https://github.com/gruelasjr "gruelasjr (15 commits)")[![Copilot](https://avatars.githubusercontent.com/in/1143301?v=4)](https://github.com/Copilot "Copilot (2 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP\_CodeSniffer

### Embed Badge

![Health badge](/badges/equidna-laravel-docbot/health.svg)

```
[![Health](https://phpackages.com/badges/equidna-laravel-docbot/health.svg)](https://phpackages.com/packages/equidna-laravel-docbot)
```

###  Alternatives

[laravel/ai

The official AI SDK for Laravel.

9782.1M161](/packages/laravel-ai)[psalm/plugin-laravel

Psalm plugin for Laravel

3345.1M337](/packages/psalm-plugin-laravel)[laravel/mcp

Rapidly build MCP servers for your Laravel applications.

76518.2M120](/packages/laravel-mcp)[illuminate/queue

The Illuminate Queue package.

20432.2M1.5k](/packages/illuminate-queue)[roots/acorn

Framework for Roots WordPress projects built with Laravel components.

9742.3M121](/packages/roots-acorn)[moonshine/moonshine

Laravel administration panel

1.3k239.9k75](/packages/moonshine-moonshine)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)