Conditional container run with reuse signaling, plus full tiny-blocks conformance.#26
Open
gustavofreze wants to merge 4 commits into
Open
Conditional container run with reuse signaling, plus full tiny-blocks conformance.#26gustavofreze wants to merge 4 commits into
gustavofreze wants to merge 4 commits into
Conversation
Introduce runWhen(gate, then), which starts a container only when a predicate holds and hands the started container to a callback, wasReused() to distinguish a reused container from a freshly started one, and EnvironmentFlag::enabled() as a ready-made predicate. The same change set brings the library into conformance with the tiny-blocks ecosystem rules across folder layout, code style, modeling, tooling, CI, and documentation.
There was a problem hiding this comment.
Pull request overview
This pull request modernizes the library to match tiny-blocks ecosystem conventions while extending the container runtime API with conditional execution and explicit reuse signaling.
Changes:
- Add conditional container execution (
runWhen) and reuse signaling (wasReused) to support gated side effects and shared containers. - Refactor the public API surface away from
Contracts\*into root namespaces, with corresponding updates across internals, tests, and docs. - Align repository tooling and templates with tiny-blocks standards (PHPStan max config, PHPCS ruleset, CI workflow structure, reports paths, GitHub templates).
Reviewed changes
Copilot reviewed 136 out of 138 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/Unit/Waits/ContainerWaitForTimeTest.php | Updates time-wait tests to match the updated wait-after signature and conventions. |
| tests/Unit/Waits/ContainerWaitForDependencyTest.php | Reorders and expands dependency wait tests, including poll interval behavior. |
| tests/Unit/TestableMySQLDockerContainer.php | Updates unit test container factory wiring and signatures. |
| tests/Unit/TestableGenericDockerContainer.php | Updates generic test container factory wiring, including shutdown hook implementation. |
| tests/Unit/TestableFlywayDockerContainer.php | Updates Flyway test container factory signature and wiring. |
| tests/Unit/ShutdownHookMock.php | Converts shutdown hook mock to match the new ShutdownHook interface. |
| tests/Unit/RunningMySQLContainer.php | Adds a helper to start a MySQL container in unit tests with realistic fixtures. |
| tests/Unit/RegisteredShutdownHookTest.php | Adds coverage for the new RegisteredShutdownHook implementation. |
| tests/Unit/MySQLCommandsTest.php | Adds reflection-based coverage for the MySQLCommands private constructor. |
| tests/Unit/Internal/Containers/ShutdownHookTest.php | Removes old ShutdownHook tests after refactor to interface plus implementation. |
| tests/Unit/Internal/Containers/Overrides/register_shutdown_function_spy.php | Updates the spy used to intercept shutdown registration calls in tests. |
| tests/Unit/Internal/Containers/Overrides/file_exists_outside_docker.php | Minor cleanup in the file-exists override fixture. |
| tests/Unit/Internal/Containers/ContainerReaperTest.php | Removes older direct unit tests for ContainerReaper. |
| tests/Unit/Internal/Containers/Address/PortsTest.php | Removes older direct unit tests for Ports behavior. |
| tests/Unit/Internal/Containers/Address/AddressTest.php | Removes older direct unit tests for Address behavior. |
| tests/Unit/Internal/Commands/DockerCommandsTest.php | Removes older direct unit tests for command argument builders. |
| tests/Unit/Internal/Client/DockerClientTest.php | Updates DockerClient tests to match moved mocks and updated conventions. |
| tests/Unit/HostEnvironmentTest.php | Adds reflection-based coverage for HostEnvironment construction constraints. |
| tests/Unit/ExecutionCompletedMock.php | Updates mock to use the new root ExecutionCompleted interface location. |
| tests/Unit/EnvironmentFlagTest.php | Adds tests for the new EnvironmentFlag helper. |
| tests/Unit/CommandWithTimeoutMock.php | Moves mocks out of Mocks namespace to match test layout conventions. |
| tests/Unit/CommandMock.php | Moves mocks out of Mocks namespace to match test layout conventions. |
| tests/Unit/ClientMock.php | Refactors test client mock to record argument arrays and align with new interfaces. |
| tests/Models/InspectResponseFixture.php | Moves fixtures to tests/Models and adjusts class shape for conventions. |
| tests/Integration/MySQLRepository.php | Updates imports for moved ContainerStarted interface. |
| tests/Integration/DockerContainerTest.php | Updates assertions and Flyway source wiring to match API changes. |
| src/Waits/ContainerWaitForTime.php | Updates imports to the new root ContainerStarted interface. |
| src/Waits/ContainerWaitAfterStarted.php | Updates imports to the new root ContainerStarted interface. |
| src/Waits/Conditions/MySQL/MySQLReady.php | Refines command building and formatting conventions for readiness checks. |
| src/Waits/Conditions/ContainerReady.php | Updates doc phrasing to match tiny-blocks style conventions. |
| src/Ports.php | Moves Ports contract to public root namespace and adjusts doc ordering. |
| src/MySQLDockerContainer.php | Adds conditional run API and refactors run logic for readiness and setup. |
| src/MySQLContainer.php | Reorders documentation and method declarations for public MySQL container contract. |
| src/MySQL/MySQLContainerStarted.php | Moves MySQL started contract to a public concept namespace. |
| src/Internal/Exceptions/ImageNameEmpty.php | Introduces a dedicated exception for empty image names. |
| src/Internal/Exceptions/DockerContainerNotFound.php | Updates Name import after internal model relocation. |
| src/Internal/Exceptions/DockerCommandExecutionFailed.php | Improves command rendering and reorders factory helpers. |
| src/Internal/Exceptions/ContainerIdTooShort.php | Introduces a dedicated exception for short container IDs. |
| src/Internal/Exceptions/ContainerIdEmpty.php | Introduces a dedicated exception for empty container IDs. |
| src/Internal/Containers/Started.php | Adjusts method ordering, adds wasReused(), and updates ShutdownHook usage. |
| src/Internal/Containers/ShutdownHook.php | Refactors ShutdownHook from concrete class into an interface. |
| src/Internal/Containers/Reused.php | Adds reuse signaling and aligns methods with updated ContainerStarted contract. |
| src/Internal/Containers/RegisteredShutdownHook.php | Adds the concrete ShutdownHook implementation that delegates to PHP shutdown registration. |
| src/Internal/Containers/Name.php | Moves Name model and updates Ksuid API usage for v2. |
| src/Internal/Containers/Models/ContainerId.php | Removes old ContainerId model after relocation and exception refactor. |
| src/Internal/Containers/Image.php | Switches to dedicated exception type and stricter empty-name check. |
| src/Internal/Containers/HostEnvironment.php | Makes HostEnvironment non-instantiable with a private constructor. |
| src/Internal/Containers/Environment/EnvironmentVariables.php | Updates imports to the new root EnvironmentVariables interface. |
| src/Internal/Containers/Drivers/MySQL/MySQLStarted.php | Aligns started wrapper with updated ContainerStarted ordering and adds reuse forwarding. |
| src/Internal/Containers/Drivers/MySQL/MySQLCommands.php | Adds private constructor and updates statement assembly conventions. |
| src/Internal/Containers/Definitions/VolumeMapping.php | Introduces $template variables for sprintf formatting conformance. |
| src/Internal/Containers/Definitions/PortMapping.php | Introduces $template variables for sprintf formatting conformance. |
| src/Internal/Containers/Definitions/EnvironmentVariable.php | Introduces $template variables for sprintf formatting conformance. |
| src/Internal/Containers/Definitions/CopyInstruction.php | Updates ContainerId import and adds $template for formatting conformance. |
| src/Internal/Containers/Definitions/ContainerDefinition.php | Reorders builder methods and adjusts withoutAutoRemove/with* semantics ordering. |
| src/Internal/Containers/ContainerReaper.php | Refines whitespace handling and formatting conventions for reaper name and checks. |
| src/Internal/Containers/ContainerLookup.php | Updates imports for moved ContainerStarted and ContainerId. |
| src/Internal/Containers/ContainerId.php | Adds new internal ContainerId model with dedicated exception types. |
| src/Internal/Containers/Address/Ports.php | Refactors filtering and key preservation using tiny-blocks collection utilities. |
| src/Internal/Containers/Address/IP.php | Tightens empty string check to avoid empty() semantics. |
| src/Internal/Containers/Address/Hostname.php | Tightens empty string check to avoid empty() semantics. |
| src/Internal/Containers/Address/Address.php | Updates imports to moved public Address and Ports interfaces. |
| src/Internal/Commands/DockerStop.php | Updates ContainerId import after model relocation. |
| src/Internal/Commands/DockerRun.php | Refactors argument assembly using collection reduce and formatting templates. |
| src/Internal/Commands/DockerRemove.php | Updates ContainerId import after model relocation. |
| src/Internal/Commands/DockerReaper.php | Reorders buildScript and introduces $template variable for formatting conformance. |
| src/Internal/Commands/DockerNetworkPrune.php | Refactors filter formatting into $template and intermediate variable. |
| src/Internal/Commands/DockerList.php | Refactors filter formatting into $template. |
| src/Internal/Commands/DockerInspect.php | Updates ContainerId import after model relocation. |
| src/Internal/Commands/DockerExecute.php | Updates Name import after model relocation. |
| src/Internal/Commands/DockerCopy.php | Updates ContainerId import after model relocation. |
| src/Internal/Commands/Command.php | Updates doc phrasing to match tiny-blocks conventions. |
| src/Internal/CommandHandler/ContainerCommandHandler.php | Reorders methods and updates imports after model/interface relocation. |
| src/Internal/CommandHandler/CommandHandler.php | Updates imports to moved public ContainerStarted and ExecutionCompleted. |
| src/Internal/Client/Execution.php | Updates imports to moved public ExecutionCompleted interface. |
| src/Internal/Client/DockerClient.php | Updates Process construction style and imports for moved ExecutionCompleted. |
| src/Internal/Client/Client.php | Updates imports to moved public ExecutionCompleted interface. |
| src/GenericDockerContainer.php | Adds runWhen, adds reuse signaling via Reused wrapper, and updates shutdown hook implementation. |
| src/FlywayDockerContainer.php | Reorders migrate/repair methods and updates Flyway source configuration signature. |
| src/FlywayContainer.php | Updates contract ordering and withSource signature to match implementation and docs. |
| src/ExecutionCompleted.php | Moves interface to public root namespace and updates doc phrasing. |
| src/EnvironmentVariables.php | Moves interface to public root namespace. |
| src/EnvironmentFlag.php | Adds environment predicate helper to support conditional container execution gates. |
| src/DockerContainer.php | Adds runWhen contract and reorganizes method docs and ordering. |
| src/ContainerStarted.php | Moves interface to public root namespace and adds wasReused() to the contract. |
| src/Address.php | Moves interface to public root namespace. |
| SECURITY.md | Adds a repository security policy file. |
| README.md | Updates documentation for new conditional run and reuse signaling features and reorders sections. |
| phpunit.xml | Tightens test strictness and standardizes report output paths under reports/. |
| phpstan.neon.dist | Expands configuration to level: max, includes tests, and replaces regex ignores with identifiers. |
| phpcs.xml | Adds PSR-12 ruleset configuration for both src and tests. |
| Makefile | Adds TTY detection, aligns targets with composer scripts, and standardizes reports paths. |
| infection.json.dist | Moves report paths under reports/ and updates infection cache/log destinations. |
| composer.json | Updates dependencies, adds canonical scripts, and aligns review and tests commands. |
| CLAUDE.md | Adds contributor-facing index of conventions, commands, and ecosystem rules. |
| .gitignore | Updates ignored paths to match new reports directory layout and local override convention. |
| .gitattributes | Adjusts export-ignore and linguist settings for tooling and Packagist packaging. |
| .editorconfig | Adds max line length and aligns editor defaults to ecosystem standards. |
| .github/workflows/codeql.yml | Adds concurrency and timeouts, updates pinned checkout version. |
| .github/workflows/ci.yml | Adds concurrency, resolves PHP version from composer.json, and standardizes CI job structure. |
| .github/workflows/auto-assign.yml | Adds concurrency, timeouts, and clarifies job naming and permissions. |
| .github/PULL_REQUEST_TEMPLATE.md | Adds a canonical pull request template aligned with tiny-blocks contributing. |
| .github/ISSUE_TEMPLATE/feature_request.md | Adds canonical feature request template. |
| .github/ISSUE_TEMPLATE/bug_report.md | Adds canonical bug report template. |
| .claude/skills/tiny-blocks-create/SKILL.md | Adds the tiny-blocks scaffolding skill definition and guidance. |
| .claude/skills/tiny-blocks-create/assets/github/workflows/ci.yml | Adds canonical CI workflow asset for scaffolding. |
| .claude/skills/tiny-blocks-create/assets/github/PULL_REQUEST_TEMPLATE.md | Adds canonical PR template asset for scaffolding. |
| .claude/skills/tiny-blocks-create/assets/github/ISSUE_TEMPLATE/feature_request.md | Adds canonical feature request template asset. |
| .claude/skills/tiny-blocks-create/assets/github/ISSUE_TEMPLATE/bug_report.md | Adds canonical bug report template asset. |
| .claude/skills/tiny-blocks-create/assets/docs/SECURITY.md | Adds canonical SECURITY.md asset for scaffolding. |
| .claude/skills/tiny-blocks-create/assets/config/phpunit.xml | Adds canonical phpunit.xml asset for scaffolding. |
| .claude/skills/tiny-blocks-create/assets/config/phpstan.neon.dist | Adds canonical phpstan.neon.dist asset for scaffolding. |
| .claude/skills/tiny-blocks-create/assets/config/phpcs.xml | Adds canonical phpcs.xml asset for scaffolding. |
| .claude/skills/tiny-blocks-create/assets/config/Makefile | Adds canonical Makefile asset for scaffolding. |
| .claude/skills/tiny-blocks-create/assets/config/infection.json.dist | Adds canonical infection.json.dist asset for scaffolding. |
| .claude/skills/tiny-blocks-create/assets/config/composer.json | Adds canonical composer.json asset template for scaffolding. |
| .claude/skills/tiny-blocks-create/assets/config/.gitignore | Adds canonical .gitignore asset for scaffolding. |
| .claude/skills/tiny-blocks-create/assets/config/.gitattributes | Adds canonical .gitattributes asset for scaffolding. |
| .claude/skills/tiny-blocks-create/assets/config/.editorconfig | Adds canonical .editorconfig asset for scaffolding. |
| .claude/skills/tiny-blocks-consume/SKILL.md | Adds the tiny-blocks consume skill definition and guidance. |
| .claude/skills/tiny-blocks-consume/scripts/refresh-catalog.py | Adds script to refresh the tiny-blocks catalog from Packagist. |
| .claude/skills/tiny-blocks-consume/references/catalog.md | Adds generated tiny-blocks package catalog reference. |
| .claude/skills/commit-message/SKILL.md | Adds conventional commit message formatting skill. |
| .claude/settings.json | Adds Claude Code settings and hook permissions configuration. |
| .claude/rules/php-library-tooling.md | Adds canonical tooling invariants for tiny-blocks PHP libraries. |
| .claude/rules/php-library-github-workflows.md | Adds canonical GitHub workflow conventions for tiny-blocks PHP libraries. |
| .claude/rules/php-library-documentation.md | Adds canonical README and docs conventions for tiny-blocks PHP libraries. |
| .claude/rules/php-library-architecture.md | Adds canonical architecture and public API boundary conventions. |
| .claude/hooks/php-prose-punctuation-conformance.py | Adds hook enforcing prose punctuation rules in Markdown and PHP comments. |
| .claude/CLAUDE.md | Removes the older Claude instruction file in favor of the new CLAUDE.md plus rules structure. |
| .claude/rules/github-workflows.md | Removes replaced workflow rule file superseded by php-library-github-workflows.md. |
Comments suppressed due to low confidence (3)
tests/Unit/TestableGenericDockerContainer.php:22
- This factory uses a self return type and new self(). The codebase rules prohibit self as a type/instantiation (use the explicit class name instead) and this class is final so late binding is not needed.
tests/Unit/TestableMySQLDockerContainer.php:18 - This factory uses a self return type and new self(). The codebase rules prohibit self as a type/instantiation (use the explicit class name instead) and this class is final so late binding is not needed.
tests/Unit/TestableFlywayDockerContainer.php:16 - This factory uses a self return type and new self(). The codebase rules prohibit self as a type/instantiation (use the explicit class name instead) and this class is final so late binding is not needed.
The integration suite starts real MySQL and Flyway containers and pulls their images on a cold cache, which exceeds Composer's default 300-second process timeout and aborts `composer tests`.
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.