docs: add v3 documentation #110
Open
Conversation
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
Introduce configuration options for machine event data compression, including enablement, compression level, targeted fields, and size threshold. Supports efficient storage by reducing payload size.
Replace `json` fields with `longText` and `binary` charset for `payload`, `context`, and `meta` columns to support compressed binary data. Improves storage efficiency for machine event data.
Introduce `CompressionManager` class to support configurable data compression and decompression. Includes global enablement, compression level, field targeting, size threshold, and compression statistics functionalities. Supports gzip compression for optimized data storage and transmission.
…tion Introduce unit tests for `CompressionManager` to validate the detection of compressed data. Ensure proper handling of compressed, uncompressed, null, and empty inputs.
Introduce unit tests to verify `CompressionManager`'s ability to compress and decompress data accurately. Ensure decompressed data matches the original.
Introduce a unit test to ensure `CompressionManager` can handle uncompressed JSON inputs for backward compatibility. Validate that decompressed results match the original data.
Introduce tests to verify `CompressionManager` respects the configured compression threshold. Ensure small data remains uncompressed while large data is compressed as expected.
Introduce tests to ensure `CompressionManager` respects the configured fields for compression. Validate that only specified fields are compressed while others remain uncompressed.
Introduce a unit test to verify `CompressionManager` respects the global compression disablement configuration. Ensure data remains uncompressed when compression is disabled globally.
Introduce a unit test to verify compression statistics calculation in `CompressionManager`. Ensure keys like `original_size`, `compressed_size`, `compression_ratio`, and `savings_percent` are accurate and valid.
Add tests to verify `CompressionManager` handles null values correctly during compression and decompression. Ensure `null` is converted and restored as expected.
Introduce a unit test to verify `CompressionManager` handles compression failures gracefully. Ensure JSON data is returned if compression fails.
Introduce a unit test to ensure `CompressionManager` throws an exception when attempting to decompress invalid compressed data. Validate proper error handling with `InvalidArgumentException`.
Introduce tests to verify `CompressionManager` handles edge compression levels correctly. Validate behavior for fastest (0) and best (9) compression, and ensure invalid levels throw `InvalidArgumentException`.
Introduce a unit test to verify `CompressionManager` handles very large data (1MB+) correctly. Ensure data is compressed and decompressed accurately without loss or error.
Introduce a unit test to verify `CompressionManager` handles special JSON characters, encoding, and formatting correctly. Ensure data is compressed and decompressed accurately without loss or alteration.
Introduce a unit test to verify `CompressionManager` correctly detects malformed zlib headers. Ensure valid compressed data is identified while invalid headers and partial data return false.
Ensure zlib extension is explicitly required in composer.json for compression-related functionality.
Introduce `CompressedJsonCast` to handle attribute compression and decompression using `CompressionManager`. Enables automated storage of compressed JSON data in models.
Switch MachineEvent attributes (payload, context, meta) to use CompressedJsonCast. Enables automatic compression and decompression of JSON data for optimized storage.
Introduce `CompressEventsCommand` to compress MachineEvent data for storage optimization. Includes options for chunk size, dry run, and force confirmation. Implements analysis and compression operations for payload, context, and meta fields.
Introduce `CompressMachineEventsJob` to enable batch compression of `MachineEvent` data. Includes configurable chunk size, retry logic, and logging for processed, compressed, and skipped records. Automatically dispatches subsequent jobs for remaining data. Handles failures with detailed logging.
Introduce integration tests for verifying automatic compression and decompression of MachineEvent data. Validate compression behavior for payload, context, and meta fields, ensuring data integrity and storage optimization. Confirm that machine_value remains uncompressed for querying.
Add integration test to validate compression threshold and field-specific configuration. Verify large payloads are compressed while small contexts remain uncompressed. Ensure data integrity after compression.
…sed data Verify handling of legacy uncompressed MachineEvent data. Ensure payload, context, and meta fields are correctly read and identified as uncompressed using `CompressionManager`. Validate data integrity and compatibility with existing attributes.
Introduce integration test to evaluate compression effectiveness on real-world MachineEvent contexts. Verify significant storage savings and maintain data integrity. Validate compression ratio and minimum savings percentage.
Introduce schema migration for upgrading MachineEvent storage to support compressed binary data. Adds new LONGBLOB columns, migrates JSON data, and maintains backward compatibility. Includes rollback support for decompression.
Add service provider registration for the new `CompressEventsCommand` and associated migration `upgrade_machine_events_for_compression_v2`. Enhances MachineEvent compression capabilities and ensures required resources are properly loaded.
Introduce unit test to verify automatic compression and decompression of MachineEvent payloads. Validate raw database storage as compressed and ensure accessors return decompressed data.
Introduce unit test to verify automatic compression of `context` on save. Ensure raw database storage is compressed and accessors return decompressed data.
…entation Removed redundant archive existence check from the code example. Added tip explaining why no double-check is needed (lockForUpdate handles it).
Adds complete documentation for EventMachine v3 including: ## New in v3 - Archival & compression system with auto-restore - restoreAndDelete() method for race-safe restoration - Lifecycle diagrams and configuration guides ## Documentation Structure - Introduction & quick start guides - Core concepts (states, transitions, events, context) - Behaviors (actions, guards, calculators, validation) - Laravel integration (persistence, Eloquent, commands) - Advanced topics (hierarchical states, DI, scenarios) - API reference for all classes - Examples (traffic lights, elevator, order processing) - Testing guides Built with VitePress for modern documentation experience.
Documentation is now maintained in the v3-docs branch and PR #110. This separation allows parallel review of code and documentation changes.
Open
New structure: - getting-started/ (3 files) - Tutorial-first introduction - understanding/ (4 files) - Core mental model Key changes: - Removed need for separate API Reference - Each section includes relevant API details in context - Progressive complexity from basics to advanced - Story-driven narrative throughout Remaining: - building/ (5 files) - behaviors/ refactor (5 files) - patterns/ (5 files) - laravel/ refactor (4 files) - advanced/ refactor (6 files) - testing/ refactor (4 files) - Update vitepress config - Remove old api-reference/
- Add building/ section (5 files): - defining-states.md - writing-transitions.md - working-with-context.md - handling-events.md - configuration.md - Add patterns/ section (6 files from examples/): - introduction.md (new) - Rename examples/ to patterns/ - Refactor behaviors/: - Rename overview.md to introduction.md - Add navigation links to all behavior pages - Update vitepress config with new sidebar structure - Fix homepage link to new getting-started path - Remove old folders: - api-reference/ (11 files) - introduction/ (4 files) - core-concepts/ (6 files) - examples/ (moved to patterns/) - Update .gitignore: add .claude, docs/.vitepress/cache
Navigation handled by sidebar; redundant links removed from: - getting-started/ (3 files) - understanding/ (4 files) - building/ (5 files) - behaviors/ (5 files) - patterns/ (1 file)
- Remove API Reference links from archival-compression.md - Update introduction/ links to getting-started/ in upgrading.md
- Add HomeFeatures.vue component for alternating layout - Add style.css with emerald brand colors - Add theme/index.ts to register components - Update config.ts with Google Fonts preconnect
Replace feature cards with 6 alternating text/code sections: - Declare Your States: basic machine definition - Every Transition, Persisted: event sourcing emphasis - Guards Protect, Actions Execute: business logic - Archive Millions, Restore Any: enterprise archival - Type-Safe Context: Spatie Data integration - Laravel Native: Eloquent, DI, Artisan
- Add "Complete Audit Trail" section for compliance-ready history - Rename "Guards Protect" to "Testable Business Logic" with test example
- Add `logo-light-old.svg` and `logo-dark-old.svg` to `docs/public/` - These assets preserve previous logos for reference or fallback usage
Compare EventMachine with: - PHP: Spatie Model States, Asantibanez, Symfony Workflow - Ruby: AASM, Statesman, state_machines - JavaScript: XState
Category A fixes: - Fix invalid event behavior: throws NoTransitionDefinitionFoundException - Fix machine.stop → machine.finish across all files - Fix withHistory() → create(state:) method - Fix eventQueue->push() → raise() method Category B additions: - Add calculator failure behavior warning - Add SourceType enum documentation - Add complete internal events reference (18 events) - Add State.$value and matches() documentation - Add ResolvesBehaviors trait to testing docs - Improve behaviors section on homepage
- Reduce understanding/context.md from 326 to 87 lines (brief intro) - Reduce understanding/events.md from 311 to 94 lines (brief intro) - Link to comprehensive building/ docs for full details - Eliminates ~80% content duplication between understanding/ and building/
- Add Laravel 12 support to requirements (matches composer.json) - Fix config example to match actual config/machine.php structure - Fix MachineCast syntax in Eloquent integration example - Replace "comprehensive" with "complete" (style guide)
deligoez
changed the title
Deploying event-machine with
|
| Latest commit: |
2a6ab99
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://becfabed.event-machine.pages.dev |
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.
Summary
Complete documentation for EventMachine v3, built with VitePress.
Documentation Structure (44 files)
Key Features Documented
Local Development
cd docs npm install npm run docs:devReview Notes