Skip to content

Commit 1332b4e

Browse files
MikeGardeMikeGarde
authored
Merge pull request #1 from MikeGarde/develop
Everything
2 parents 8270ca6 + 174a287 commit 1332b4e

28 files changed

+1044
-28
lines changed

‎.github/workflows/tests.yml‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
name: Run tests
2+
3+
on:
4+
pull_request:
5+
types: [ opened, synchronize, reopened ]
6+
branches: [ main ]
7+
8+
jobs:
9+
test:
10+
runs-on: ubuntu-latest
11+
strategy:
12+
matrix:
13+
php: [8.1, 8.2, 8.3, 8.4]
14+
name: PHP ${{ matrix.php }} Test
15+
16+
steps:
17+
- uses: actions/checkout@v4
18+
19+
- name: Setup PHP
20+
uses: shivammathur/setup-php@v2
21+
with:
22+
php-version: ${{ matrix.php }}
23+
extensions: zip
24+
25+
- name: Install Dependencies
26+
run: composer install
27+
28+
- name: Run tests
29+
run: composer test

‎.gitignore‎

Lines changed: 3 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,6 @@
1+
/.idea/
12
/vendor/
2-
node_modules/
3-
npm-debug.log
4-
yarn-error.log
53

6-
# Laravel 4 specific
7-
bootstrap/compiled.php
8-
app/storage/
9-
10-
# Laravel 5 & Lumen specific
11-
public/storage
12-
public/hot
13-
14-
# Laravel 5 & Lumen specific with changed public path
15-
public_html/storage
16-
public_html/hot
17-
18-
storage/*.key
19-
.env
20-
Homestead.yaml
21-
Homestead.json
22-
/.vagrant
234
.phpunit.result.cache
24-
25-
/public/build
26-
/storage/pail
27-
.env.backup
28-
.env.production
29-
.phpactor.json
30-
auth.json
5+
composer.lock
6+
Taskfile.yml

‎DEVELOP.md‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# Development Guide for `laravel-route-docs`
2+
3+
This document outlines the local development workflow for building and testing the `laravel-route-docs` package,
4+
as well as integrating it into other Laravel projects before publishing.
5+
6+
---
7+
8+
## Project Setup
9+
10+
- [Docker](https://www.docker.com/)
11+
- [Taskfile](https://taskfile.dev/)
12+
13+
### Setup & Install Dependencies
14+
15+
```bash
16+
task build
17+
```
18+
19+
---
20+
21+
## Running Tests
22+
23+
### PHPUnit
24+
25+
```bash
26+
task test:unit
27+
```
28+
29+
Or run tests against all versions of PHP:
30+
31+
```bash
32+
task test:all
33+
```
34+
35+
---
36+
37+
## Route Integration Tests with Laravel Kernel
38+
39+
- Tests extend `Tests\TestCase`, which boots a full Laravel app kernel using Testbench.
40+
- Example route definitions are injected using `defineRoutes()`.
41+
42+
---
43+
44+
## Using This Package in Another Laravel Project (During Development)
45+
46+
If you're actively developing this package and want to test it **in another Laravel app** without publishing it yet:
47+
48+
### Option 1: Path Repository (Recommended)
49+
50+
In your consuming Laravel app's `composer.json`:
51+
52+
```json
53+
"repositories": [
54+
{
55+
"type": "path",
56+
"url": "../path-to/laravel-route-docs"
57+
}
58+
],
59+
"require": {
60+
"mikegarde/laravel-route-docs": "*"
61+
}
62+
```
63+
64+
Then run:
65+
66+
```bash
67+
composer update mikegarde/laravel-route-docs
68+
```
69+
70+
> Changes in `laravel-route-docs` will be picked up live, no commit/push needed.
71+
72+
---
73+
74+
## Using Inside Docker (Path Setup)
75+
76+
If you're using Docker and the package is **outside** the app folder, mount both volumes in your `docker-compose.yml`:
77+
78+
```yaml
79+
services:
80+
php:
81+
volumes:
82+
- ../your-laravel-app:/var/www/html
83+
- ../laravel-route-docs:/packages/laravel-route-docs
84+
```
85+
86+
Then in the app's `composer.json`:
87+
88+
```json
89+
"repositories": [
90+
{
91+
"type": "path",
92+
"url": "/packages/laravel-route-docs"
93+
}
94+
]
95+
```
96+
97+
Run this inside your container:
98+
99+
```bash
100+
composer require mikegarde/laravel-route-docs:* --prefer-source
101+
# And maybe also:
102+
composer dump-autoload
103+
php artisan ide-helper:generate
104+
```
105+
106+
---
107+
108+
## Helpers and Polyfills
109+
110+
To support `base_path()` and `app_path()` in both Laravel and standalone mode:
111+
- Polyfills are provided in `src/helpers.php`.
112+
- Registered in `composer.json` under `autoload.files`.
113+
114+
---
115+
116+
## Useful Commands
117+
118+
- `php artisan route:docs` — show documented routes
119+
- `php artisan route:docs:validate` — validate attribute/route consistency
120+
- `composer test` — run all tests
121+
122+
---
123+
124+
## Notes
125+
126+
- The `examples/Http/Controllers` folder contains real attribute usage for demo and test purposes.
127+

‎Dockerfile‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
ARG PHP_VERSION=8.1
2+
FROM php:${PHP_VERSION}-cli
3+
4+
# Install dependencies
5+
RUN apt-get update && apt-get install -y \
6+
git zip unzip curl libzip-dev
7+
8+
# Install Composer &...
9+
# Can install >100 PHP extensions
10+
# See: https://github.com/mlocati/docker-php-extension-installer
11+
ADD https://github.com/mlocati/docker-php-extension-installer/releases/latest/download/install-php-extensions /usr/local/bin/
12+
RUN chmod +x /usr/local/bin/install-php-extensions && sync
13+
RUN install-php-extensions @composer xdebug
14+
15+
WORKDIR /app

‎README.md‎

Lines changed: 61 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,62 @@
1-
# laravel-route-docs
1+
# Laravel Route Docs
2+
3+
[![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)
4+
[![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)
5+
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](LICENSE)
6+
27
A Laravel package that uses PHP attributes to document routes, generate readable route listings, and export OpenAPI or Postman definitions.
8+
9+
---
10+
11+
## Features
12+
13+
- Document routes directly using PHP attributes
14+
- Validate route documentation in your CI/CD pipeline
15+
- Includes CLI tooling for discovery and inspection
16+
17+
### TODO:
18+
- Add request parameters
19+
- Add response schemas
20+
- Export route definitions as JSON, OpenAPI, or Postman collections
21+
22+
---
23+
24+
## Installation
25+
26+
```bash
27+
composer require mikegarde/laravel-route-docs --dev
28+
```
29+
30+
## Usage
31+
Annotate your controller methods using custom attributes to describe your API:
32+
33+
```php
34+
use RouteDocs\Attributes\get;
35+
36+
class ItemController
37+
{
38+
#[get('/items', name: 'items.index')]
39+
public function index()
40+
{
41+
return Item::all();
42+
}
43+
}
44+
```
45+
46+
Then run:
47+
48+
```bash
49+
php artisan route:docs
50+
```
51+
52+
You’ll get a structured view of your documented routes.
53+
54+
## Validate Route Attributes in CI/CD
55+
56+
You can validate that all routes have correct and complete attribute annotations:
57+
58+
```bash
59+
php artisan route:docs:validate
60+
```
61+
62+
This will return non-zero exit codes on failure, making it CI-friendly.

‎Taskfile.dist.yml‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
version: '3'
2+
3+
vars:
4+
DEFAULT_PHP: '8.1'
5+
6+
tasks:
7+
default:
8+
silent: true
9+
cmds:
10+
- task --list
11+
- echo ""
12+
- echo -e "\033[34mGet more details by running \033[36mtask --summary [COMMAND]\033[0m"
13+
14+
build:
15+
vars:
16+
PHP_VERSION: '{{.DEFAULT_PHP}}'
17+
desc: Build the Docker image for PHP development
18+
cmds:
19+
- task: build:{{.PHP_VERSION}}
20+
build:*:
21+
vars:
22+
PHP_VERSION: '{{index .MATCH 0}}'
23+
cmds:
24+
- docker compose down
25+
- rm -f composer.lock
26+
- docker compose build --build-arg PHP_VERSION={{.PHP_VERSION}}
27+
- docker compose up -d
28+
- docker compose exec php composer install --no-interaction --prefer-dist
29+
30+
test:unit:
31+
desc: Run tests inside the container
32+
cmds:
33+
- docker compose run --rm php composer test
34+
test:all:
35+
desc: Run all tests inside the container
36+
cmds:
37+
- |
38+
VERSIONS=("8.1" "8.2" "8.3" "8.4")
39+
for VERSION in "${VERSIONS[@]}"; do
40+
task build:$VERSION
41+
task test:unit
42+
done
43+
44+
ssh:
45+
desc: SSH into the PHP container
46+
cmds:
47+
- docker compose exec php bash

‎composer.json‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
{
2+
"name": "mikegarde/laravel-route-docs",
3+
"description": "A Laravel package that uses PHP attributes to document routes, generate readable route listings, and export OpenAPI or Postman definitions.",
4+
"type": "library",
5+
"license": "GPL-3.0-only",
6+
"authors": [
7+
{
8+
"name": "Mike Garde",
9+
"email": "[email protected]"
10+
}
11+
],
12+
"require": {
13+
"php": "^8.1",
14+
"illuminate/support": "^9.0|^10.0|^11.0|^12.0",
15+
"illuminate/console": "^9.0|^10.0|^11.0|^12.0"
16+
},
17+
"require-dev": {
18+
"phpunit/phpunit": ">=10.5",
19+
"orchestra/testbench": ">=8.18"
20+
},
21+
"autoload": {
22+
"psr-4": {
23+
"RouteDocs\\": "src/"
24+
},
25+
"files": [
26+
"src/helpers.php"
27+
]
28+
},
29+
"autoload-dev": {
30+
"psr-4": {
31+
"Examples\\Http\\Controllers\\": "examples/",
32+
"Tests\\": "tests/"
33+
}
34+
},
35+
"extra": {
36+
"laravel": {
37+
"providers": [
38+
"RouteDocs\\RouteDocsServiceProvider"
39+
]
40+
}
41+
},
42+
"keywords": [
43+
"laravel",
44+
"routes",
45+
"route docs",
46+
"api docs",
47+
"openapi",
48+
"postman",
49+
"attribute",
50+
"annotation",
51+
"cli",
52+
"developer tools"
53+
],
54+
"minimum-stability": "stable",
55+
"prefer-stable": true,
56+
"scripts": {
57+
"test": [
58+
"phpunit"
59+
],
60+
"post-autoload-dump": [
61+
"Illuminate\\Foundation\\ComposerScripts::postAutoloadDump"
62+
]
63+
}
64+
}

0 commit comments

Comments
 (0)