PHPackages                             dgtlss/atlas - 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. [Parsing &amp; Serialization](/categories/parsing)
4. /
5. dgtlss/atlas

ActiveLibrary[Parsing &amp; Serialization](/categories/parsing)

dgtlss/atlas
============

Expose selected Laravel routes as agent-readable Markdown and JSON without changing their HTML behavior.

v1.0.0(1w ago)20MITPHPPHP ^8.1CI passing

Since Mar 15Pushed 1w agoCompare

[ Source](https://github.com/dgtlss/atlas)[ Packagist](https://packagist.org/packages/dgtlss/atlas)[ RSS](/packages/dgtlss-atlas/feed)WikiDiscussions main Synced today

READMEChangelog (1)Dependencies (7)Versions (2)Used By (0)

Atlas
=====

[](#atlas)

Expose selected Laravel routes as agent-readable Markdown and JSON without rewriting the controller or Blade view that already powers the browser experience.

Install
-------

[](#install)

```
composer require dgtlss/atlas
```

Publish the config if you want to customize negotiation, headers, metadata, or cache behavior:

```
php artisan vendor:publish --tag=atlas-config
```

Compatibility
-------------

[](#compatibility)

AtlasPHPLaravel1.0.x8.1+10.x, 11.x, 12.x1.0.x8.4+13.x provisionalLaravel 13 stays declared in package metadata, but it should be treated as provisional until the stable framework release can be validated in CI without the experimental flag.

Quick Start
-----------

[](#quick-start)

```
use Illuminate\Support\Facades\Route;

Route::get('/docs/getting-started', fn () => view('docs.getting-started'))
    ->name('docs.show')
    ->atlas();
```

HTML stays the default response for browsers. Atlas only transforms the response when the route is explicitly opted in and the request asks for a supported machine-readable format:

```
curl -H "Accept: text/markdown" https://example.com/docs/getting-started
curl -H "Accept: application/json" https://example.com/docs/getting-started
curl "https://example.com/docs/getting-started?atlas=markdown"
```

Stable v1 Surface
-----------------

[](#stable-v1-surface)

- Route macro: `->atlas(array $options = [])`
- Middleware alias: `atlas`
- Contracts:
    - `Dgtlss\Atlas\Contracts\MarkdownTransformer`
    - `Dgtlss\Atlas\Contracts\JsonTransformer`
    - `Dgtlss\Atlas\Contracts\AtlasPresenter`

Route Options
-------------

[](#route-options)

```
Route::get('/knowledge-base/{article}', ShowArticleController::class)->atlas([
    'formats' => ['markdown', 'json'],
    'presenter' => App\Atlas\ArticlePresenter::class,
    'cache' => ['ttl' => 900, 'vary' => ['locale']],
    'metadata' => ['section' => 'knowledge-base'],
    'query_parameter' => 'format',
    'markdown_transformer' => App\Atlas\CustomMarkdownTransformer::class,
    'json_transformer' => App\Atlas\CustomJsonTransformer::class,
]);
```

Supported route options in v1:

OptionTypeDefaultPurpose`formats``array``['markdown', 'json']`Restrict which transformed formats a route will serve.`presenter``class-stringnull``null``cache``boolintarray``metadata``array``[]`Merge route-specific metadata into transformed responses.`query_parameter``stringfalse`config value`markdown_transformer``class-string`config valueOverride Markdown generation for a route.`json_transformer``class-string`config valueOverride JSON generation for a route.Negotiation Rules
-----------------

[](#negotiation-rules)

Atlas only transforms routes that explicitly opt in with `->atlas()`.

Negotiation precedence in v1 is:

1. Query parameter override, if enabled globally and for the route.
2. `Accept` header negotiation for the formats allowed on that route.
3. Fall back to the original HTML response.

Examples:

```
curl "https://example.com/docs/getting-started?atlas=json"
curl "https://example.com/docs/getting-started?format=markdown"
curl -H "Accept: application/json" https://example.com/docs/getting-started
```

Presenter Contract
------------------

[](#presenter-contract)

Presenters take precedence over the generic HTML transformers when you need precise structured output.

```
namespace App\Atlas;

use Dgtlss\Atlas\Contracts\AtlasPresenter;
use Dgtlss\Atlas\Support\AtlasContext;

class ArticlePresenter implements AtlasPresenter
{
    public function toMarkdown(AtlasContext $context): string
    {
        return "# {$context->title()}\n\nCustom article body";
    }

    public function toJson(AtlasContext $context): array
    {
        return [
            'title' => $context->title(),
            'url' => $context->url(),
            'content' => 'Custom article body',
            'summary' => 'Custom summary',
            'headings' => [],
            'metadata' => $context->metadata(),
        ];
    }
}
```

Response Shape
--------------

[](#response-shape)

Markdown responses can include frontmatter-style metadata, followed by the transformed page body:

```
---
title: "Atlas Docs"
url: "https://example.com/docs/getting-started"
metadata: {"section":"docs"}
---

# Atlas Docs
```

JSON responses use these stable top-level keys:

```
{
  "title": "Page title",
  "url": "https://example.com/docs/getting-started",
  "content": "Markdown-friendly readable content",
  "summary": "Short summary",
  "headings": [
    {
      "level": 1,
      "text": "Getting started",
      "id": "getting-started"
    }
  ],
  "metadata": {
    "section": "docs"
  }
}
```

Config Defaults
---------------

[](#config-defaults)

Published config defaults:

```
return [
    'enabled' => true,
    'allowed_environments' => null,
    'default_formats' => ['markdown', 'json'],
    'negotiation' => [
        'accept_header' => true,
        'allow_query_parameter' => true,
        'query_parameter' => 'atlas',
    ],
    'metadata' => [
        'include_frontmatter' => true,
        'defaults' => [],
    ],
    'headers' => [
        'canonical' => true,
        'source_url' => true,
    ],
    'cache' => [
        'enabled' => false,
        'store' => null,
        'ttl' => 600,
        'vary' => ['locale'],
    ],
];
```

Important config behaviors:

- `enabled`: disables Atlas globally while leaving your original routes untouched.
- `allowed_environments`: restricts transformation to specific app environments.
- `cache.vary`: cache keys vary by route, format, and the configured dimensions such as `locale` or `user`.
- `metadata.include_frontmatter`: controls whether Markdown responses prepend frontmatter-style metadata.
- `headers.canonical` and `headers.source_url`: add canonical/source attribution headers to transformed responses.

Fallback Behavior
-----------------

[](#fallback-behavior)

- Atlas only transforms routes that explicitly call `->atlas()`.
- Existing auth and authorization still run before transformation.
- Redirects, downloads, binary responses, and streamed responses fall back to their original response in v1.
- Successful non-HTML responses also fall back to their original response unless a presenter is explicitly configured.
- Unsupported or disallowed requested formats fall back to the original route response.

Headers and Caching
-------------------

[](#headers-and-caching)

Transformed responses preserve the original successful status code and copy through existing headers and cookies where possible. Atlas adds:

- `X-Atlas-Format`
- `X-Atlas-Source-URL` when enabled
- `Link: ; rel="canonical"` when enabled

If caching is enabled, Atlas stores transformed payloads per route and format, then further varies them by the configured cache dimensions.

v1 Guarantees and Non-Goals
---------------------------

[](#v1-guarantees-and-non-goals)

Atlas 1.0 guarantees:

- explicit route opt-in
- original route/controller execution before transformation
- Markdown and JSON outputs only
- presenter precedence over generic HTML transformation
- fallback to the original response for unsupported response types

Atlas 1.0 does not aim to provide:

- perfect conversion of highly interactive layouts
- deep client-rendered SPA extraction
- additional machine-readable formats beyond Markdown and JSON

Development
-----------

[](#development)

See [CONTRIBUTING.md](./CONTRIBUTING.md) for local testing and CI-lane commands.

###  Health Score

39

—

LowBetter than 87% of packages

Maintenance98

Actively maintained with recent releases

Popularity3

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity42

Maturing project, gaining track record

 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.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

9d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/f86c3be8ba6d2b7a1fce05177ef066b040564e52cc0415a50ff259906b62f133?d=identicon)[dgtlss](/maintainers/dgtlss)

---

Top Contributors

[![dgtlss](https://avatars.githubusercontent.com/u/32520453?v=4)](https://github.com/dgtlss "dgtlss (4 commits)")

---

Tags

agentagentsaiai-agentsatlasjsonlaravellaravel-packagellmmarkdownmiddlewarephproute-macrojsonlaravelroutesaimarkdownAgentatlasai-seo

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/dgtlss-atlas/health.svg)

```
[![Health](https://phpackages.com/badges/dgtlss-atlas/health.svg)](https://phpackages.com/packages/dgtlss-atlas)
```

###  Alternatives

[sbsaga/toon

🧠 TOON for Laravel — a compact, human-readable, and token-efficient data format for AI prompts &amp; LLM contexts. Perfect for ChatGPT, Gemini, Claude, Mistral, and OpenAI integrations (JSON ⇄ TOON).

589.9k](/packages/sbsaga-toon)[grazulex/laravel-atlas

Laravel Atlas scans your Laravel project to generate a complete, structured map of its internal components — models, controllers, routes, jobs, observers, events, commands, and more — and exports visual or machine-readable representations in formats like Mermaid, Markdown, JSON, or PDF.

151.4k](/packages/grazulex-laravel-atlas)[json-mapper/laravel-package

The JsonMapper package for Laravel

25160.6k3](/packages/json-mapper-laravel-package)[xetaio/xetaravel-editor-md

A wrapper to use Editor.md with Laravel.

232.7k](/packages/xetaio-xetaravel-editor-md)

PHPackages © 2026

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