Introduce new Docker command classes and improve existing command handling.

[gustavofreze]

No description provided.

[Copilot]

Pull request overview

This PR refactors the Docker container execution pipeline by introducing container “definition” objects and new command handler classes, and it expands wait strategies (including time-based waits and dependency readiness polling with timeouts). It also reorganizes/rewrites a large portion of the unit test suite and updates documentation and dependencies to match the new architecture.

Changes:

• Introduces ContainerDefinition + mapping/value objects (ports, volumes, env vars, copy instructions) and rewrites Docker command classes to build CLI strings from definitions.
• Adds timeout-based dependency waiting (ContainerWaitForDependency) and a new ContainerWaitTimeout exception; updates MySQL readiness checks.
• Replaces/rewrites many unit tests with new mocks/fixtures and updates README/Makefile/composer dependencies.

Reviewed changes

Copilot reviewed 95 out of 95 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
tests/Unit/Waits/ContainerWaitForTimeTest.php	Adds unit tests for time-based wait strategy.
tests/Unit/Waits/ContainerWaitForDependencyTest.php	Updates dependency-wait tests for retries/timeouts/polling.
tests/Unit/MySQLDockerContainerTest.php	Adds comprehensive MySQL container unit tests using mocks.
tests/Unit/Mocks/TestableMySQLDockerContainer.php	Provides test helper for creating MySQL containers with a mock client.
tests/Unit/Mocks/TestableGenericDockerContainer.php	Provides test helper for creating generic containers with a mock client.
tests/Unit/Mocks/InspectResponseFixture.php	Adds fixture builder for docker inspect payloads.
tests/Unit/Mocks/ExecutionCompletedMock.php	Adds mock for command execution results.
tests/Unit/Mocks/CommandWithTimeoutMock.php	Adds mock command supporting timeouts.
tests/Unit/Mocks/CommandMock.php	Adds mock command for DockerClient tests.
tests/Unit/Mocks/ClientMock.php	Adds richer Docker client mock (run/list/inspect/exec/stop).
tests/Unit/Internal/Containers/Models/ImageTest.php	Removes old model-level unit tests.
tests/Unit/Internal/Containers/Models/ContainerIdTest.php	Removes old model-level unit tests.
tests/Unit/Internal/Containers/Drivers/MySQL/MySQLStartedTest.php	Removes old MySQLStarted tests (replaced by new suite).
tests/Unit/Internal/Commands/DockerStopTest.php	Removes old DockerStop command unit test.
tests/Unit/Internal/Commands/DockerRunTest.php	Removes old DockerRun command unit test.
tests/Unit/Internal/Commands/DockerListTest.php	Removes old DockerList command unit test.
tests/Unit/Internal/Commands/DockerInspectTest.php	Removes old DockerInspect command unit test.
tests/Unit/Internal/Commands/DockerExecuteTest.php	Removes old DockerExecute command unit test.
tests/Unit/Internal/Commands/DockerCopyTest.php	Removes old DockerCopy command unit test.
tests/Unit/Internal/CommandHandlerTest.php	Removes old command handler tests (handler refactored).
tests/Unit/Internal/Client/DockerClientTest.php	Updates DockerClient tests and moves to new namespace/mocks.
tests/Unit/GenericDockerContainerTest.php	Adds extensive new unit tests for generic container behavior and CLI args.
tests/Unit/CommandWithTimeoutMock.php	Removes old mock (replaced under tests/Unit/Mocks).
tests/Unit/CommandMock.php	Removes old mock (replaced under tests/Unit/Mocks).
tests/Unit/CommandHandlerMock.php	Removes old mock command handler.
tests/Unit/ClientMock.php	Removes old client mock (replaced under tests/Unit/Mocks).
tests/Integration/DockerContainerTest.php	Tweaks integration test configuration/timeouts.
tests/Integration/Database/Migrations/V0000__Create_xpto_table.sql	Adjusts SQL migration formatting/quoting.
src/Waits/ContainerWaitForTime.php	Switches to microsecond sleeping for time waits.
src/Waits/ContainerWaitForDependency.php	Adds deadline/timeout + poll interval and throws ContainerWaitTimeout.
src/Waits/ContainerWaitBeforeStarted.php	Updates interface docs/throws.
src/Waits/ContainerWaitAfterStarted.php	Updates interface docs/throws.
src/Waits/ContainerWait.php	Replaces old wait constant with default timeout + poll interval constants.
src/Waits/Conditions/MySQL/MySQLReady.php	Makes MySQL readiness check resilient to exceptions (returns false).
src/Waits/Conditions/ContainerReady.php	Clarifies condition semantics/docs.
src/MySQLDockerContainer.php	Refactors MySQL container to wrap GenericDockerContainer and adds readiness timeout config.
src/MySQLContainer.php	Extends MySQL container contract with readiness timeout configuration.
src/Internal/Exceptions/ContainerWaitTimeout.php	Introduces dedicated timeout exception for wait strategies.
src/Internal/Containers/Started.php	Refactors started-container implementation to store parsed fields directly.
src/Internal/Containers/Models/Environment/EnvironmentVariables.php	Removes old model collection-based env var holder.
src/Internal/Containers/Models/ContainerId.php	Trims and validates IDs more robustly.
src/Internal/Containers/Models/Container.php	Removes old container model.
src/Internal/Containers/Models/Address/Ports.php	Removes old ports model.
src/Internal/Containers/Models/Address/IP.php	Removes old IP model.
src/Internal/Containers/Models/Address/Hostname.php	Removes old hostname model.
src/Internal/Containers/Factories/InspectResultParser.php	Adds parser for inspect payload into address/env var domain objects.
src/Internal/Containers/Factories/EnvironmentVariablesFactory.php	Removes old env var factory.
src/Internal/Containers/Factories/ContainerFactory.php	Removes old container factory.
src/Internal/Containers/Factories/AddressFactory.php	Removes old address factory.
src/Internal/Containers/Environment/EnvironmentVariables.php	Adds new env vars implementation returning empty string for missing keys.
src/Internal/Containers/Drivers/MySQL/MySQLStarted.php	Refactors MySQLStarted to wrap ContainerStarted (composition).
src/Internal/Containers/Definitions/VolumeMapping.php	Adds value object for volume mapping CLI args.
src/Internal/Containers/Definitions/PortMapping.php	Adds value object for port mapping CLI args.
src/Internal/Containers/Definitions/EnvironmentVariable.php	Adds value object for env var CLI args (with escaping).
src/Internal/Containers/Definitions/CopyInstruction.php	Adds value object for post-start copy instructions.
src/Internal/Containers/Definitions/ContainerDefinition.php	Adds immutable container definition used to build commands.
src/Internal/Containers/Address/Ports.php	Adds new ports implementation backed by Collection.
src/Internal/Containers/Address/IP.php	Adds new IP value type (defaults to 127.0.0.1).
src/Internal/Containers/Address/Hostname.php	Adds new hostname value type (defaults to localhost).
src/Internal/Containers/Address/Address.php	Moves/updates address implementation and construction.
src/Internal/ContainerCommandHandler.php	Removes old command handler implementation.
src/Internal/Commands/Options/VolumeOption.php	Removes old command-option system.
src/Internal/Commands/Options/SimpleCommandOption.php	Removes old command-option system.
src/Internal/Commands/Options/PortOption.php	Removes old command-option system.
src/Internal/Commands/Options/NetworkOption.php	Removes old command-option system.
src/Internal/Commands/Options/ItemToCopyOption.php	Removes old command-option system.
src/Internal/Commands/Options/GenericCommandOption.php	Removes old command-option system.
src/Internal/Commands/Options/EnvironmentVariableOption.php	Removes old command-option system.
src/Internal/Commands/Options/CommandOptions.php	Removes old command-option system.
src/Internal/Commands/Options/CommandOption.php	Removes old command-option system.
src/Internal/Commands/LineBuilder.php	Removes old helper trait used for CLI string building.
src/Internal/Commands/DockerStop.php	Updates DockerStop to build CLI via sprintf.
src/Internal/Commands/DockerRun.php	Rewrites DockerRun to build CLI from ContainerDefinition.
src/Internal/Commands/DockerList.php	Simplifies DockerList to filter by name only.
src/Internal/Commands/DockerInspect.php	Updates DockerInspect to build CLI via sprintf.
src/Internal/Commands/DockerExecute.php	Rewrites DockerExecute to build CLI from a commands collection.
src/Internal/Commands/DockerCopy.php	Rewrites DockerCopy to use copy instruction + container ID.
src/Internal/Commands/CommandWithTimeout.php	Updates docs for timeout-capable commands.
src/Internal/Commands/Command.php	Updates docs for command string conversion.
src/Internal/CommandHandler/ContainerCommandHandler.php	Introduces new command handler coordinating run/find/inspect/copy flows.
src/Internal/CommandHandler/CommandHandler.php	Introduces new command handler interface (run/find/execute).
src/Internal/CommandHandler.php	Removes old command handler interface.
src/Internal/Client/DockerClient.php	Minor fix: uses instanceof for timeout capability.
src/Internal/Client/Client.php	Updates client docs.
src/GenericDockerContainer.php	Refactors to use container definitions + new command handler.
src/DockerContainer.php	Tightens container contract return types (static) and improves docs.
src/Contracts/Ports.php	Clarifies exposed ports contract/docs.
src/Contracts/MySQL/MySQLContainerStarted.php	Clarifies JDBC options typing/docs.
src/Contracts/ExecutionCompleted.php	Clarifies output semantics/docs.
src/Contracts/EnvironmentVariables.php	Clarifies missing-key behavior/docs.
src/Contracts/ContainerStarted.php	Clarifies typing/docs and default stop timeout.
src/Contracts/Address.php	Clarifies address contract/docs.
README.md	Updates usage docs for new waits/readiness timeout and examples.
Makefile	Removes mutation report path from show-reports.
composer.json	Updates dependencies (notably bumps collection, removes mapper).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.