Doc Us Laravel Package

Getting Started

unisharp/doc-us is a schema-documentation generator: it introspects your MySQL database and renders human-readable docs (tables, columns, types, keys, comments, foreign keys). It documents the database as it actually exists, not your Eloquent models — which makes it useful precisely when models and migrations have drifted from reality.

Minimal path:

composer require unisharp/doc-us

Publish the package assets (config + views), then register the service provider if you're on a Laravel version without package auto-discovery:

php artisan vendor:publish --provider="Unisharp\DocUs\DocUsServiceProvider"

Then run the generator command and open the produced output. Check the README for the exact command name and the published config key names — this is a small, low-traffic package (37 stars), so verify the command signature against php artisan list rather than trusting a blog post:

php artisan list | grep -i doc
php artisan doc-us:generate   # verify name in README / artisan list

Where to look first: the published config file. That's where you control the DB connection, which tables are included/excluded, and where output lands. Everything else is cosmetic.

First use case: point it at an existing, undocumented production or legacy MySQL schema and generate a baseline document for onboarding, a schema review, or a client deliverable. It's also immediately useful on your own project — the generated column list is a fast way to spot tables you forgot existed (queue tables, pivot tables, soft-delete leftovers).

Implementation Patterns

Scope the output with an allow/deny list. The single most important config decision is excluding framework noise (migrations, sessions, cache, jobs, failed_jobs, password_reset_tokens, telescope_*, personal_access_tokens). If the config supports only/except table lists, use except for a broad project and only for a focused slice (e.g. documenting just the billing domain for a handoff).

Drive quality from migrations, not from the generator. The generator can only render what's in the schema. Two habits make the docs genuinely valuable:

Schema::create('invoices', function (Blueprint $table) {
    $table->id();
    $table->foreignId('customer_id')->constrained()->cascadeOnDelete();
    $table->string('number', 32)->comment('Human-facing invoice number, unique per tenant');
    $table->unsignedBigInteger('total_cents')->comment('Stored in minor units; currency in invoices.currency');
    $table->timestamps();
});

Column comments and real foreign-key constraints (->constrained()) are the difference between a useless column dump and a document someone actually reads. Polymorphic relations (morphTo) will never appear — no FK exists — so annotate those columns via comments.

Regenerate as part of a workflow, not by hand. Treat the docs as a build artifact:

• A Composer script or Make target (make docs) that runs the generator against a freshly migrated local DB.
• A CI job on main that regenerates and commits to a docs/ branch, or fails if the output differs — a schema diff in a PR is a surprisingly effective review prompt.
• A deploy hook on staging so the docs always reflect the deployed schema.

Multiple connections. For apps with a reporting/analytics connection, run the generator once per connection into separate output directories rather than trying to merge. The config's connection setting is the lever.

Pair with an ERD tool. This package is text/tabular, not graphical. Use it for the authoritative column reference and a separate tool (SchemaSpy, dbdiagram, MySQL Workbench) for the visual relationship map. They answer different questions.

Serving the output. Render into whatever docs pipeline you already have — copy into a Docusaurus/VuePress docs/ folder, publish to an internal wiki, or attach as a build artifact. If the package outputs HTML, keep the assets path consistent relative to the output directory so styles don't 404 when the docs are hosted elsewhere.

Gotchas and Tips

• MySQL only. It reads information_schema, so Postgres, SQLite, and SQL Server are out. That also means a SQLite-based test suite won't exercise the generator — test it against a real MySQL instance.
• DB user permissions. The configured user needs read access to information_schema and visibility of the target schema. A restricted app user with column-level grants can produce incomplete output.
• Config caching bites. Laravel caches config. After editing the published config, php artisan config:clear before regenerating, or you'll debug a change that "didn't apply."
• Stale docs are worse than no docs. If the docs are generated manually once, they will lie within a sprint. Automate or don't ship them.
• Large schemas. Hundreds of tables with wide columns can be slow and memory-hungry, and the generated output becomes unnavigable. Use the table filters aggressively; a 3-domain doc set beats one monolith.
• Type rendering edge cases. enum, set, json, and spatial columns often render as raw type strings without the allowed values. If those matter, document them in column comments.
• Views and generated columns may or may not be included depending on how the package filters information_schema.TABLES (BASE TABLE vs VIEW). Check your output before assuming they're covered.
• Laravel version drift. A small package with few stars is likely pinned to older illuminate/* constraints. If Composer resolution fails, check the package's composer.json before assuming your app is at fault; you may need to fork and relax constraints, or run it in a separate tooling container against the same database.
• It documents the DB, not the app. No model relations, no accessors, no observers, no validation rules. Don't present the output as API documentation — it's a schema reference.
• Extension point: the published views are the intended customization surface (branding, layout, extra sections). If you need derived data — e.g. row-count estimates or a "sensitive columns" flag — those are usually easiest to add by post-processing the generated output rather than patching the introspection layer, which keeps you upgrade-safe.