7 days of WordPress plugins, themes & templates - for free!* Unlimited asset downloads! Start 7-Day Free Trial
  1. Code
  2. PHP

Get Command-Line Arguments With PHP $argv or getopt()

Read Time: 7 mins

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.

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

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.

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:

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

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.

It should show you the following output:

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?
Want a weekly email summary?
Subscribe below and we’ll send you a weekly email summary of all new Code tutorials. Never miss out on learning about the next big thing.
Scroll to top
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.