Repository navigation
[MAINTENANCE] Encapsulate access to physical structure data - part 3 - #2267
Draft
beatrycze-volk wants to merge 14 commits into
Draft
beatrycze-volk wants to merge 14 commits into
beatrycze-volk wants to merge 14 commits into
Conversation
Direct access to the `physicalStructure` and `physicalStructureInfo` properties is now deprecated. Public getter methods, `getPhysicalStructure()` and `getPhysicalStructureInfo()`, have been introduced to provide a controlled API for retrieving this data, improving encapsulation. Accessing these properties directly via `__get()` will now trigger a deprecation warning, guiding developers to use the new public methods. All internal usages have been updated accordingly.
…nodes Introduce `getPhysicalStructureNode()` in `AbstractDocument` to centralize and standardize access to individual physical structure nodes by their ID. This new method replaces direct indexed access to the `physicalStructureInfo` array, improving encapsulation and providing a consistent way to handle missing nodes by returning an empty array. All internal usages have been updated accordingly.
Introduce `getPhysicalStructureNodeByPage()` to provide a direct way to retrieve physical structure metadata based on a page number. This new method encapsulates the previous two-step process of first resolving the physical structure ID from the `physicalStructure` array and then fetching the node using its ID. This change improves code readability and reduces redundancy across the codebase by consolidating a common lookup pattern. It also includes a minor refinement to `getPhysicalStructureNode()` to gracefully handle empty IDs.
Introduce `abstract protected function loadPhysicalStructure()` to centralize the format-specific logic for populating the document's physical structure. The `getPhysicalStructure()` method in `AbstractDocument` is now concrete, providing a consistent public interface that internally manages lazy loading by invoking `loadPhysicalStructure()` if the data is not yet available. This refactoring separates the concerns of *how* data is loaded (implemented by subclasses) from *when* it's loaded (managed by the abstract base class), reducing duplication and improving clarity in document type implementations. `getPhysicalStructureInfo()` also now utilizes this standardized loading mechanism.
Introduce dedicated methods like `getPhysicalStructureNodeFileByPage()` and `getPhysicalStructureNodeFilesByPage()` to encapsulate file retrieval from the document's physical structure. These methods provide direct access to file IDs by page or node ID, optionally filtered by a `fileGrp`'s `@USE` attribute. This refactoring replaces repetitive direct array access patterns (e.g., `['files']['DEFAULT']`), improving encapsulation, code readability, and reducing redundancy in consuming controllers.
Update `magicGetNumPages()` to directly invoke `loadPhysicalStructure()`. This ensures the method correctly utilizes the dedicated, format-specific loading mechanism introduced for populating the document's physical structure, rather than the public `getPhysicalStructure()` which now acts as a lazy loader.
Update `FullTextReader::getFromXml()` to directly accept a dedicated `files` array, simplifying its API by removing the need for the full physical structure node. Correspondingly, `IiifManifest` and `MetsDocument` are refactored to leverage the newly introduced encapsulated methods (`getPhysicalStructureNodeFiles()`, `getPhysicalStructureNodeFile()`, `getPhysicalStructureNodeFileByPage()`) for retrieving file information. This ensures consistent and encapsulated access to files for full text and thumbnail generation, aligning with the ongoing physical structure refactoring.
… in MetsDocument and PageGridController Update the `MetsDocument`'s `magicGetThumbnail()` method to leverage the newly introduced `getPhysicalStructureNodeFile()` and `getPhysicalStructureNodeFileByPage()` methods. This replaces direct array access with encapsulated file retrieval, aligning with ongoing physical structure refactoring for improved consistency and maintainability.
beatrycze-volk
added
the
⟳ maintenance
beatrycze-volk
marked this pull request as draft
November 13, 2026 11:15
This branch has not been deployed
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.
Depends on #2265