[Docs] Update and refine docs#1122
Open
fashxp wants to merge 15 commits into
Open
Conversation
Replace doc/04_Studio.md, a 298-line hand-maintained mirror of the Studio REST API, with doc/04_Studio_Integration.md. All Studio controllers are @internal and Studio serves generated OpenAPI docs at /pimcore-studio/api/docs, so the copy could only drift. It already had: it named the PHP constant PLUGIN_DATA_HUB_CONFIG as the permission (the value is plugin_datahub_config) and gave the prefix as /pimcore-studio/api/data-hub instead of /pimcore-studio/api/bundle/data-hub. The replacement keeps the permission model, the location of the generated API docs, and points at the public GraphQL endpoint /pimcore-graphql-webservices/{clientname}. Correct further content that no longer matched the source: - Deployment named the config directory var/config/data-hub. Migration Version20230329133119 renames it to var/config/data_hub, which is also the default in Configuration.php. - Deployment called datahub:graphql:rebuild-definitions "deprecated". The command was removed in 2.0.0; datahub:configuration:rebuild-workspaces replaces it. The upgrade notes named the replacement datahub:graphql:rebuild-workspaces, which never existed. - The upgrade notes gave the Studio endpoints as /studio/api/datahub/... - Basic Principle described the removed Admin Classic interface. The configuration panel now lives in Pimcore Studio under Automation & Integration > Data Hub Configuration. - Query samples linked to dead /admin/login/deeplink demo URLs. Document the permission resolution order from Configuration::isAllowed(): admin or plugin_datahub_admin always wins, otherwise a configuration's own permissions decide alone, otherwise the adapter permission decides. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019LmFQ3VND6uUqMpWsmppz6
configuration3.png showed the removed ExtJS Settings menu with a "Datahub Config" entry, contradicting the documented navigation path. Replace it with the Studio mega menu showing Automation & Integration > Data Hub Configuration. Replace add_config.png with the Studio adapter menu, which lists GraphQL, File Export, Productsup, Webhooks, Data Objects Importer, Simple REST and Headless Documents. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019LmFQ3VND6uUqMpWsmppz6
Recapture the core GraphQL configuration screens from Pimcore Studio on the public demo: the General, Schema Definition and Security Definition tabs, the field configuration dialog's operator overview, and the GraphQL Playground running a live query against the products endpoint. The previous images showed the removed ExtJS Admin Classic interface. The API key visible on the Security tab is masked. Replaced: general, schema, schema_add, security1, iexplorer, open_explorer and queryoperators_overview. Correct the config docs against the current UI: - The General tab no longer has an SQL Condition field. It was removed in Datahub 2.0.0, as the upgrade notes record. The General Settings page now lists Active, Type, Name, Description and Group. - The Security page documents the Generate Key button, the Datahub API Keys field, the Skip Permission Check and Disable Introspection toggles, and points the workspace-permissions link at the current Studio UI Users and Roles doc instead of a dead Pimcore 6.x URL. - The integrated tool is the GraphQL Playground, not GraphiQL. The README and the operators overview now describe the Playground and the field configuration dialog, whose operator tabs (Formatter, Transformer, Other) moved to the right panel. The public endpoint path shown in the Playground, /pimcore-graphql-webservices/products, confirms the endpoint documented in Studio Integration. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019LmFQ3VND6uUqMpWsmppz6
Recapture six query-sample screenshots by running each query in the GraphQL Playground against the demo's products config and screenshotting the live result: - manufacturer_listing (getManufacturerListing with paging and sort) - filtering (getManufacturerListing with a filter expression) - sample_parentChildrenSiblings (getCar parent, children, siblings) - many_to_many_object_relation (getCar categories relation) - asset_metadata (getAsset custom metadata) - asset_embeddedMetaInfo (getAsset embedded EXIF/IPTC info) The previous images showed the removed ExtJS GraphiQL interface. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019LmFQ3VND6uUqMpWsmppz6
The page described @internal Studio REST endpoints that Studio already documents itself at /pimcore-studio/api/docs, and duplicated the permission table from the installation chapter. It also documented none of the four pre-response events the bundle actually dispatches. Replace it with doc/05_Extending.md, which documents all four (configuration, configuration_detail, permission_user, thumbnail) and points to the much richer GraphQL event set. Keep the clarification that the API exposed to other systems is the GraphQL endpoint, not the Studio API, in the GraphQL chapter where readers look for it. Screenshots: replace the chapter hero (it was an Admin Classic composite) and the mutation schema grid with Pimcore Studio captures, and delete two images no page references. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019LmFQ3VND6uUqMpWsmppz6
An earlier batch had replaced Pimcore-side source screenshots with GraphiQL panes, which duplicated the query/response code blocks already on the page and dropped the annotations that carried the explanation. Recapture all twelve against the current Studio UI (2026.x) at 1440x900 with the side trees collapsed, matching what each page's prose describes: - general, schema_add, schema, security1, queryoperators_overview, open_explorer: the endpoint's General / Schema Definition / Security Definition tabs, the field configurator dialog (Class Attributes and Formatter panels, now distinct images), and the Schema Definition footer where the Playground opens. - asset_metadata / asset_embeddedMetaInfo: the Custom Metadata and Embedded Meta Info tabs of the exact assets the adjacent GraphQL examples query (asset 4 and asset 295). - filtering, manufacturer_listing, many_to_many_object_relation, sample_parentChildrenSiblings: the object grids and tree that the query samples read from, not a picture of the query itself. Mask the live Datahub API key on the Security Definition tab. The schema.png / schema_add.png byte-identical duplicate is resolved. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Accuracy fixes verified against source:
- Per-configuration permissions are read/update/delete only. The Permissions
tab grid renders exactly those three columns and Configuration::isAllowed()
is only ever called with them; PLUGIN_DATA_HUB_PERMISSION_CREATE is declared
but never used for configuration access ('create' exists only as a workspace
check).
- Document the role fallback accurately: an entry matching the user's own name
returns immediately, so roles are consulted only when the user has no entry,
and only a role that explicitly grants the permission counts
(Configuration.php:455-463).
- Note the automationIntegration.dataHubConfiguration perspective permission,
which also gates the navigation entry, and that the frontend permission only
hides the UI while #[IsGranted] protects the API.
- Operator groups: Formatter/Transformer/Other are registered on the query
registry only; the mutation registry registers Other alone.
- Remove sqlObjectCondition from the deployment sample. It was removed in 2.0.0
and no PHP reads it, which this branch already states elsewhere.
Admin Classic removal:
- Rewrite the frontend half of both Add a Custom Query/Mutation Operator pages.
They described writing ExtJS JS under src/Resources/public/js (deleted in
2026.1) and registering a pimcore.plugin.datahub.* namespace. Operators are
now Studio dynamic types extending DynamicTypeOperatorAbstract, registered
against the DataHub Query/Mutation operator registries. The PHP halves were
correct and are kept.
Links:
- Replace 12 absolute pimcore.com/docs.pimcore.com URLs with GitHub file URLs.
- Unlink 6 references to Pimcore 6.x pages that have no current equivalent
(Query Filters, Editable Naming Strategies, the TranslateValue grid
operator), keeping the prose. A dead 6.x link is worse than none.
Structure and style:
- Rename 05_Extending.md to 05_Customization.md for cross-bundle consistency.
- Descriptive alt text for configuration3.png, which shows the navigation menu
rather than a configuration overview.
- Drop a filler sentence and add a missing trailing newline.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The heading is 'Configuration Storage Locations and Fallbacks (LocationAwareConfigRepository)', so the anchor is #configuration-storage-locations-and-fallbacks-locationawareconfigrepository. Caught by a purged npm run build. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Modernizes Datahub documentation for Pimcore Studio and refreshes the generated Studio frontend bundle.
Changes:
- Refines installation, permissions, deployment, customization, and GraphQL guidance.
- Removes obsolete API documentation, demo links, and legacy references.
- Regenerates Studio assets under a new build identifier.
Reviewed changes
Copilot reviewed 37 out of 71 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
src/Resources/public/studio/build/e31abccc-0f0b-4902-ba7a-f84a94b97404/manifest.json |
Removes old build manifest. |
src/Resources/public/studio/build/e31abccc-0f0b-4902-ba7a-f84a94b97404/entrypoints.json |
Removes old entrypoints. |
src/Resources/public/studio/build/066991ef-dc72-4ec3-8fc0-dcc67df99d4b/static/js/remoteEntry.js.LICENSE.txt |
Adds dependency licenses. |
src/Resources/public/studio/build/066991ef-dc72-4ec3-8fc0-dcc67df99d4b/static/js/main.9c3ad8a2.js.LICENSE.txt |
Adds bundle license. |
src/Resources/public/studio/build/066991ef-dc72-4ec3-8fc0-dcc67df99d4b/static/js/async/840.b584be96.js.LICENSE.txt |
Adds chunk licenses. |
src/Resources/public/studio/build/066991ef-dc72-4ec3-8fc0-dcc67df99d4b/static/js/async/499.4aead98c.js.LICENSE.txt |
Adds chunk license. |
src/Resources/public/studio/build/066991ef-dc72-4ec3-8fc0-dcc67df99d4b/static/js/async/499.4aead98c.js |
Adds generated configuration chunk. |
src/Resources/public/studio/build/066991ef-dc72-4ec3-8fc0-dcc67df99d4b/static/js/async/__federation_expose_plugins.85a68c1a.js.LICENSE.txt |
Adds plugin chunk license. |
src/Resources/public/studio/build/066991ef-dc72-4ec3-8fc0-dcc67df99d4b/static/js/async/__federation_expose_plugins.85a68c1a.js |
Adds generated plugin export. |
src/Resources/public/studio/build/066991ef-dc72-4ec3-8fc0-dcc67df99d4b/static/js/async/__federation_expose_default_export.062d3a0b.js.LICENSE.txt |
Adds SDK chunk license. |
src/Resources/public/studio/build/066991ef-dc72-4ec3-8fc0-dcc67df99d4b/static/js/async/__federation_expose_default_export.062d3a0b.js |
Adds generated SDK export. |
src/Resources/public/studio/build/066991ef-dc72-4ec3-8fc0-dcc67df99d4b/static/js/109.62a4c31b.js.LICENSE.txt |
Adds runtime licenses. |
src/Resources/public/studio/build/066991ef-dc72-4ec3-8fc0-dcc67df99d4b/mf-stats.json |
Updates federation public path. |
src/Resources/public/studio/build/066991ef-dc72-4ec3-8fc0-dcc67df99d4b/mf-manifest.json |
Updates federation manifest path. |
src/Resources/public/studio/build/066991ef-dc72-4ec3-8fc0-dcc67df99d4b/manifest.json |
Adds new build manifest. |
src/Resources/public/studio/build/066991ef-dc72-4ec3-8fc0-dcc67df99d4b/main.html |
Updates generated script paths. |
src/Resources/public/studio/build/066991ef-dc72-4ec3-8fc0-dcc67df99d4b/exposeRemote.js |
Updates remote entry path. |
src/Resources/public/studio/build/066991ef-dc72-4ec3-8fc0-dcc67df99d4b/entrypoints.json |
Adds new entrypoint metadata. |
README.md |
Revises documentation links. |
doc/30_Testing.md |
Adds page metadata. |
doc/20_Deployment.md |
Corrects storage and deployment guidance. |
doc/10_GraphQL/README.md |
Updates GraphQL and Playground guidance. |
doc/10_GraphQL/10_Events.md |
Updates the events link. |
doc/10_GraphQL/08_Operators/README.md |
Revises operator UI instructions. |
doc/10_GraphQL/08_Operators/Query/TranslateValue.md |
Removes an obsolete link. |
doc/10_GraphQL/07_Mutation/27_Add_Custom_Mutations.md |
Updates event documentation link. |
doc/10_GraphQL/07_Mutation/26_Add_Custom_Mutation_Operator.md |
Documents Studio mutation operators. |
doc/10_GraphQL/07_Mutation/24_Mutation_Samples/15_Fieldcollection_Mutations.md |
Updates field collection link. |
doc/10_GraphQL/07_Mutation/20_DataObject_Mutations.md |
Updates datatype link. |
doc/10_GraphQL/07_Mutation/01_Document_Mutations.md |
Removes obsolete naming links. |
doc/10_GraphQL/04_Query/20_Add_Custom_Query.md |
Updates event documentation link. |
doc/10_GraphQL/04_Query/16_Add_Custom_Query_Operator.md |
Documents Studio query operators. |
doc/10_GraphQL/04_Query/11_Query_Samples/27_Sample_Translate_Values.md |
Removes stale demo link. |
doc/10_GraphQL/04_Query/11_Query_Samples/26_Sample_Get_Linked_Data.md |
Removes stale demo link. |
doc/10_GraphQL/04_Query/11_Query_Samples/24_Sample_Fieldcollections.md |
Removes stale demo link. |
doc/10_GraphQL/04_Query/11_Query_Samples/12_Sample_Asset_Metadata.md |
Removes stale demo link. |
doc/10_GraphQL/04_Query/11_Query_Samples/11_Sample_GetAsset.md |
Removes stale demo link. |
doc/10_GraphQL/04_Query/10_Filtering.md |
Revises filtering introduction. |
doc/10_GraphQL/04_Query/05_DataObject_Queries.md |
Updates datatype and filtering references. |
doc/10_GraphQL/04_Query/04_Asset_Queries.md |
Revises filtering reference. |
doc/10_GraphQL/01_Configuration/03_Security_Settings.md |
Expands endpoint security guidance. |
doc/10_GraphQL/01_Configuration/01_General_Settings.md |
Updates general settings documentation. |
doc/05_Customization.md |
Adds Studio event customization guidance. |
doc/04_Studio.md |
Removes internal Studio API documentation. |
doc/02_Basic_Principle.md |
Rewrites configuration overview. |
doc/01_Installation_and_Upgrade/README.md |
Expands prerequisites and permissions. |
doc/01_Installation_and_Upgrade/01_Upgrade_Notes.md |
Corrects routes and migration notes. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
The Studio UI string is currently 'Data Hub Configuration' (src/Resources/translations/studio.en.yaml), so this intentionally desyncs the prose from the UI label and the configuration3.png screenshot. Documentation spelling is 'Datahub' throughout; the product string should follow. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Both were annotated Admin Classic captures whose recapture dropped the explanation, so they are re-shot in Pimcore Studio at 1440x900 with the side panels collapsed and the annotation reproduced. manufacturer_listing.png The original was the Manufacturer grid sorted by Name with purple boxes on exactly the three rows a `limit 3, offset 1, sortBy: name` query returns. The previous recapture was sorted by ID, unannotated, and did not even include Aston Martin in frame, so it no longer showed anything the page claims. Now sorted by Name, with the box on Alfa Romeo (28), Aston Martin (240) and Austin-Healey (35). "Total 27 items" matches the documented totalCount. open_explorer.png The original had arrows on the two buttons that open the GraphQL Playground. The previous recapture was an unannotated Schema Definition tab showing no query, no response and no Playground, while the caption above it described writing a query. Studio now has a single `Open in tab` button in the panel footer, so the arrow points at that. The prose is corrected to match: this section is about opening the Playground, and the "write a query on the left" sentence moves up to iexplorer.png, which is the image that actually shows it. Descriptive alt text on all three. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The previous recapture left four unrelated widget tabs and an open element tab in the tab bar, which is noise the reader has to look past. Both are re-shot with only the tab the image is about open: - manufacturer_listing.png: only the Manufacturer tab - open_explorer.png: only the Data Hub Configuration tab Content is otherwise unchanged: 1440x900, side panels collapsed, grid sorted by Name with the box on Alfa Romeo / Aston Martin / Austin-Healey, and the arrow on the Open in tab button. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Accepted from the review on PR #1122, each verified against source: - The custom operator pages described a frontend extension path that is not actually available: DynamicTypeOperatorAbstract is not exported from assets/studio/js/src/sdk/index.ts, so another bundle's Studio plugin cannot import it. Both pages now carry a warning stating that, and mention the required `readonly id` member that was omitted. - Fix the Studio UI links. studio-ui-bundle has no 1.x branch and no doc/README.md; point at 2026.x/doc/04_Extending/01_Getting_Started_with_Your_First_Plugin.md. - Scope the permission claim. Controller/Studio/GraphQL/ExplorerController.php carries no #[IsGranted] (11 of 12 controllers do), so say the configuration-management API is enforced rather than implying every endpoint is. Rejected, with evidence: - "The left/right description is reversed" for the schema fields dialog. Opened the dialog on the demo and measured it: Available Fields is the left column (x=244), the operator icon strip sits at x~730, and Class Attributes is the right panel (x=775). The text was already correct. - "Link to the public platform documentation instead" for the five Further Information links. AGENTS.md mandates the GitHub file URL convention and explicitly forbids docs.pimcore.com, because the build rewrites and validates the former. Those four adapter repos are private, which is why they 404 when browsed; the published docs resolve them to relative links. - "The Data Importer installation page is doc/01_Installation.md". On the restructure branch it is a directory with a README.md, which is what the link targets. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
A Composer dependency is not an installed bundle. Spell out that the Studio Backend and Studio UI bundles must be enabled and installed in their own right. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011gNY3NwTbQPwco5wyWgpE8
|
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.