PHPackages intent-doc/laravel - 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. intent-doc/laravel ActiveLibrary[API Development](/categories/api) intent-doc/laravel ================== Developer-first API documentation that lives where your code lives. Document the intent behind your Laravel API endpoints with a fluent, expressive syntax. 02PHP Since Jan 17Pushed 4mo agoCompare [ Source](https://github.com/intent-doc/laravel)[ Packagist](https://packagist.org/packages/intent-doc/laravel)[ RSS](/packages/intent-doc-laravel/feed)WikiDiscussions main Synced 1mo ago READMEChangelogDependenciesVersions (3)Used By (0) IntentDoc for Laravel ===================== [](#intentdoc-for-laravel) [![Latest Version on Packagist](https://camo.githubusercontent.com/df5aad008f3bf8b4cbc7b2f7e4f35b8fade17949d319b79e17c18b2e405cf2f1/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f696e74656e742d646f632f6c61726176656c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/intent-doc/laravel)[![Total Downloads](https://camo.githubusercontent.com/901422c05956167a19126d913386f38df9e7f408d7a92ff361611a43f5deacb3/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f696e74656e742d646f632f6c61726176656c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/intent-doc/laravel)[![License](https://camo.githubusercontent.com/f4f41beb74fe6ce7f8ee10b3ef4f75ec6fa45f60f3a89798a8818c37ffa7ec8b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f696e74656e742d646f632f6c61726176656c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/intent-doc/laravel) **Developer-first API documentation that lives where your code lives.** IntentDoc allows you to describe the intent behind your API endpoints directly where they are defined. By attaching human-readable metadata (purpose, rules, and context) to routes using a fluent, expressive API, IntentDoc generates a clear, structured representation of what each endpoint is meant to do. Why IntentDoc? -------------- [](#why-intentdoc) - **Intent-Driven**: Document the "why", not just the "what" - **Clean Syntax**: Fluent API that feels natural in Laravel - **Zero Pollution**: No heavy annotations or controller clutter - **Multiple Formats**: Generate JSON, Markdown, or HTML documentation - **Framework-Friendly**: Built specifically for Laravel's routing system - **Lightweight**: Minimal dependencies, maximum clarity Installation ------------ [](#installation) Install via Composer: ``` composer require intent-doc/laravel ``` The service provider will be automatically registered. Usage ----- [](#usage) ### Basic Example [](#basic-example) In your route files (`routes/api.php` or `routes/web.php`): ``` use Illuminate\Support\Facades\Route; Route::post('/payments', [PaymentController::class, 'store']) ->intent('Process payment') ->description('Processes a customer payment transaction') ->rules([ 'Authenticated user required', 'User must have valid payment method', 'Amount must be positive', ]); ``` ### Advanced Example [](#advanced-example) ``` Route::get('/users/{id}', [UserController::class, 'show']) ->intent('Get user details') ->description('Retrieves detailed information about a specific user') ->rules([ 'Authenticated user required', 'Admin or user must own the resource', ]) ->request([ 'headers' => [ 'Authorization' => 'Bearer {token}', ], ]) ->response([ 'data' => [ 'id' => 1, 'name' => 'John Doe', 'email' => 'john@example.com', ], ]); ``` ### Available Methods [](#available-methods) - `->intent(string $name)` - The name/intent of the endpoint (required) - `->description(string $description)` - Detailed description of what the endpoint does - `->rules(array $rules)` - Business rules and constraints - `->request(array $request)` - Example request structure - `->response(array $response)` - Example response structure Generating Documentation ------------------------ [](#generating-documentation) IntentDoc provides an Artisan command to generate documentation in multiple formats: ### Quick Start - Interactive Documentation [](#quick-start---interactive-documentation) The easiest way to generate documentation is to run the command without any options: ``` php artisan intent-doc:generate ``` This will automatically: 1. Create an `intent-doc/` folder in your project root 2. Generate `intent-doc/api-doc.json` with all your documented endpoints 3. Generate `intent-doc/index.html` - a beautiful, interactive documentation viewer Simply open `intent-doc/index.html` in your browser to view your API documentation! **Features of the interactive viewer:** - Search endpoints by name, path, or method - Expandable sections for each endpoint - Color-coded HTTP methods (GET, POST, PUT, DELETE, etc.) - Clean, modern interface with syntax highlighting - No server required - works offline [![IntentDoc Interactive Viewer](docs/images/simple_example.png)](docs/images/simple_example.png) ### Custom Output (Advanced) [](#custom-output-advanced) You can also generate documentation in specific formats to custom locations: #### JSON Format [](#json-format) ``` php artisan intent-doc:generate --format=json --output=docs/custom-api.json ``` #### Markdown Format [](#markdown-format) ``` php artisan intent-doc:generate --format=markdown --output=docs/API.md ``` #### HTML Format [](#html-format) ``` php artisan intent-doc:generate --format=html --output=docs/api.html ``` ### Example Output Structure [](#example-output-structure) The generated `api-doc.json` follows this structure: ``` { "version": "1.0", "generated_at": "2024-01-15T10:30:00Z", "endpoints": [ { "name": "Process payment", "description": "Processes a customer payment transaction", "method": "POST", "endpoint": "/api/payments", "rules": [ "Authenticated user required", "User must have valid payment method" ], "request": { "amount": 99.99, "currency": "USD" }, "response": { "id": 12345, "status": "completed" } } ] } ``` ### Version Control [](#version-control) You can choose to commit the `intent-doc/` folder to your repository or generate it on-demand: **Option 1: Commit documentation (Recommended)** - Keep `intent-doc/` in version control - Useful for sharing documentation with the team - Documentation is always available without regeneration **Option 2: Generate on-demand** - Add `intent-doc/` to your `.gitignore` - Generate documentation when needed - Keeps repository lighter ``` # Add to .gitignore if you prefer to generate on-demand /intent-doc/ ``` Real-World Example ------------------ [](#real-world-example) ``` // routes/api.php Route::prefix('api/v1')->group(function () { Route::post('/auth/login', [AuthController::class, 'login']) ->intent('User authentication') ->description('Authenticates a user and returns an access token') ->rules([ 'Rate limited to 5 attempts per minute', 'Credentials must be valid', ]) ->request([ 'email' => 'user@example.com', 'password' => 'password123', ]) ->response([ 'token' => 'eyJhbGciOiJIUzI1...', 'expires_at' => '2024-01-15T12:00:00Z', ]); Route::middleware('auth:sanctum')->group(function () { Route::get('/orders', [OrderController::class, 'index']) ->intent('List user orders') ->description('Retrieves a paginated list of orders for the authenticated user') ->rules([ 'Authenticated user required', 'Returns only orders owned by the user', ]) ->response([ 'data' => [ ['id' => 1, 'total' => 99.99, 'status' => 'completed'], ['id' => 2, 'total' => 149.99, 'status' => 'pending'], ], 'meta' => [ 'current_page' => 1, 'total' => 45, ], ]); Route::post('/orders', [OrderController::class, 'store']) ->intent('Create new order') ->description('Creates a new order for the authenticated user') ->rules([ 'Authenticated user required', 'Cart must not be empty', 'All items must be in stock', 'Payment method must be valid', ]) ->request([ 'items' => [ ['product_id' => 1, 'quantity' => 2], ['product_id' => 5, 'quantity' => 1], ], 'shipping_address_id' => 3, 'payment_method_id' => 2, ]) ->response([ 'data' => [ 'id' => 123, 'total' => 199.99, 'status' => 'pending', ], ]); }); }); ``` Benefits -------- [](#benefits) ### For Developers [](#for-developers) - **Documentation lives with code**: No more outdated separate docs - **Quick onboarding**: New developers understand intent immediately - **Self-documenting**: The code explains business logic - **Type-safe**: Fluent API with IDE autocomplete ### For Teams [](#for-teams) - **Alignment**: Business intent is explicit in technical implementation - **Maintainability**: Easy to understand what endpoints should do - **Communication**: Bridge between technical and business teams - **Evolution**: See how APIs should change over time ### For Projects [](#for-projects) - **API Discovery**: Automatically generate documentation - **Contract Testing**: Use intent definitions for testing - **API Governance**: Ensure endpoints meet business requirements - **Integration**: Share documentation with frontend teams Philosophy ---------- [](#philosophy) IntentDoc follows these principles: 1. **Intent Over Implementation**: Document *why* before *how* 2. **Proximity**: Documentation should live next to the code it describes 3. **Clarity**: Simple, readable, human-friendly syntax 4. **Flexibility**: Multiple output formats for different needs 5. **Zero Overhead**: Minimal performance impact Requirements ------------ [](#requirements) - PHP 8.2, 8.3, or 8.4 - Laravel 10.x, 11.x, or 12.x Testing ------- [](#testing) Run the tests with: ``` composer test ``` Generate coverage report: ``` composer test-coverage ``` ### Local Testing with Docker [](#local-testing-with-docker) You can test all PHP/Laravel version combinations locally using Docker without relying on GitHub Actions: ``` # Run all tests across multiple PHP and Laravel versions ./run-tests-docker.sh ``` This will: - Test PHP 8.2, 8.3, and 8.4 - Test Laravel 10.x, 11.x, and 12.x - Generate a compatibility matrix in `COMPATIBILITY.md` - Save detailed logs in `test-results/` The script uses official PHP Docker images and provides colored output showing which combinations passed (✓), failed (✗), or are not supported (⊘). **Requirements:** - Docker installed and running - Internet connection (first run only) **View results:** ``` # See the compatibility matrix cat COMPATIBILITY.md # Check specific test logs cat test-results/php-8.2-laravel-10.*.log ``` Development ----------- [](#development) Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details. Changelog --------- [](#changelog) Please see [CHANGELOG.md](CHANGELOG.md) for recent changes. License ------- [](#license) MIT License - see [LICENSE](LICENSE) file for details. Support ------- [](#support) If you encounter any issues or have questions, please [open an issue](https://github.com/intent-doc/laravel/issues) on GitHub. --- Made with ❤️ for Laravel developers who believe good documentation starts with clear intent. laravel ======= [](#laravel) ### Health Score 19 — LowBetter than 10% of packages Maintenance52 Moderate activity, may be stable Popularity2 Limited adoption so far Community6 Small or concentrated contributor base Maturity15 Early-stage or recently created project Bus Factor1 Top contributor holds 100% 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. ### Community Maintainers ![](https://www.gravatar.com/avatar/f4aaa8f63fe90bcb0e26a7dfe9817d5b1e364431ba8c08be43562f5cbda774ec?d=identicon)[oadrianolucas](/maintainers/oadrianolucas) --- Top Contributors [![oadrianolucas](https://avatars.githubusercontent.com/u/66094825?v=4)](https://github.com/oadrianolucas "oadrianolucas (5 commits)") ### Embed Badge ![Health badge](/badges/intent-doc-laravel/health.svg) ``` [![Health](https://phpackages.com/badges/intent-doc-laravel/health.svg)](https://phpackages.com/packages/intent-doc-laravel) ``` ### Alternatives [stripe/stripe-php Stripe PHP Library 4.0k143.3M480](/packages/stripe-stripe-php)[twilio/sdk A PHP wrapper for Twilio's API 1.6k92.9M272](/packages/twilio-sdk)[facebook/php-business-sdk PHP SDK for Facebook Business 90821.9M34](/packages/facebook-php-business-sdk)[meilisearch/meilisearch-php PHP wrapper for the Meilisearch API 74513.7M114](/packages/meilisearch-meilisearch-php)[google/gax Google API Core for PHP 265103.1M454](/packages/google-gax)[google/common-protos Google API Common Protos for PHP 173103.7M50](/packages/google-common-protos) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)