How do i run a command line argument in php?

Any PHP code that we write is usually run on the server when users request a webpage. However, it is also possible to run a script through a CLI or command-line interface. Sometimes it becomes necessary to write PHP scripts that can accept arguments when executed inside a command prompt. There can be a variety of reasons for doing this, ranging from ease of use to automation of specific tasks.

In this tutorial, you will learn how to access command-line arguments inside your script with $argv and getopt[] in PHP.

Why Do We Need Them?

Arguments are passed around as query parameters when you request a page from your web browser. On the server side, we access the values inside these parameters using the superglobal $_GET. Unfortunately, this technique won't work when you are running your script inside the command prompt. This is because a command prompt expects arguments for its script in a different format.

Let's create a simple script to better understand the problem. Put the following code inside a file called reverse.php.

Now, try to run the following command from the directory in which the file reverse.php is located.

php reverse.php?n=monty

This will give you an error similar to the following line.

Could not open input file: reverse.php?name=monty

This happens because the system tries to run a file called reverse.php?n=monty within the current directory, but there is no such file.

You can run the following command successfully, but it still won't output the reversed name.

php reverse.php monty

It will show a warning about an undefined array key "n" instead. The use of $argv and getopt[] solves this problem for us.

Get Command-Line Arguments With $argv

There are two predefined variables in PHP, called $argc and $argv, that you can use to work with command-line arguments.

The variable $argc simply tells you the number of arguments that were passed to the script. Remember that the name of the script you are running is always counted as an argument. This means that the minimum value of $argc would be 1.

The variable $argv is much more helpful because it is an array of arguments passed to the script and contains their actual value. You can iterate over all the values with a foreach loop.

Let's create a script to change the brightness and contrast of JPEG images. The script will accept three parameters besides its name: the name of the file, desired brightness, and desired contrast. Put the following code in a file called im-filters.php.

We create an array with three elements and autofill it with null. Now, we loop over the command-line arguments and put their values inside our $filters array. We have skipped the first argument because that's the name of the script itself. The name of the new file is created by adding -edited at the end of the original file name.

Now, run the following command in the terminal:

php im-filters.php beach.jpg -40 -20

This should create the following output in the terminal, while generating a file called beach-edited.jpg.

Edited Image: beach.jpg [Brightness: -40 and Contrast: -20]

Get Command-Line Arguments With getopt[]

There are a few shortcomings in the method that we used to access command-line arguments in our previous example. For instance, we are assuming that the arguments will be provided in the order in which we are processing them in the script. However, that might not always be the case.

The getopt[] function in PHP is a great way for accessing all these arguments without worrying too much about their order, etc. It has one required parameter and two optional parameters.

1. short_options: Short options in the command line start with a single hyphen. Each character passed into this string is matched against the options passed to the script.
2. long_options:This optional parameter accepts an array. Each element [a string] in the array is matched against the options passed to the script starting with two hyphens.
3. rest_index:The optional third parameter is used to store the index at which the parsing of arguments stopped.

Both short_options and long_options follow a specific convention to parse values passed to the script. Individual characters and strings don't accept any values. Characters and strings followed by a colon indicate a required value. Characters and strings followed by two colons indicate an optional value. Here are some examples:

1. -g and --grayscale will not accept any values. We will use them in our script to convert images to grayscale.
2. -f: and --filename: will both require a value passed to them. We will use them to make sure that users provide us an image file on which we can apply our filters.
3. -c:: and --contrast:: will both accept an optional value. We will use them to give users the option to not change the contrast of the image unnecessarily. The same goes for -b:: and --brightness::.

One thing you should remember is that the array returned by getopt[] does not contain elements which were missing from the argument list. Also, the elements present in the argument list which did not have a specified value are set to false.

Now it's time to create our script with all these points in mind.

We accept four different arguments for our image editing script and have set only the filename to be required. The grayscale filter does not accept any parameter, so we have marked it as such.

We check if the value has been supplied with a long-form or short-form option for each of our arguments. The code inside the if block will execute in either case. After that, the ternary operator allows us to pick the correct form to get our value with a single statement. For example, let's say a user has provided a contrast value using the long-form option. In this case, isset[$options["c"]] will be false, and $contrast will be set according to the value in $options["contrast"].

The $filter_list string is used to keep track of all the filters applied to the image to show them to the user.

Try running the following command in the console now.

php im-filters.php --filename="beach.jpg" --grayscale -c-20 --brightness="-30"

It should show you the following output:

Edited Image: beach.jpg Grayscale Brightness:-30 Contrast:-20

Avoiding Script Duplication

We have seen that different code needs to be used to access argument values when the script runs on a web server vs. when it runs in a CLI. However, this does not mean that you will require two copies of the same script to run in different environments. There is a function called php_sapi_name[] that will tell you whether your code is running inside a web server or a CLI. The predefined constant PHP_SAPI serves the same purpose.

Final Thoughts

There are a lot of times when we have to write code that will work on some provided input to give us an output. Usually, the input is handled by $_GET and $_PUT when the script is running on a server. However, you will sometimes need to run your script through a CLI, and that requires you to use $argv or getopt[]. Using getopt[] gives you more flexibility when dealing with the arguments and does some heavy lifting regarding their parsing for you.

Try running the above script on your own images while changing the order of arguments. You should consider creating your own custom scripts to automate boring tasks with a task scheduler.

Did you find this post useful?

Freelancer, Instructor

I am a full-stack developer who also loves to write tutorials. After trying out a bunch of things till second year of college, I decided to work on my web development skills. Starting with just HTML and CSS, I kept moving forward and gained experience in PHP, JavaScript and Python. I usually spend my free time either working on some side projects or traveling around.

How do I pass a command line argument in PHP?

Can we use PHP for command line scripts?

How do I run a PHP script?

How do I echo in PHP terminal?