Docs/3.0 accuracy pass - #23
Merged
Merged
Conversation
Reviewed every page in src/3.0 against the UnoPim 3.0 source and fixed
what did not match. The changes fall into a few groups.
Documented software that does not exist:
- Removed agentic/mcp-server.md and agentic/extending-mcp.md. There is no
Webkul\MCP package, no BaseMcpTool, no ToolRegistry under that
namespace and no MCP_* config keys anywhere in the repository. Every
surviving reference in the agentic section was rewritten around the
interfaces that do exist, which meant reworking index.md and rebuilding
five of the eight recipes on real agent tool names.
- Removed the `unopim:translate` section; the command is not registered.
- Removed thirteen `core()` helpers from advanced/helpers.md
(convertPrice, getExchangeRate, states, isCountryRequired, …). They are
eCommerce leftovers with no counterpart in Core.php.
- Removed the media.images, media.videos and quantity-changer components,
which 3.0 deleted, and documented media.image and media.gallery with
their real props.
Instructions that would fail if followed:
- plugins/create-plugin.md registered the service provider in
config/app.php's providers array, which Laravel 11 removed. A plugin
built from that page never loads.
- The Nginx vhosts in web-server-configuration.md and the three OS guides
put the static-file rule ahead of the front controller, so /cache/
thumbnails and /p/{uuid}/carrier.svg 404. Added the guards the shipped
dockerfiles/nginx.conf already has, plus its PHP-handler hardening.
- installation-docker.md advertised admin123 as the Docker password. The
seeder generates a random one and writes it to
storage/app/admin-credentials.txt.
- The worker command omitted the webhooks and publication queues, so
deliveries and passport publishing queued up unprocessed.
- CACHE_DRIVER and ELASTICSEARCH_PORT are dead variables; the installer
expects host:port in ELASTICSEARCH_HOST.
- Both installers listed prompts that no longer match Installer.php and
omitted the Elasticsearch block entirely.
- Repository examples used Input::all(), removed in Laravel 6.
Conventions the docs contradicted:
- routes.php used ['web', 'admin']; every core route group uses ['admin'].
- validation.md taught inline $request->validate(); rewritten
FormRequest-first.
- The wk_ prefix was stated as fact; DB_PREFIX defaults to empty.
- Menu and ACL examples hardcoded English labels.
- Migrations were said to live in Database/Migration/ (singular).
Missing reference material:
- Added api/passports.md, api/association_types.md and
api/variant_structures.md. The passport endpoints were reachable only
through a dead anchor; the other two arrived with the catalog routes.
- Documented swatch upload, configurable-product delete, the delta-sync
filters and cursor parameters, and the product associations block.
- architecture/packages.md documented FPC, removed in 3.0, and omitted
six real packages; the list now matches packages/Webkul exactly.
Every artisan command, Webkul class, Blade component, env var, config
key, table and route named in the docs was verified against source.
The pagination envelope documented in `api/explanation.md` was wrong: it described `data`/`links`/`meta`, but `ApiDataSource::responseFormatData()` returns the counters at the top level next to a four-URL `links` object and emits no `meta` at all. The page now matches, and documents the `pagination_type=search_after` cursor mode it never mentioned. Passports are the one exception — they go through a Laravel resource collection and really do return `links`/`meta` — so that page now warns against sharing a pagination parser with the rest of the API. The association-type and variant-structure examples were missing the envelope entirely; both now show what the endpoints return. Product associations are asymmetric by design: a request identifies the linked product with `sku`, a response returns `related_sku`. Saying "the same structure" hid that. The Nginx dot-file deny also swallowed `/.well-known/acme-challenge/`, breaking Let's Encrypt HTTP-01 renewal. An allow rule now precedes it in all four vhosts, not only the one the review flagged.
The switcher's regex listed every release except 3.0, so on a 3.0 page it matched nothing and dropped the rest of the path: picking 2.1 navigated to /2.1/, which has no index page. Match versions generically, and fall back to a version's landing page when the current page does not exist there.
There was a problem hiding this comment.
Pull request overview
Documentation accuracy pass for the UnoPim v3.0 docs set, aligning guides with the current platform stack (Laravel 13 / PHP 8.4), updated admin/API behavior, and revised agentic tooling. It also improves cross-version navigation behavior in the VitePress theme to avoid version-switch 404s.
Changes:
- Update v3.0 operational docs (queues, web servers, install/update steps, env vars) to match current runtime behavior.
- Expand/normalize v3.0 REST API reference (new endpoints + client migration guidance; pagination/rate-limit semantics).
- Refresh developer/package/plugin docs to reflect updated UnoPim conventions (translations, routes middleware, Blade layouts/components, repository namespaces).
Reviewed changes
Copilot reviewed 87 out of 87 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| src/3.0/prologue/upgrade-guide.md | Clarifies queue requirements and URL changes for 2.1 → 3.0 upgrades |
| src/3.0/prologue/release-notes.md | Expands v3.0 feature/fix highlights and links |
| src/3.0/prologue/patch-update.md | Updates patch-update checklist for 3.0.x and Docker stack split |
| src/3.0/prologue/index.md | Adds “In This Section” navigation and wording tweaks |
| src/3.0/prologue/contribution-guide.md | Updates contributor workflow (Pint/Pest/Larastan/translations/Playwright) |
| src/3.0/plugins/index.md | Updates plugin config file naming examples |
| src/3.0/plugins/create-plugin.md | Moves provider registration guidance to bootstrap/providers.php |
| src/3.0/plugins/create-import-profile.md | Renames importer config example to importers.php |
| src/3.0/plugins/create-export-profile.md | Renames exporter config example + translation-key guidance |
| src/3.0/plugins/add-side-menu.md | Requires translation keys for menu labels |
| src/3.0/packages/views.md | Updates Laravel doc link + admin Blade layout example |
| src/3.0/packages/validation.md | Reorients validation guidance around FormRequests and core conventions |
| src/3.0/packages/swatch-types.md | Generalizes swatch intro + updates table names |
| src/3.0/packages/store-data-through-repositories.md | Updates repository namespace/folder naming + request validated() examples |
| src/3.0/packages/routes.md | Documents ['admin'] middleware-only requirement |
| src/3.0/packages/localization.md | Adds translation-check modes + “Custom” AI provider row |
| src/3.0/packages/layouts.md | Expands admin layout guidance + with-history usage |
| src/3.0/packages/index.md | Updates package structure (system_settings.php, locale directories) |
| src/3.0/packages/history.md | Updates with-history snippet and explanation (needs correction) |
| src/3.0/packages/datagrid.md | Fixes examples (permissions gating, primary key, route typos) |
| src/3.0/packages/data-transfer.md | Updates Data Transfer section positioning + v3.0 additions |
| src/3.0/packages/create-models.md | Updates Laravel doc link + SwiftMailer → Symfony Mailer |
| src/3.0/packages/create-migrations.md | Updates Laravel doc link |
| src/3.0/packages/create-acl.md | Switches ACL name values to translation keys + optimize:clear |
| src/3.0/packages/controllers.md | Updates Laravel doc link + repository namespace example |
| src/3.0/packages/configurable-associations.md | Updates validator signature reference |
| src/3.0/packages/bundling-assets.md | Updates tooling versions + adds @vitejs/plugin-vue guidance |
| src/3.0/packages/blade-components.md | Adds component index + updates links and examples |
| src/3.0/packages/add-menu-in-admin.md | Requires translation keys for menu labels |
| src/3.0/introduction/web-server-configuration.md | Improves Nginx/Apache rules for dynamic routes + upload hardening |
| src/3.0/introduction/requirements.md | Updates PHP/Redis/env var guidance and recommended limits |
| src/3.0/introduction/queue-scheduler-setup.md | Updates queue list, DB driver notes, and table names |
| src/3.0/introduction/installation.md | Updates composer steps + installer prompt wording + options tip |
| src/3.0/introduction/installation-with-postgresql.md | Updates install steps, prompts, PHP requirement, and wording |
| src/3.0/introduction/installation-ubuntu.md | Updates env var names + Elasticsearch host format + dynamic route handling |
| src/3.0/introduction/installation-docker.md | Replaces default admin creds with generated-credentials flow |
| src/3.0/introduction/installation-debian.md | Updates upload sizes, Elasticsearch host format, and Nginx rules |
| src/3.0/introduction/installation-centos.md | Updates upload sizes, Elasticsearch host format, and Nginx rules |
| src/3.0/introduction/index.md | Updates “What’s new” and AI provider list/count |
| src/3.0/architecture/repository-pattern.md | Updates Laravel doc link |
| src/3.0/architecture/packages.md | Adds/expands package entries; updates links and names |
| src/3.0/architecture/index.md | Refreshes modular architecture description and tool counts |
| src/3.0/architecture/frontend.md | Fixes reference link to internal Views doc |
| src/3.0/api/whats-new-v3.md | Adds client-migration link + new API surface references |
| src/3.0/api/variant_structures.md | New: REST reference for variant structures |
| src/3.0/api/product.md | Documents pagination changes + new associations block |
| src/3.0/api/passports.md | New: REST reference for Digital Product Passports |
| src/3.0/api/migrating-your-client.md | New: v2.x → v3.0 client migration guide (rate limits, errors, pagination) |
| src/3.0/api/media.md | Adds swatch upload + clarifies read/delete semantics |
| src/3.0/api/locales.md | Clarifies limit clamping |
| src/3.0/api/index.md | Adds “Coming from v2.x” pointer to migration guide |
| src/3.0/api/explanation.md | Updates pagination envelope explanation (needs correction) |
| src/3.0/api/currency.md | Corrects default limit docs |
| src/3.0/api/configuration.md | Updates integration ownership (robot user) and credential guidance |
| src/3.0/api/configurable_products.md | Fixes configurable-products links + adds delete endpoint |
| src/3.0/api/channel.md | Adds query parameter documentation |
| src/3.0/api/category.md | Adds limit param + filter operator details |
| src/3.0/api/category_fields.md | Adds filters param documentation |
| src/3.0/api/category_field_options.md | Adds delete behavior notes |
| src/3.0/api/authenticate.md | Adds token rate limit guidance + token invalidation note |
| src/3.0/api/attribute.md | Clarifies limit clamping |
| src/3.0/api/attribute_options.md | Adds swatch keys info + delete caveats |
| src/3.0/api/attribute_groups.md | Adds limit/filters docs + example |
| src/3.0/api/attribute_families.md | Adds limit/filters docs + example |
| src/3.0/api/association_types.md | New: REST reference for configurable association types |
| src/3.0/agentic/recipes.md | Updates recipes to remove MCP references + align tool naming |
| src/3.0/agentic/mcp-server.md | Removes MCP Server page from v3.0 docs |
| src/3.0/agentic/magic-ai-platform.md | Updates MagicAI architecture to laravel/ai SDK references |
| src/3.0/agentic/index.md | Reframes agentic tooling pillars (AI Agent + Skills + REST) |
| src/3.0/agentic/extending-mcp.md | Removes MCP bridge extension page from v3.0 docs |
| src/3.0/agentic/building-integrations.md | Updates integration walkthrough to remove MCP dependency |
| src/3.0/agentic/building-agent-tools.md | Updates custom tool authoring to laravel/ai Tool API |
| src/3.0/agentic/ai-agent.md | Updates AI Agent docs (tool count, laravel/ai, error resolver) |
| src/3.0/agentic/agent-skills.md | Updates conventions (DB_PREFIX, migrations path, pipeline steps) |
| src/3.0/advanced/security-practice.md | Generalizes security section wording (needs tool-count fix) |
| src/3.0/advanced/render-event.md | Updates examples to Blade + adds listener payload guidance |
| src/3.0/advanced/queue-management.md | Updates baseline worker queue list |
| src/3.0/advanced/override-core-model.md | Fixes override example namespaces and paths |
| src/3.0/advanced/index.md | Updates agentic section reference (removes MCP mention) |
| src/3.0/advanced/helpers.md | Removes several helper subsections |
| src/3.0/advanced/events.md | Updates Laravel doc link + example namespaces/listeners |
| src/3.0/advanced/elasticsearch-configuration.md | Generalizes “v2.0.0 improvements” phrasing |
| src/3.0/advanced/digital-product-passport.md | Adds REST API pointer |
| src/3.0/advanced/cli-commands.md | Updates command flags + worker queue list |
| .vitepress/version-configs/3.0.ts | Updates sidebar (removes MCP pages; adds new API pages) |
| .vitepress/theme/pages.data.mts | New: content loader for known page URLs for version switcher |
| .vitepress/theme/components/VersionSelect.vue | Adds known-page existence check + safe version switching |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| # Response Structure Explained | ||
|
|
||
| Every paginated response in this API shares the same shape, and this page walks you through it. Once you understand the three top-level keys — `data`, `links`, and `meta` — you can navigate any list endpoint. | ||
| Every paginated response in this API shares the same shape, and this page walks you through it. Once you understand the top-level keys — `data`, `current_page`, `last_page`, `total`, and `links` — you can navigate any list endpoint. |
Comment on lines
+126
to
129
| UnoPim includes significant API security hardening: | ||
|
|
||
| - **Full ACL enforcement on all API routes**: All 48 API routes now have proper ACL authorization checks. 15 previously unprotected routes have been fixed to require appropriate permissions. | ||
| - **ACL authorization on AI Agent tools**: All 32 AI Agent tools enforce permission checks via the `ChecksPermission` trait, ensuring that AI-driven operations respect the same role-based access controls as manual actions. |
Comment on lines
+74
to
+78
| <x-admin::layouts.with-history :history-id="$attributeFamily->id"> | ||
| <x-slot:entityName> | ||
| attributeFamily | ||
| </x-slot> | ||
|
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.