Return codes of all functions

[danshumaker]

I've got a deploy recipe that I'm writing for Magento 2. It has a very complicated setup with several stages I need to check before doing things like compiling code ( https://devdocs.magento.com/guides/v2.3/config-guide/cli/config-cli-subcommands-compiler.html ).

What I'd like to do in the recipe is something like

db_status = run('bin/magento setup:db:status');
app_status = run('bin/magento app:config:status');
ready = db_status && app_status;
if (ready) {
   run('bin/magento setup:di:compile');
}

I'm looking in the docs for deployer ( https://deployer.org/docs/7.x/api#task) and none of the functions document their return code.

Can we add all the functions return codes to the documentation? Will they return the linux code return code?

When those commands return errors I don't want my git lab ci job to fail, I just want deployer to skip the current step.

It's sort of a chicken egg issue but I figure we all have similar issues when setting up deploys for the first time.

[antonmedv]

I didn't get it. What codes?

[danshumaker]

Often times when documenting a function in an API you specify the arguments/parameters and the return codes/values (for example https://www.php.net/manual/en/function.array-map.php see return values section.)

For linux processes you also get return codes/values (https://shapeshed.com/unix-exit-codes/) . Any value greater than 0 is considered an error. I would like to trap that value coming from my command ( https://devdocs.magento.com/guides/v2.4/config-guide/cli/config-cli-subcommands-compiler.html in this case) , but if your "run" function doesn't return what linux returns then it won't do me much good to act upon it.

Does that make sense?

I can dig into your actual code to determine if the run command returns the numeric value from linux, but I thought that perhaps a quicker way to find out would be to check the documentation. But I don't see return codes/values listed there, but I do see the normal parameters described.

[peterjaap]

All of this is already done in the default Magento 2 recipe; https://github.com/deployphp/deployer/blob/master/recipe/magento2.php#L147

It would be best to use that recipe, at least as a base. But if you want to write one completely custom, fine too, but there's your example.

The reason why it doesn't work the way you expect it to work is because the functions aren't run synchronously but using a callback, see here.

[antonmedv]

Func run return output only if exit code is 0. Otherwise throws an exception with exit code.

[danshumaker]

I see the docs do have some indication of return codes in the function definition.

run(string $command, ?array $options = [], ?int $timeout = null, ?int $idle_timeout = null, ?string $secret = null, ?array $env = null, ?bool $real_time_output = false, ?bool $no_throw = false): string 

Which says it should be a string return value. Similarly https://deployer.org/docs/7.x/api#test Says test returns a bool.

test(string $command): bool

So it's up to the user to read the function definition to determine the return value. Which is good and bad. It's good that it's printed in the docs. But bad because it would be nice to have a little bit more feedback capabilities in the processes that are launched since deployer is indeed a fancy process launcher (task runner). So for invoke , I'd love to see more than a void return value.

invoke(string $taskName): void

I understand the difficulty in that implementation suggestion. But it would be helpful to perhaps have a todo task or note in the documentation saying "Until process feedback is implemented - then no return values are given." .... Or something to that effect.
Not a big deal, just trying to be helpful.

And thank you @peterjaap , that function link to the callback method helped me understand under the hood what's going on.
And yes, I'm using the contrib magento2.php recipe as a base but found that during Magento setup it wasn't sufficient for my needs. I'm attempting to use yaml config task definitions for Deployer 7 ( https://github.com/unleashedtech/deployer-recipes/blob/magento2/cms/magento/2.yml )

[danshumaker]

@antonmedv These are the types of exit codes I was talking about https://github.com/symfony/process/blob/bf0e245dd8f115502d11df04cdb91c49abbc83ec/Process.php#L91

with perhaps a usage of https://github.com/symfony/process/blob/bf0e245dd8f115502d11df04cdb91c49abbc83ec/Process.php#L751 (getExitCode)

[antonmedv]

Catch the exception. Get error core from it.