Everything

.github/workflows/tests.yml

@@ -0,0 +1,29 @@
+name: Run tests
+
+on:
+  pull_request:
+    types: [ opened, synchronize, reopened ]
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        php: [8.1, 8.2, 8.3, 8.4]
+    name: PHP ${{ matrix.php }} Test
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          extensions: zip
+
+      - name: Install Dependencies
+        run: composer install
+
+      - name: Run tests
+        run: composer test

.gitignore

@@ -1,30 +1,6 @@
+/.idea/
 /vendor/
-node_modules/
-npm-debug.log
-yarn-error.log
 
-# Laravel 4 specific
-bootstrap/compiled.php
-app/storage/
-
-# Laravel 5 & Lumen specific
-public/storage
-public/hot
-
-# Laravel 5 & Lumen specific with changed public path
-public_html/storage
-public_html/hot
-
-storage/*.key
-.env
-Homestead.yaml
-Homestead.json
-/.vagrant
 .phpunit.result.cache
-
-/public/build
-/storage/pail
-.env.backup
-.env.production
-.phpactor.json
-auth.json
+composer.lock
+Taskfile.yml

DEVELOP.md

@@ -0,0 +1,127 @@
+# Development Guide for `laravel-route-docs`
+
+This document outlines the local development workflow for building and testing the `laravel-route-docs` package, 
+as well as integrating it into other Laravel projects before publishing.
+
+---
+
+## Project Setup
+
+ - [Docker](https://www.docker.com/)
+ - [Taskfile](https://taskfile.dev/)
+
+### Setup & Install Dependencies
+
+```bash
+task build
+```
+
+---
+
+## Running Tests
+
+### PHPUnit
+
+```bash
+task test:unit
+```
+
+Or run tests against all versions of PHP:
+
+```bash
+task test:all
+```
+
+---
+
+## Route Integration Tests with Laravel Kernel
+
+- Tests extend `Tests\TestCase`, which boots a full Laravel app kernel using Testbench.
+- Example route definitions are injected using `defineRoutes()`.
+
+---
+
+## Using This Package in Another Laravel Project (During Development)
+
+If you're actively developing this package and want to test it **in another Laravel app** without publishing it yet:
+
+### Option 1: Path Repository (Recommended)
+
+In your consuming Laravel app's `composer.json`:
+
+```json
+"repositories": [
+  {
+    "type": "path",
+    "url": "../path-to/laravel-route-docs"
+  }
+],
+"require": {
+  "mikegarde/laravel-route-docs": "*"
+}
+```
+
+Then run:
+
+```bash
+composer update mikegarde/laravel-route-docs
+```
+
+> Changes in `laravel-route-docs` will be picked up live, no commit/push needed.
+
+---
+
+## Using Inside Docker (Path Setup)
+
+If you're using Docker and the package is **outside** the app folder, mount both volumes in your `docker-compose.yml`:
+
+```yaml
+services:
+  php:
+    volumes:
+      - ../your-laravel-app:/var/www/html
+      - ../laravel-route-docs:/packages/laravel-route-docs
+```
+
+Then in the app's `composer.json`:
+
+```json
+"repositories": [
+  {
+    "type": "path",
+    "url": "/packages/laravel-route-docs"
+  }
+]
+```
+
+Run this inside your container:
+
+```bash
+composer require mikegarde/laravel-route-docs:* --prefer-source
+# And maybe also:
+composer dump-autoload
+php artisan ide-helper:generate
+```
+
+---
+
+## Helpers and Polyfills
+
+To support `base_path()` and `app_path()` in both Laravel and standalone mode:
+- Polyfills are provided in `src/helpers.php`.
+- Registered in `composer.json` under `autoload.files`.
+
+---
+
+## Useful Commands
+
+- `php artisan route:docs` — show documented routes
+- `php artisan route:docs:validate` — validate attribute/route consistency
+- `composer test` — run all tests
+
+---
+
+## Notes
+
+- The `examples/Http/Controllers` folder contains real attribute usage for demo and test purposes.
+

Dockerfile

@@ -0,0 +1,15 @@
+ARG PHP_VERSION=8.1
+FROM php:${PHP_VERSION}-cli
+
+# Install dependencies
+RUN apt-get update && apt-get install -y \
+    git zip unzip curl libzip-dev
+
+# Install Composer &...
+# Can install >100 PHP extensions
+# See: https://github.com/mlocati/docker-php-extension-installer
+ADD https://github.com/mlocati/docker-php-extension-installer/releases/latest/download/install-php-extensions /usr/local/bin/
+RUN chmod +x /usr/local/bin/install-php-extensions && sync
+RUN install-php-extensions @composer xdebug
+
+WORKDIR /app

README.md

@@ -1,2 +1,62 @@
-# laravel-route-docs
+# Laravel Route Docs
+
+[![Latest Version on Packagist](https://img.shields.io/packagist/v/mikegarde/laravel-route-docs.svg?style=flat-square)](https://packagist.org/packages/mikegarde/laravel-route-docs)
+[![GitHub Tests Action Status](https://img.shields.io/github/actions/workflow/status/mikegarde/laravel-route-docs/run-tests.yml?branch=main&label=tests)](https://github.com/mikegarde/laravel-route-docs/actions)
+[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](LICENSE)
+
 A Laravel package that uses PHP attributes to document routes, generate readable route listings, and export OpenAPI or Postman definitions.
+
+---
+
+## Features
+
+- Document routes directly using PHP attributes
+- Validate route documentation in your CI/CD pipeline
+- Includes CLI tooling for discovery and inspection
+
+### TODO:
+- Add request parameters
+- Add response schemas
+- Export route definitions as JSON, OpenAPI, or Postman collections
+
+---
+
+## Installation
+
+```bash
+composer require mikegarde/laravel-route-docs --dev
+```
+
+## Usage
+Annotate your controller methods using custom attributes to describe your API:
+
+```php
+use RouteDocs\Attributes\get;
+
+class ItemController
+{
+    #[get('/items', name: 'items.index')]
+    public function index()
+    {
+        return Item::all();
+    }
+}
+```
+
+Then run:
+
+```bash
+php artisan route:docs
+```
+
+You’ll get a structured view of your documented routes.
+
+## Validate Route Attributes in CI/CD
+
+You can validate that all routes have correct and complete attribute annotations:
+
+```bash
+php artisan route:docs:validate
+```
+
+This will return non-zero exit codes on failure, making it CI-friendly.

Taskfile.dist.yml

@@ -0,0 +1,47 @@
+version: '3'
+
+vars:
+  DEFAULT_PHP: '8.1'
+
+tasks:
+  default:
+    silent: true
+    cmds:
+      - task --list
+      - echo ""
+      - echo -e "\033[34mGet more details by running \033[36mtask --summary [COMMAND]\033[0m"
+
+  build:
+    vars:
+      PHP_VERSION: '{{.DEFAULT_PHP}}'
+    desc: Build the Docker image for PHP development
+    cmds:
+      - task: build:{{.PHP_VERSION}}
+  build:*:
+    vars:
+      PHP_VERSION: '{{index .MATCH 0}}'
+    cmds:
+      - docker compose down
+      - rm -f composer.lock
+      - docker compose build --build-arg PHP_VERSION={{.PHP_VERSION}}
+      - docker compose up -d
+      - docker compose exec php composer install --no-interaction --prefer-dist
+
+  test:unit:
+    desc: Run tests inside the container
+    cmds:
+      - docker compose run --rm php composer test
+  test:all:
+    desc: Run all tests inside the container
+    cmds:
+      - |
+        VERSIONS=("8.1" "8.2" "8.3" "8.4")
+        for VERSION in "${VERSIONS[@]}"; do
+          task build:$VERSION
+          task test:unit
+        done
+
+  ssh:
+    desc: SSH into the PHP container
+    cmds:
+      - docker compose exec php bash

composer.json

@@ -0,0 +1,64 @@
+{
+  "name": "mikegarde/laravel-route-docs",
+  "description": "A Laravel package that uses PHP attributes to document routes, generate readable route listings, and export OpenAPI or Postman definitions.",
+  "type": "library",
+  "license": "GPL-3.0-only",
+  "authors": [
+    {
+      "name": "Mike Garde",
+      "email": "[email protected]"
+    }
+  ],
+  "require": {
+    "php": "^8.1",
+    "illuminate/support": "^9.0|^10.0|^11.0|^12.0",
+    "illuminate/console": "^9.0|^10.0|^11.0|^12.0"
+  },
+  "require-dev": {
+    "phpunit/phpunit": ">=10.5",
+    "orchestra/testbench": ">=8.18"
+  },
+  "autoload": {
+    "psr-4": {
+      "RouteDocs\\": "src/"
+    },
+    "files": [
+      "src/helpers.php"
+    ]
+  },
+  "autoload-dev": {
+    "psr-4": {
+      "Examples\\Http\\Controllers\\": "examples/",
+      "Tests\\": "tests/"
+    }
+  },
+  "extra": {
+    "laravel": {
+      "providers": [
+        "RouteDocs\\RouteDocsServiceProvider"
+      ]
+    }
+  },
+  "keywords": [
+    "laravel",
+    "routes",
+    "route docs",
+    "api docs",
+    "openapi",
+    "postman",
+    "attribute",
+    "annotation",
+    "cli",
+    "developer tools"
+  ],
+  "minimum-stability": "stable",
+  "prefer-stable": true,
+  "scripts": {
+    "test": [
+      "phpunit"
+    ],
+    "post-autoload-dump": [
+      "Illuminate\\Foundation\\ComposerScripts::postAutoloadDump"
+    ]
+  }
+}