Skip to content

Conventional layout and wiring, richer API, full reference docs - #11

Merged
imanimanyara merged 4 commits into
mainfrom
docs/rich-api-and-docs
Nov 10, 2026
Merged

imanimanyara merged 4 commits into
mainfrom
docs/rich-api-and-docs

Conversation

@imanimanyara

Copy link
Copy Markdown
Member

Summary

Makes the package conventional Laravel, gives headless consumers a richer API, and documents all of it.

  • Rich API: many, setMany, forgetMany, missing, remember, all and definitions on the settings handle, plus a namespaced settings() helper in helpers/helpers.php.
  • Docs: full PHP and REST references, plus events, exceptions, commands and configuration, and seven headless recipes. Guards fail when a method, route, event, exception, command or config key is undocumented.
  • Layout:
    • routes/api.php, declared by hand in named, nested groups. The prefix, version and name prefix are declared once in the provider. The per-group switches are plain ifs.
    • routes/web.php, which holds no routes.
    • resources/lang/en/settings.php, resources/views/mail/alert.blade.php and resources/assets/.
  • Prefix: the default stays api/settings/v1; LARANAIL_SETTINGS_HTTP_PREFIX (or http.prefix) moves it, and an empty value mounts it at /v1.
  • Conventional rewrite:
    • Each action is injected directly.
    • One form request per write; JSON resources for responses.
    • Each exception carries its HTTP status and problem type.
    • Translations and config are read through Laravel's own APIs.
    • The provider dropped from 1,180 to 708 lines.

Removed (owner-approved; package never tagged)

  • The 19 deprecated class aliases, PruneOrphans::find() and DatabaseDefinitions::localised().
  • ApiRoutes, Capability, the OpenAPI generator and its command, FreshControllers.
  • The 7 action bundles.
  • BodyRequest, BodyInput, ListResponse, Messages, ConfigValues.
  • The 5 single-implementation contracts.

Every removal is recorded in .claude/design/settings/audits/deprecations.md.

Behaviour changes

  • Typed settings classes are bound from typed.classes at boot; an unlisted class now resolves without its stored values.
  • Missing translations fall back through Laravel's fallback_locale.
  • A config value of the wrong type throws.
  • The alert mail is rendered from a markdown view.

Verification (local)

  • Pest: 672 passed; coverage 96.8 %
  • PHPStan max, Rector, Pint and composer audit: clean
  • Full schema matrix: 4,609 passed

Copilot AI balanced review requested due to automatic review settings November 10, 2026 15:45

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

@imanimanyara
imanimanyara merged commit 90f0f31 into main Nov 10, 2026
15 checks passed
@imanimanyara
imanimanyara deleted the docs/rich-api-and-docs branch November 11, 2026 17:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants