feat(support): add support for high level API#13
Draft
dieselxxx wants to merge 79 commits into
Draft
Conversation
…oxy" focus **Details:** - Rebranded the repository with a fresh header emphasizing the development of a high-level API for low-level proxy functionality. - Updated badge visuals: - Changed release badge to reflect "DEV" status with a green color scheme (`#66BB6A`) for clarity. - Updated version badge to indicate v0.3.0 progression. - Adjusted license badge to enhance styling and match the new design aesthetic. - Revised purpose section: - Dropped "Unstable Develop Branch" warnings in favor of a milestone-focused approach. - Clearly outlined the branch's goal to introduce reusable support classes (`Str`, `Collection`) to enhance productivity for string and collection manipulation. - Updated linked references: - Pointed commit activity, differences, and milestones to `feature/support-high-level-api` instead of the previous `develop`. - Added related milestone and pull request details for better contextual navigation. - Introduced dedicated "Purpose" and "Scope" sections to clearly delineate objectives. - Refined wording and structure for improved readability, focusing on community clarity and simplicity. This update reflects the repository's pivot to prioritizing internal utility abstraction while aligning visual components and descriptions with
…oxy" focus **Details:** - Rebranded the repository with a fresh header emphasizing the development of a high-level API for low-level proxy functionality. - Updated badge visuals: - Changed release badge to reflect "DEV" status with a green color scheme (`#66BB6A`) for clarity. - Updated version badge to indicate v0.3.0 progression. - Adjusted license badge to enhance styling and match the new design aesthetic. - Revised purpose section: - Dropped "Unstable Develop Branch" warnings in favor of a milestone-focused approach. - Clearly outlined the branch's goal to introduce reusable support classes (`Str`, `Collection`) to enhance productivity for string and collection manipulation. - Updated linked references: - Pointed commit activity, differences, and milestones to `feature/support-high-level-api` instead of the previous `develop`. - Added related milestone and pull request details for better contextual navigation. - Introduced dedicated "Purpose" and "Scope" sections to clearly delineate objectives. - Refined wording and structure for improved readability, focusing on community clarity and simplicity. This update reflects the repository's pivot to prioritizing internal utility abstraction while aligning
dieselxxx
added
priority: Normal
3 tasks
dieselxxx
added
status: In Progress
…oxy" focus **Details:** - Rebranded the repository with a fresh header emphasizing the development of a high-level API for low-level proxy functionality. - Updated badge visuals: - Changed release badge to reflect "DEV" status with a green color scheme (`#66BB6A`) for clarity. - Updated version badge to indicate v0.3.0 progression. - Adjusted license badge to enhance styling and match the new design aesthetic. - Revised purpose section: - Dropped "Unstable Develop Branch" warnings in favor of a milestone-focused approach. - Clearly outlined the branch's goal to introduce reusable support classes (`Str`, `Collection`) to enhance productivity for string and collection manipulation. - Updated linked references: - Pointed commit activity, differences, and milestones to `feature/support-high-level-api` instead of the previous `develop`. - Added related milestone and pull request details for better contextual navigation. - Introduced dedicated "Purpose" and "Scope" sections to clearly delineate objectives. - Refined wording and structure for improved readability, focusing on community clarity and simplicity. This update reflects the repository's pivot to prioritizing internal utility abstraction while aligning
**Details:** - Moved PSR-4 autoloading configuration from the `autoload-dev` section to the `autoload` section. - Ensures consistent loading behavior for the `FireHub\PHPStan` namespace in both development and production environments. This change improves autoloading setup, supporting better project organization and deployment alignment.
…actions for data structures
**Details:**
- **New Contracts Added:**
- Implemented foundational interfaces under `Core\Shared\Contracts`:
- `Countable`: Extends PHP's native `Countable` interface, standardizing object element counting.
- `Traversable`, `Iterator`, and `IteratorAggregate`: Provide base contracts for iterable and iterator behavior.
- Introduced `DataStructure` contract in `Core\Support\Contracts`:
- Serves as a unified, consistent abstraction for high-level data structures supporting type safety, iteration, and utility operations.
- **Shared Trait Introduced:**
- Added `Enumerable` trait for reusable iteration and transformation logic in data structures:
- Simplifies integration by reducing duplication in common operations like counting and sequential access.
- **Updates to Project Structure:**
- New files organized under `src/shared/contracts`, `src/support/contracts`, and `src/support/datastructure/traits`.
- Updated `CHANGELOG.md` to document these changes under the `Unreleased` section.
These additions establish the core framework for designing extensible and type-safe data structures, supporting cross-library consistency and improving developer productivity in the FireHub ecosystem.
…re implementations
**Details:**
- **New Contracts Added:**
- Introduced key interfaces under `Core\Shared\Contracts` and `Core\Support\Contracts`, including:
- `Arrayable`, `ArrayConvertable`, `DataStructure`, and `Collection`.
- Streamlined type-safe iteration and array conversion behaviors for core data structures.
- Standardized traversable interfaces (`Iterator`, `IteratorAggregate`, `Traversable`).
- Updated type variance annotations (`template-covariant TKey` to `template TKey`) across existing contracts for consistency.
- **Shared Traits Added:**
- Developed `Shared` and `Enumerable` traits for reusable functionality:
- `Shared` offers common data structure utilities (counting, conversion, iteration).
- `Enumerable` handles iteration and transformation logic, supporting extensibility in data structures.
- **Concrete Implementation Introduced:**
- Added `Collection`:
- Eager, array-based implementation of `DataStructure` designed for high-level manipulation of key-value data.
- Implements type-safe `fromArray` and `toArray` methods alongside iterator functionality.
- **Project Structure Updates:**
- Organized additions into `src/shared/contracts`, `src/support/contracts`, `src/support/datastructure`, and `src/support/datastructure/traits`.
- Simplified redundant code across multiple classes by centralizing shared logic into traits.
- **Changelog Update:**
- Documented the introduction of foundational contracts, shared traits, and high-level abstractions under the `Unreleased` section.
These updates establish the foundational framework for extensible, type-safe abstractions, paving the way for cohesive data structure utilities in the FireHub ecosystem.
…ovements, and serialization capabilities
**Details:**
- **Core Updates:**
- Simplified `$Id` version annotations in `FireHub.php` and `Builder.php` for cleaner metadata tracking.
- Enhanced exception handling by updating the `match` expression in the `boot` method:
- Replaced explicit exception `throw()` calls with direct `throw` expressions for improved readability and performance.
- Added context information (`key` and `value`) for `NotBootloaderException` to enrich debugging information.
- **Exception Builder Refactor:**
- Renamed `throw` method to `build` in `firehub.Builder`:
- Better aligns with its purpose of constructing exception objects without directly throwing them.
- Removed redundant `throw new` in favor of returning instances for flexibility in exception handling logic.
- **New Serializable Contracts:**
- Introduced high-level serialization abstractions under `Core\Shared\Contracts\Magic`:
- `Serializable`: Defines methods for generating and restoring object serialized data (`serialize`, `__serialize`).
- `SerializableConvertable`: Extends `Serializable` with methods for unserialization and data conversion (`unserialize`, `__unserialize`).
- **JSON Serialization Capability:**
- Added `JsonSerializable` and `JsonSerializableConvertable` interfaces for customizable JSON representations:
- `JsonSerializable` defines methods for JSON encoding (`toJson`, `jsonSerialize`) with flag support.
- `JsonSerializableConvertable` builds on JSON encoding with methods for object construction from JSON (`fromJson`).
This commit enhances FireHub's core abstractions with expanded exception handling, robust serialization contracts, and JSON-specific encoding, paving the way for richer extensibility and better runtime diagnostics.
**Details:**
- **Convertable Trait:**
- Introduced the `Convertable` trait, enabling reusable bidirectional data structure conversions to/from array, JSON, and serialized formats.
- Implemented methods for data serialization (`toJson`, `serialize`) and creation from serialized or JSON data (`fromJson`, `unserialize`).
- Includes exception handling for serialization errors, ensuring robustness in encoding/decoding logic.
- **Collection Class Enhancements:**
- Updated `Collection` to utilize the new `Convertable` trait, adding support for JSON and serialization:
- Implemented methods like `jsonSerialize` and `__serialize` for seamless integration with high-level functionality.
- Enhanced constructor to allow writable `protected(set)` storage property for improved encapsulation.
- Updated PHP version requirement to 8.4, leveraging modern language features.
- **Classmap and Changelog Updates:**
- Expanded the autoload classmap to include new contracts and traits (`Convertable`, `JsonSerializable`, `Magic\Serializable`, etc.).
- Documented the new trait and updated `Collection` functionality in the `CHANGELOG.md` under the "Added" section.
These changes enhance FireHub's core abstractions with versatile serialization capabilities, improving extensibility and compliance with modern PHP standards.
**Details:** - **Abstract Collection Base:** - Introduced `Abstract\Collection` as the foundational class for high-level data structures, centralizing iteration, transformation, and conversion logic. - Updated `Collection` to inherit from `Abstract\Collection` to streamline implementation and reduce redundancy. - **Iteration Enhancements:** - Added `each` method to data structures, enabling user-defined callback execution with control flow signals (`BREAK`, `CONTINUE`). - Introduced examples demonstrating `each` usage for custom iteration and early termination. - **Exception Refinements:** - Added `WrongReturnTypeException` to validate callback signal results and enforce stricter type safety. - **Namespace and Dependency Updates:** - Moved `FailedToLoadBootloaderException` and `NotBootloaderException` under `Support\Bootstrap` for consistent exception categorization. - Introduced enum `ControlFlow\Signal` to standardize control flow signals across the framework. - **Autoloading and Classmap Updates:** - Expanded classmap to include new abstractions, exceptions, and enums (`Abstract\Collection`, `ControlFlow\Signal`, etc.). - Updated compiled autoload definitions to reflect the extended file structure. With these changes, FireHub's data structure framework offers improved extensibility, type-safe iteration utilities, and a more modular organization.
…and Data Provider
**Details:**
- **Namespace Updates:**
- Renamed `FireHub\Tests\Unit\Domain\Autoload` namespace to `FireHub\Tests\Unit\Support` for consistency with the test directory structure.
- Adjusted relevant `@package` and file metadata annotations for clarity.
- **Classmap Refinement:**
- Removed unused classmap entries for `Collection2` and `Collection3` from `classmap.php` and `firehub.CompiledClassmap.php` to clean up and streamline the autoload definitions.
- **Shared Trait Enhancements:**
- Updated `each` method in `firehub.Shared` with additional exceptions:
- `WrongReturnTypeException` to enforce stricter validation of callback return signals.
- Generic `Throwable` contract for broader error handling.
- **New Unit Tests:**
- Added `CollectionTest` to test high-level features of the `Collection` data structure:
- Includes tests for `toArray`, JSON serialization, and object serialization/deserialization.
- Leverages modern PHPUnit features, such as `TestWith` attributes for parameterized testing.
- Incorporated a new data provider class (`DataStructureDataProvider`) for reusable data scaffolding in `CollectionTest`.
- **Miscellaneous:**
- Simplified `$Id` version annotations across modified files for cleaner metadata.
These changes improve test coverage, streamline autoload behavior, and enhance the modularity and maintainability of FireHub Core's unit testing and namespace organization.
… Transformable Capability, Update Tests **Details:** - **Class Renaming:** - Renamed `Collection` to `ArrayCollection` to better align with its array-based implementation and improve clarity across the framework. - **Abstract Base Class Updates:** - Updated `Abstract\Collection` to `Abstract\ArrayCollection`, ensuring consistent naming patterns for array-based data structures. - Refined docblocks and property descriptions to highlight array-backed design. - **New `Transformable` Contract:** - Introduced `Transformable` interface for functional transformation capabilities, including `map` method support. - Extended `ArrayCollection` and its abstract base to implement `Transformable` contract for consistent immutable-style transformations. - **Classmap and Autoloader:** - Adjusted `classmap.php` and `firehub.CompiledClassmap.php` to reflect renaming (`Collection` → `ArrayCollection`) and include the new `Transformable` contract. - Removed stale references to old naming. - **Unit Tests:** - Replaced `CollectionTest` with `ArrayCollectionTest` to test the renamed class. - Improved test cases for `map`, serialization, and JSON conversion functionality. - Enhanced `DataStructureDataProvider` to use `ArrayCollection`. - **Miscellaneous:** - Simplified `$Id` metadata annotations for better tracking. - Updated examples and docblocks in shared traits and implementations to reflect the renaming and new capabilities. These changes improve code clarity, introduce functional transformation utilities, and ensure tests fully align with the updated class structure.
…sistency **Detailed Description:** 1. **Introduction of `EmptyStructureException`:** - Created `EmptyStructureException` class for handling cases where a `DataStructure` is unexpectedly empty. - Includes a default message: "DataStructure is empty." 2. **Improvements to `WrongReturnTypeException`:** - Corrected typos and improved formatting in class description and the default exception message for clarity and consistency. - Updated: "Datastructure has retuned the wrong type." to "DataStructure has returned the wrong type." **Key Benefits:** - Establishes a dedicated exception for empty data structures, ensuring clearer and more precise error handling. - Enhances overall code quality and consistency in exception messaging.
…sistency **Detailed Description:** 1. **Introduction of `EmptyStructureException`:** - Created `EmptyStructureException` class for handling cases where a `DataStructure` is unexpectedly empty. - Includes a default message: "DataStructure is empty." 2. **Improvements to `WrongReturnTypeException`:** - Corrected typos and improved formatting in class description and the default exception message for clarity and consistency. - Updated: "Datastructure has retuned the wrong type." to "DataStructure has returned the wrong type." **Key Benefits:** - Establishes a dedicated exception for empty data structures, ensuring clearer and more precise error handling. - Enhances overall code quality and consistency in exception messaging.
… structure hierarchy **Detailed Description:** 1. **Introduction of `Enumerable` Interface:** - Added `Enumerable` interface to represent iterable data structures with a standardized contract for traversal. - Extends core `DataStructure` and `IteratorAggregate` contracts. - Improves type consistency across data structures and simplifies iteration handling. 2. **Addition of `Collection` Interface:** - Introduced `Collection` interface as an extension of `Enumerable`. - Designed for stateful, in-memory data structures with finite elements. - Serves as a base abstraction for diverse collection types (e.g., linear, associative, set-based). 3. **Classmap Enhancements:** - Updated `classmap` and `compiled classmap` to include `Enumerable` and `Collection` interfaces. - Ensures proper autoloading of new interfaces for seamless integration with the system. 4. **Refinements to `DataStructure`:** - Updated the `DataStructure` interface to redefine its purpose as a root abstraction for classifying and interacting with data structures. - Enhanced the documentation to clarify its role within the architectural boundaries. 5. **PHAR Regeneration:** - Regenerated `core.phar` and `core.min.phar` to incorporate the newly added interfaces and changes. **Key Benefits:** - Strengthens FireHub's modular data structure hierarchy with foundational contracts. - Simplifies future extension of enumerable and collection-based abstractions. - Improves autoloading efficiency and runtime consistency for enterprise environments.
…n documentation
**Detailed Description:**
1. **Introduction of `SizeException`:**
- Added `SizeException` class under `Throwable\Exception\DataStructure` namespace.
- Provides a dedicated exception for handling invalid data structure sizes with a default message: "DataStructure size is wrong."
2. **Mark `ErrorBuilder` and `ExceptionBuilder` as Internal:**
- Updated the class-level annotations for `firehub.ErrorBuilder` and `firehub.ExceptionBuilder` to mark them as `@internal`.
- Indicates these builders are not intended for external use, helping maintain proper encapsulation within the framework.
3. **Documentation Fixes:**
- Corrected a typo in `firehub.Resolver`:
- Updated "namespaces prefixes" to "namespace prefixes" for improved clarity.
**Key Benefits:**
- Adds a precise and context-specific exception for size-related errors in data structures.
- Strengthens encapsulation by designating builders as internal, limiting unintended external use.
- Improves documentation clarity, ensuring consistency and professionalism in the codebase.
**Detailed Description:**
1. **Namespace Adjustments:**
- Refactored namespaces for multiple exception classes:
- `WrongReturnTypeException`, `SizeException`, and `EmptyDataStructureException` updated from `Exception\DataStructure` to `Exception\Support\DataStructure`.
- Aligns with the logical organization under a more appropriate "Support" directory for better clarity and maintainability.
- Updated `InvalidValueObjectError` namespace from `Error\LowLevel` to `Error\ValueObject`, improving hierarchical alignment within the error structure.
2. **Documentation Updates:**
- Adjusted related comments and annotations to reflect the new namespace paths.
- Ensures consistency across the codebase for easier navigation and understanding.
3. **Improved Exception References:**
- Modified all references to the relocated `InvalidValueObjectError` for better contextual accuracy:
- Updated an instance in `Throwable\ValueObject\Firehub.Code` to reflect the correct path.
**Key Benefits:**
- Enhances overall code modularity and organizational structure by aligning namespaces with intended functionality.
- Improves long-term maintainability and ease of understanding for developers interacting with exception and error classes.
…constraints and improved annotations
**Detailed Description:**
1. **Stricter Argument Validation:**
- Added validation to ensure `start` and `end` parameters are of the same type.
- Throws `OutOfRangeError` if one parameter is a string and the other is not, with an appropriate error message.
2. **Improved Type Annotations and Templates:**
- Updated the method's parameter types to generic templates (`TStart`, `TEnd`, and `TStep`) for improved type hinting.
- Enhanced `@return` annotations with conditional types to specify the possible return value structures based on input types:
- Integer, float, or string sequences are correctly annotated depending on the input parameters.
3. **Inclusion of `DataIs::string()`:**
- Documented usage of `DataIs::string()` for type-checks to clarify its role in validating `start` and `end` inputs.
4. **Code Simplification:**
- Consolidated checks and exception handling for better readability and maintainability.
**Key Benefits:**
- Ensures stricter type safety and consistency for the `range` method.
- Reduces runtime errors and enhances developer understanding with more robust type annotations.
- Improves the reliability of sequence generation by explicitly handling edge cases like mismatched types.
…constraints and improved annotations
**Detailed Description:**
1. **Stricter Argument Validation:**
- Added validation to ensure `start` and `end` parameters are of the same type.
- Throws `OutOfRangeError` if one parameter is a string and the other is not, with an appropriate error message.
2. **Improved Type Annotations and Templates:**
- Updated the method's parameter types to generic templates (`TStart`, `TEnd`, and `TStep`) for improved type hinting.
- Enhanced `@return` annotations with conditional types to specify the possible return value structures based on input types:
- Integer, float, or string sequences are correctly annotated depending on the input parameters.
3. **Inclusion of `DataIs::string()`:**
- Documented usage of `DataIs::string()` for type-checks to clarify its role in validating `start` and `end` inputs.
4. **Code Simplification:**
- Consolidated checks and exception handling for better readability and maintainability.
**Key Benefits:**
- Ensures stricter type safety and consistency for the `range` method.
- Reduces runtime errors and enhances developer understanding with more robust type annotations.
- Improves the reliability of sequence generation by explicitly handling edge cases like mismatched types.
…tion **Detailed Description:** - Fixed a typographical error in the `OutOfRangeError` exception documentation: - Changed "bu not both" to "but not both." **Key Benefits:** - Improves code documentation accuracy and professionalism. - Enhances readability and understanding for developers working with the `range` method.
…bstraction contracts
**Detailed Description:**
1. **Removed `Enumerable` and `Collection` Interfaces:**
- Deprecated interfaces were removed to streamline the data structure hierarchy and eliminate redundancy in traversal contracts.
2. **Introduced Comprehensive Storage Capabilities:**
- Designed new interfaces under the `Storage\Capability` namespace to add extensible abstractions for specific data structure operations, including:
- `IndexAccess`, `NodeInsertAfter`, `NodeInsertBefore`, `NodeBidirectionalInsert`, `NodeRemoval`, `CyclicTraversal`.
- These capabilities enhance granularity and modularity in defining and implementing storage behaviors.
3. **Added Initialization Strategies:**
- Introduced concrete initializers `ArrCallbackInitializer` and `GeneratorCallbackInitializer` for dynamic and memory-efficient data generation, enabling greater flexibility in array and generator-based storage.
4. **Expanded `MutationOutcome` Enum:**
- Added `MutationOutcome` enum to standardize mutation operation results (e.g., `CREATED`, `UPDATED`, `REMOVED`, `NOT_FOUND`).
5. **Enhanced Exception Handling:**
- Included new custom exceptions and relocated existing ones for better organization:
- Updated paths for size, boundaries, and ownership-related exception classes under the `Support\DataStructure` namespace.
6. **Classmap Updates:**
- Comprehensive updates to the classmap for seamless autoloading of new capabilities, enums, initializers, and exceptions.
7. **Code Consistency Improvements:**
- Updated annotations, namespaces, and internal references for better adherence to the project's architectural style and clarity.
**Key Benefits:**
- Enhances modularity and scalability for data structure-related functionality.
- Adds robust and reusable abstractions for key storage operations.
- Improves memory efficiency and flexibility through dynamic initializers.
- Enhances exception granularity, improving error management and debugging clarity.
**Detailed Description:** 1. **Resolved Typographical Errors:** - Updated method name `testKeyExist` to `testKeyExists` to align with naming conventions. - Corrected static method call from `Arr::keyExist` to `Arr::keyExists`. 2. **Improved Code Readability:** - Changes ensure consistency between method names and their usage across the codebase. **Key Benefits:** - Enhances code clarity and maintains conformity with established naming patterns. - Reduces potential confusion for future contributors working on the `Arr` utility and its test cases.
**Detailed Description:** 1. **Introduced Autoload Files:** - Added the `autoload.files` directive to `composer.json` for including `dist/core.phar` in the project autoloader. 2. **Enhanced PHAR Compatibility:** - Ensures seamless integration of the prebuilt `core.phar` file into the application without requiring manual inclusion. 3. **Classmap Integration:** - Guarantees that `core.phar` is autoloaded consistently, improving runtime behavior in environments depending on the bundled PHAR. **Key Benefits:** - Simplifies dependency management by automating PHAR inclusion. - Enhances maintainability and ensures uniform loading in diverse execution environments.
…omposer.json` **Detailed Description:** 1. **Removed `autoload.files`:** - Eliminated the `autoload.files` directive from `composer.json`, which previously included `dist/core.phar` for autoloading. - Simplifies composer configuration by removing manual PHAR inclusion from the autoloader. 2. **Updated PHAR Builds:** - Made changes to `dist/core.phar` and `dist/core.min.phar` files, reflecting updated PHAR builds. **Key Benefits:** - Reduces reliance on manual file inclusion for better configuration maintainability. - Ensures consistency with the project's evolving standards for dependency and build management.
…abilities and runtime state management
**Detailed Description:**
1. **New Data Structures and Capabilities:**
- Implemented `Vector` as a dynamic, index-based linear data structure for efficient positional operations with seamless random access.
- Added `Snapshotable`, `Forkable`, `Freezable`, and `Copyable` interfaces to enable refined data structure operations including immutability, snapshots, structural sharing, and deep copying.
2. **Advanced Runtime State Management:**
- Introduced `HasCopyOnWriteState` and `HasFreezeState` traits to enable runtime behavioral flexibility:
- `HasCopyOnWriteState` facilitates lazy cloning for shared storage until mutation.
- `HasFreezeState` allows locking data structures in immutable states, rejecting modifications.
- Incorporated `StructureState` to manage reference counts and enforce safe ownership for copy-on-write operations.
3. **Snapshot Functionality:**
- Implemented `Snapshot` base and `VectorSnapshot` for read-only, immutable projections of data structures with controlled delegation of read operations.
4. **New Exceptions:**
- Added `InvalidCowStateException` and `FrozenDataStructureException` to handle errors related to copy-on-write ownership and mutation during freeze states.
5. **Type Enhancements:**
- Introduced `Linear` as a logical description for sequentially organized data topologies to represent collections like vectors, stacks, and queues.
6. **Autoload Classmap Updates:**
- Updated `classmap.php` for seamless integration of new data structure implementations, capabilities, and exceptions into the autoloader.
**Key Benefits:**
- Ensures modularity and scalability for creating consistent and reusable data structure abstractions.
- Improves performance through memory-efficient structural sharing and lazy instantiation during mutations.
- Enhances reliability with enforced immutability and clear runtime state tracking.
- Facilitates extensible and safe interaction via snapshot capabilities and granular exception handling.
**Detailed Description:** - Added release notes for version v0.3.1 to `CHANGELOG.md`. - Highlights the introduction of an extensible data structure framework with granular capabilities and runtime state management. - References linked issue, pull request, and specific commit for further context. **Key Benefits:** - Keeps the changelog up-to-date for better transparency and project documentation. - Provides a clear summary of changes and their implications for users and contributors.
…ctured data management
…sertion and ArrListStorage
…d PHP 8.1 support
**Detailed Description:**
1. **Upgraded PHP Version Compatibility:**
- Updated `Vector`, `ArrListStorage`, and `ArrMapStorage` to require PHP 8.1 for modern language features and improved compatibility.
2. **Extended `Vector`'s Capability Support:**
- Added support for new capabilities including `IndexMutation`, `LinearBoundaryAccess`, `FrontInsertion`, `BackInsertion`, `FrontRemoval`, and `BackRemoval`.
- Integrated operations for advanced index-based data access and mutation:
- `first()`, `last()`, `has(int $index)`, `get(int $index)`, `set(int $index, mixed $value)`, `remove(int $index)` methods.
- Array-like operations for structural modification, including `prepend` (addFirst), `append` (addLast), `shift` (removeFirst), and `pop` (removeLast).
3. **Improved Structural Snapshot Handling:**
- Enhanced `VectorSnapshot` with new snapshot capabilities, including `first`, `last`, `has`, and `get`.
4. **Runtime State Management Enhancements:**
- Added safeguards for frozen structures and copy-on-write state during mutation operations:
- Ensures proper detachment and immutability handling with added exception management (`FrozenDataStructureException`, `InvalidCowStateException`).
5. **PHAR Builds Updated:**
- Updated `core.phar` and `core.min.phar` builds to reflect enhancements.
**Key Benefits:**
- Improves `Vector`'s usability with robust and flexible index-based operations.
- Ensures compatibility with modern PHP versions for optimized performance.
- Enhances safety and consistency in runtime behavior with clear safeguards and error handling.
- Expands snapshot functionality for immutable state projections.
**Detailed Description:** - Updated `Vector` initialization to correctly use `BackInsertion::addLast` instead of `FrontInsertion::addFirst` for adding payload values to storage. - Modified relevant docblock in `firehub.Vector.php` to reflect the correct method usage. - Ensured consistency between the `Vector` initialization logic and its intended design for element insertion. **Key Benefits:** - Fixes incorrect method reference, ensuring proper functionality aligned with `BackInsertion` capability. - Improves documentation accuracy for better readability and developer understanding. - Updated PHAR builds (`core.phar` and `core.min.phar`) to integrate the corrected changes.
**Detailed Description:**
1. **Introduced `Map` Data Structure:**
- Implemented `Map`, a key-value associative data structure enabling efficient key-based operations like `get`, `set`, `has`, `remove`, and `replace`.
- Designed with support for advanced capabilities:
- Copy-on-write state handling via `HasCopyOnWriteState`.
- Immutability control through `HasFreezeState`.
- Snapshot creation for immutable state projections with `snapshot()`.
- Serialization and deserialization operations using `hydrate` and `dehydrate`.
2. **Added `Associative` Interface:**
- Created a logically distinct `Associative` type, representing data structures indexed via explicit keys instead of positional indices.
- Ensures semantic capabilities for key-driven lookups and mappings.
3. **Enhanced Snapshot Functionality:**
- Introduced `MapSnapshot` class for read-only, immutable versions of `Map` containing delegated access to core methods like `count`, `has`, and `get`.
4. **Extended `Vector` Capabilities:**
- Added new methods (`replace`, `delete`) to ensure flexibility for index-specific mutations.
5. **Autoload and Builds:**
- Updated `classmap.php` and `firehub.CompiledClassmap.php` for seamless class autoloading of newly introduced components.
- Revised PHAR builds (`core.phar` and `core.min.phar`) to integrate new data structures and enhanced functionality.
**Key Benefits:**
- Introduces highly flexible, key-oriented `Map` data structures with advanced runtime safety features.
- Extends the framework's abstraction capabilities with `Associative` for semantic richness.
- Improves structural immutability with robust snapshot capabilities.
- Updates PHAR for consistent developer experience with prepackaged dependencies.
…ce pluggable `HashEngine` and remove outdated array-based initializers**
**Detailed Description:**
1. **Migration to `HashStorage`:**
- Removed the legacy `ArrMapStorage` implementation and replaced it with `HashStorage`, a new key-value abstraction leveraging a pluggable hash engine for implementation flexibility.
- `HashStorage` decouples storage APIs from internal logic, enabling runtime adaptability with interchangeable hash engines.
2. **New Components Introduced:**
- **`HashEngine` Interface**: Defined the contract for hash-based storage engines.
- **`ArrHashEngine`**: Added a PHP array-backed implementation of `HashEngine` for fast and memory-resident key-value management.
- **`InvalidEngineException`**: Introduced an exception for invalid engine handling during runtime assignments.
3. **Changes to Initializers:**
- Replaced array-specific `ArrStorageInitializer` and related strategies (`ArrCallbackInitializer`, `ArrFillInitializer`, etc.) with their generic `ListStorageInitializer` counterparts to align with broader list-based operations.
4. **Updated Classmap Configuration:**
- Modified `classmap.php` and `firehub.CompiledClassmap.php` to reflect the removal of old structures and the addition of new components (`HashStorage`, `ArrHashEngine`, etc.).
5. **Deprecations and Cleanup:**
- Removed outdated components:
- `ArrMapStorage`
- `ArrStorageInitializer`
- Refactored relevant docblocks and file paths to improve consistency.
**Key Benefits:**
- Enhances modularity and scalability with runtime engine pluggability.
- Simplifies the framework by removing tightly coupled array-based initializers.
- Introduces a unified abstraction (`HashStorage`) for key-value structures with dynamic behaviors.
- Improves long-term maintainability by migrating to a flexible, engine-driven architecture.
**Detailed Description:** 1. **New Method in `StrSB`:** - Introduced `crc32(string $string): int` method to calculate the CRC32 checksum of a given string. - Utilizes PHP's built-in `crc32` function to efficiently compute the checksum and return it as an integer. 2. **Unit Test for `crc32`:** - Added a corresponding test case `testCrc32()` in `StrSBTest` to validate the functionality. - Used `TestWith` annotation to provide sample inputs (e.g., "The quick brown fox...") and expected checksum values for assertion. 3. **Documentation Updates:** - Updated docblocks in `StrSB` to describe the new method, including the expected input type, output type, and functionality purpose. 4. **File Name Consistency:** - Renamed internal class comments for better readability (e.g., adjusted spacing in `Array HashEngine`). 5. **Changelog Enhancement:** - Documented the addition of the `crc32` method under the "Unreleased" section, ensuring proper documentation of changes. 6. **Build Updates:** - Regenerated PHAR builds (`core.phar` and `core.min.phar`) to include the new functionality. **Key Benefits:** - Introduces CRC32 checksum capability directly within the framework for improved convenience and reduced dependency on external libraries. - Ensures correctness and reliability with unit test validation. - Maintains clear and up-to-date documentation, supporting seamless developer adoption.
…n outcome handling for `HashStorage` and related components. **Detailed Description:** 1. **Fixed Typographical Errors:** - Corrected repeated typos where "AAssigns" was used instead of "Assigns" in several docblocks across `firehub.Map.php`, `firehub.HashStorage.php`, `firehub.HashEngine.php`, and `firehub.KeyMutation.php`. - Ensured uniform punctuation, such as adding missing periods in method descriptions. 2. **Improved Mutation Outcome Logic:** - Refactored `set` and `remove` methods in `ArrHashEngine` to improve mutation outcome handling by caching the key existence check (`has($key)`) before and after the operation. - Reduces redundant calls to `has($key)` for performance optimization while maintaining correct return values (`CREATED`, `UPDATED`, `REMOVED`, `NOT_FOUND`). 3. **Enhanced Default Behavior for `HashStorage`:** - Introduced `ArrHashEngine` as the default engine in the `HashStorage` constructor, ensuring the class can operate independently if no engine is provided. - Updated relevant docblocks to explain the optional `HashEngine` parameter and clarified behavior when no engine is explicitly set. 4. **Documentation Updates:** - Adjusted docblocks across affected files to match established conventions within the project. This includes improved clarity, consistent formatting, and better readability. 5. **PHAR Build Updates:** - Recompiled `core.phar` and `core.min.phar` to include both the typo corrections and the logic improvements for mutation outcomes. **Key Benefits:** - Enhances code clarity and ensures accurate documentation for developers. - Improves runtime efficiency by optimizing mutation outcome handling. - Provides a seamless and self-contained `HashStorage` setup with sensible defaults. - Ensures PHAR builds reflect all recent improvements for consistency across distributions.
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
2 participants
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.
💢 Features / Enhancements Pull Request
Related Issue
Closes [Feature]: High-level API for Low-level proxys #11
Description
StrandCollectionin Core-Foundation v0.3.0.Implementation Details
FireHub\Support\Strimplemented:FireHub\Support\Collectionimplemented:StrMB,ArrMB, etc.).Testing
Documentation
Checklist
Risks / Impact
Notes
StrandCollectionare the first of many high-level helpers planned for the Support layer.