-
Notifications
You must be signed in to change notification settings - Fork 14
feat: v2 containers #63
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,4 +1,5 @@ | ||
| /vendor/ | ||
| /.idea/ | ||
| .phpunit.result.cache | ||
| *.phpdisabled | ||
| *.phpdisabled | ||
| .DS_Store |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,18 +1,18 @@ | ||
| # Utopia Orchestration | ||
| # Utopia Containers | ||
|
|
||
| [](https://app.travis-ci.com/github/utopia-php/orchestration) | ||
|  | ||
| [](https://app.travis-ci.com/github/utopia-php/containers) | ||
|  | ||
| [](https://appwrite.io/discord) | ||
|
|
||
| Utopia framework orchestration library is simple and lite library for abstracting the interaction with multiple container orchestrators. This library is aiming to be as simple and easy to learn and use. This library is maintained by the [Appwrite team](https://appwrite.io). | ||
| Utopia framework containers library is simple and lite library for abstracting the interaction with multiple container orchestrators. This library is aiming to be as simple and easy to learn and use. This library is maintained by the [Appwrite team](https://appwrite.io). | ||
|
|
||
| Although this library is part of the [Utopia Framework](https://github.com/utopia-php/framework) project it is dependency free and can be used as standalone with any other PHP project or framework. | ||
|
|
||
| ## Getting Started | ||
|
|
||
| Install using composer: | ||
| ```bash | ||
| composer require utopia-php/orchestration | ||
| composer require utopia-php/containers | ||
| ``` | ||
|
Comment on lines
+7
to
16
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🧩 Analysis chainREADME still documents v1 There are a couple of important drifts between the README and the v2 code:
Once the v2 API is finalized, please update these sections to match the actual Also applies to: 75-112 I'll verify the review comment by checking the actual README content and comparing it with the current API implementation. 🏁 Script executed: #!/bin/bash
# Read the full README to see lines 75-112
cat README.md | head -120 | tail -50Length of output: 1208 🏁 Script executed: #!/bin/bash
# Search for Containers class and pull/run method signatures
find . -type f -name "*.php" | head -20Length of output: 789 🏁 Script executed: #!/bin/bash
# Look for the main Containers class file
fd -t f "\.php$" -x grep -l "class Containers" {} \;Length of output: 314 🏁 Script executed: #!/bin/bash
# Search for RestartPolicy, Mount, Volume classes
rg -nP "class (RestartPolicy|Mount|Volume|Tmpfs|Bind)" --type phpLength of output: 236 🏁 Script executed: #!/bin/bash
# Find method signatures for pull and run
rg -nP "function (pull|run)\s*\(" --type php -A 3 -B 1Length of output: 2371 I need to see the complete 🏁 Script executed: #!/bin/bash
# Get full run() signature from Containers.php
sed -n '74,95p' src/Containers/Containers.phpLength of output: 850 🏁 Script executed: #!/bin/bash
# Get full run() signature from Adapter.php
sed -n '40,65p' src/Containers/Adapter.phpLength of output: 660 🏁 Script executed: #!/bin/bash
# Check RestartPolicy class
cat src/Containers/RestartPolicy.phpLength of output: 193 🏁 Script executed: #!/bin/bash
# Check Mount interface
cat src/Containers/Mount.phpLength of output: 137 🏁 Script executed: #!/bin/bash
# Check Bind class structure
cat src/Containers/Mount/Bind.phpLength of output: 411 🏁 Script executed: #!/bin/bash
# Get full DockerAPI run() signature for comparison
sed -n '486,510p' src/Containers/Adapter/DockerAPI.phpLength of output: 847 README documentation drift confirmed; also note DockerAPI implementation inconsistency The review comment is correct. The README still documents the v1 API while the Containers/Adapter contract has evolved to v2:
Also note: DockerAPI implementation (src/Containers/Adapter/DockerAPI.php) does not conform to the Adapter contract—it still has the old signatures ( Update README lines 75–112 to document the current v2 API, and ensure DockerAPI implements the Adapter contract correctly. 🧰 Tools🪛 LanguageTool[grammar] ~9-~9: Use a hyphen to join words. (QB_NEW_EN_HYPHEN) 🤖 Prompt for AI Agents |
||
|
|
||
| ### Example | ||
|
|
@@ -21,26 +21,26 @@ composer require utopia-php/orchestration | |
|
|
||
| require_once 'vendor/autoload.php'; | ||
|
|
||
| use Utopia\Orchestration\Orchestration; | ||
| use Utopia\Orchestration\Adapter\DockerCLI; | ||
| use Utopia\Containers\Containers; | ||
| use Utopia\Containers\Adapter\DockerCLI; | ||
|
|
||
| // Initialise Orchestration with Docker CLI adapter. | ||
| $orchestration = new Orchestration(new DockerCLI()); | ||
| // Initialise Containers with Docker CLI adapter. | ||
| $containers = new Containers(new DockerCLI()); | ||
|
|
||
| // Pull the image. | ||
| $orchestration->pull('ubuntu:latest'); | ||
| $containers->pull('ubuntu:latest'); | ||
|
|
||
| // Launch a ubuntu container that doesn't end using the tail command. | ||
| $containerID = $orchestration->run('ubuntu:latest', 'testContainer', ['tail', '-f', '/dev/null']); | ||
| $containerID = $containers->run('ubuntu:latest', 'testContainer', ['tail', '-f', '/dev/null']); | ||
|
|
||
| $stderr = ''; | ||
| $stdout = ''; | ||
|
|
||
| // Execute a hello world command in the container | ||
| $orchestration->execute($containerID, ['echo', 'Hello World!'], $stdout, $stderr); | ||
| $containers->execute($containerID, ['echo', 'Hello World!'], $stdout, $stderr); | ||
|
|
||
| // Remove the container forcefully since it's still running. | ||
| $orchestration->remove($containerID, true); | ||
| $containers->remove($containerID, true); | ||
| ``` | ||
|
|
||
| ## Usage | ||
|
|
@@ -53,30 +53,30 @@ There are currently two orchestrator adapters available and each of them has sli | |
| Directly communicates to the Docker Daemon using the Docker UNIX socket. | ||
|
|
||
| ```php | ||
| use Utopia\Orchestration\Orchestration; | ||
| use Utopia\Orchestration\Adapter\DockerAPI; | ||
| use Utopia\Containers\Containers; | ||
| use Utopia\Containers\Adapter\DockerAPI; | ||
|
|
||
| $orchestration = new Orchestration(new DockerAPI($username, $password, $email)); | ||
| $containers = new Containers(new DockerAPI($username, $password, $email)); | ||
| ``` | ||
| $username, $password and $email are optional and are only used to pull private images from Docker Hub. | ||
|
|
||
| - ### DockerCLI | ||
| Uses the Docker CLI to communicate to the Docker Daemon. | ||
| ```php | ||
| use Utopia\Orchestration\Orchestration; | ||
| use Utopia\Orchestration\Adapter\DockerCLI; | ||
| use Utopia\Containers\Containers; | ||
| use Utopia\Containers\Adapter\DockerCLI; | ||
|
|
||
| $orchestration = new Orchestration(new DockerCLI($username, $password)); | ||
| $containers = new Containers(new DockerCLI($username, $password)); | ||
| ``` | ||
| $username and $password are optional and are only used to pull private images from Docker Hub. | ||
|
|
||
| Once you have initialised your Orchestration object the following methods can be used: | ||
| Once you have initialised your Containers object the following methods can be used: | ||
|
|
||
| - ### Pulling an image | ||
| This method pulls the image requested from the orchestrators registry. It will return a boolean value indicating if the image was pulled successfully. | ||
|
|
||
| ```php | ||
| $orchestration->pull('image:tag'); | ||
| $containers->pull('image:tag'); | ||
| ``` | ||
|
|
||
| <details> | ||
|
|
@@ -96,7 +96,7 @@ Once you have initialised your Orchestration object the following methods can be | |
| This method creates and runs a new container. On success, it will return a string containing the container ID. On failure, it will throw an exception. | ||
|
|
||
| ```php | ||
| $orchestration->run( | ||
| $containers->run( | ||
| 'image:tag', | ||
| 'name', | ||
| ['echo', 'hello world!'], | ||
|
|
@@ -219,7 +219,7 @@ Once you have initialised your Orchestration object the following methods can be | |
| This method removes a container and returns a boolean value indicating if the container was removed successfully. | ||
|
|
||
| ```php | ||
| $orchestration->remove('container_id', true); | ||
| $containers->remove('container_id', true); | ||
| ``` | ||
|
|
||
| <details> | ||
|
|
@@ -243,7 +243,7 @@ Once you have initialised your Orchestration object the following methods can be | |
| This method returns an array of containers. | ||
|
|
||
| ```php | ||
| $orchestration->list(['label' => 'value']); | ||
| $containers->list(['label' => 'value']); | ||
| ``` | ||
|
|
||
| <details> | ||
|
|
@@ -263,7 +263,7 @@ Once you have initialised your Orchestration object the following methods can be | |
| This method returns an array of networks. | ||
|
|
||
| ```php | ||
| $orchestration->listNetworks(); | ||
| $containers->listNetworks(); | ||
| ``` | ||
|
|
||
| <details> | ||
|
|
@@ -281,7 +281,7 @@ Once you have initialised your Orchestration object the following methods can be | |
| This method creates a new network and returns a boolean value indicating if the network was created successfully. | ||
|
|
||
| ```php | ||
| $orchestration->createNetwork('name', false); | ||
| $containers->createNetwork('name', false); | ||
| ``` | ||
|
|
||
| <details> | ||
|
|
@@ -305,7 +305,7 @@ Once you have initialised your Orchestration object the following methods can be | |
| This method removes a network and returns a boolean value indicating if the network was removed successfully. | ||
|
|
||
| ```php | ||
| $orchestration->removeNetwork('network_id'); | ||
| $containers->removeNetwork('network_id'); | ||
| ``` | ||
|
|
||
| <details> | ||
|
|
@@ -325,7 +325,7 @@ Once you have initialised your Orchestration object the following methods can be | |
| This method connects a container to a network and returns a boolean value indicating if the connection was successful. | ||
|
|
||
| ```php | ||
| $orchestration->connect('container_id', 'network_id'); | ||
| $containers->connect('container_id', 'network_id'); | ||
| ``` | ||
|
|
||
| <details> | ||
|
|
@@ -349,7 +349,7 @@ Once you have initialised your Orchestration object the following methods can be | |
| This method disconnects a container from a network and returns a boolean value indicating if the removal was successful. | ||
|
|
||
| ```php | ||
| $orchestration->disconnect('container_id', 'network_id', false); | ||
| $containers->disconnect('container_id', 'network_id', false); | ||
| ``` | ||
|
|
||
| <details> | ||
|
|
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,8 +1,8 @@ | ||
| { | ||
| "name": "utopia-php/orchestration", | ||
| "description": "Lite & fast micro PHP abstraction library for container orchestration", | ||
| "name": "utopia-php/containers", | ||
| "description": "Lite & fast micro PHP abstraction library for container containers", | ||
| "type": "library", | ||
| "keywords": ["php","framework", "upf", "utopia", "orchestration", "docker", "swarm", "kubernetes"], | ||
| "keywords": ["php","framework", "upf", "utopia", "containers", "docker", "swarm", "kubernetes"], | ||
| "license": "MIT", | ||
|
Comment on lines
+2
to
6
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Minor metadata fixes: description wording and consistency The
Otherwise the autoload mappings and keywords are consistent with the new namespace. Also applies to: 14-19 🤖 Prompt for AI Agents |
||
| "minimum-stability": "stable", | ||
| "scripts": { | ||
|
|
@@ -12,10 +12,10 @@ | |
| "format": "./vendor/bin/pint" | ||
| }, | ||
| "autoload": { | ||
| "psr-4": {"Utopia\\Orchestration\\": "src/Orchestration"} | ||
| "psr-4": {"Utopia\\Containers\\": "src/Containers"} | ||
| }, | ||
| "autoload-dev": { | ||
| "psr-4": {"Utopia\\Tests\\": "tests/Orchestration"} | ||
| "psr-4": {"Utopia\\Tests\\": "tests/Containers"} | ||
| }, | ||
| "require": { | ||
| "php": ">=8.0", | ||
|
|
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,68 @@ | ||
| <?php | ||
|
|
||
| namespace Utopia\Containers; | ||
|
|
||
| use Utopia\Containers\Usage; | ||
|
|
||
| abstract class Adapter | ||
|
Comment on lines
+3
to
+7
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🧩 Analysis chainAdapter contract mostly looks good, but clean up imports and ensure A few points on this new abstraction:
After fixing the import, aligning Also applies to: 19-31 🏁 Script executed: #!/bin/bash
# View Adapter.php file to see full contract
cat src/Containers/Adapter.phpLength of output: 1785 🏁 Script executed: #!/bin/bash
# Find and view DockerCLI implementation
find . -name "DockerCLI.php" -o -name "DockerAPI.php" | head -5Length of output: 77 🏁 Script executed: #!/bin/bash
# Find Networks class
find . -name "Networks.php" | head -5Length of output: 29 🏁 Script executed: #!/bin/bash
# Search for other adapter implementations
find . -path "*/Containers/*" -name "*.php" -type f | grep -i adapterLength of output: 196 🏁 Script executed: #!/bin/bash
# Check PHP version and Pint configuration for linting
ls -la | grep -E 'pint|phpstan|composer'Length of output: 187 🏁 Script executed: #!/bin/bash
# View DockerCLI implementation
cat src/Containers/Adapter/DockerCLI.phpLength of output: 14679 🏁 Script executed: #!/bin/bash
# View DockerAPI implementation
cat src/Containers/Adapter/DockerAPI.phpLength of output: 21754 🏁 Script executed: #!/bin/bash
# View Networks class
cat src/Containers/Networks.phpLength of output: 1350 🏁 Script executed: #!/bin/bash
# Check DockerAPI class declaration and inheritance
head -20 src/Containers/Adapter/DockerAPI.phpLength of output: 508 🏁 Script executed: #!/bin/bash
# Check pint configuration
cat pint.jsonLength of output: 391 Fix Adapter contract: clean import, add return types, align getUsage implementation across adapters Three confirmed issues:
|
||
| { | ||
| abstract public function createNetwork(string $name, bool $internal): void; | ||
|
|
||
| abstract public function removeNetwork(string $name): void; | ||
|
|
||
| abstract public function networkExists(string $name): bool; | ||
|
|
||
| abstract public function connect(string $container, string $network): void; | ||
|
|
||
| abstract public function disconnect(string $container, string $network, bool $force); | ||
|
|
||
| /** | ||
| * @return list<Network> | ||
| */ | ||
| abstract public function listNetworks(): array; | ||
|
|
||
| abstract public function getUsage(string $container): ?Usage; | ||
|
|
||
| /** | ||
| * @param array<string, string> $filters | ||
| * @return array<string, Usage> Map of container ids to usage stats | ||
| */ | ||
| abstract public function listUsage(array $filters): array; | ||
|
|
||
| abstract public function pull(string $image): void; | ||
|
|
||
| /** | ||
| * @param array<string, string> $filters | ||
| * @return Container[] | ||
| */ | ||
| abstract public function list(array $filters): array; | ||
|
|
||
| abstract public function run( | ||
| string $name, | ||
| string $image, | ||
| string $hostname, | ||
| array $command, | ||
| array $entrypoint, | ||
| ?string $workdir, | ||
| array $environment, | ||
| array $mounts, | ||
| array $labels, | ||
| ?string $network, | ||
| ?float $cpus, | ||
| ?int $memory, | ||
| ?int $swap, | ||
| RestartPolicy $restart, | ||
| bool $remove, | ||
| ): string; | ||
|
|
||
| /** | ||
| * @param string[] $command | ||
| * @param array<string, string> $vars | ||
| */ | ||
| abstract public function execute(string $name, array $command, string &$output, array $vars, int $timeout): bool; | ||
|
|
||
| /** | ||
| * Remove Container | ||
| */ | ||
| abstract public function remove(string $name, bool $force): bool; | ||
| } | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Minor language fixes in introduction
Two small text issues flagged by tooling:
Not critical, but easy polish for the new package branding.
🧰 Tools
🪛 LanguageTool
[grammar] ~9-~9: Use a hyphen to join words.
Context: ...-php/framework) project it is dependency free and can be used as standalone with ...
(QB_NEW_EN_HYPHEN)
🤖 Prompt for AI Agents