How to Run a PHP Script in CLI Mode Only

How to run a php script in cli mode only

PHP is a great programming language to use for something that's beyond the basics of static HTML. Nearly all of your PHP processing (or at least a huge percentage of it), will be when handling HTTP requests. That would be something like a login screen, processing a user's credentials, and for that, you'll be using your PHP script. But there are times, mainly when running CRON jobs, or message queues when you don't want the given script to be runnable via a simple HTTP request. For that, you'd want to keep it protected behind the command line. But why might this occur, what are the benefits, and how do you modify your code, to allow PHP scripts to only run in CLI mode, let's find out in this PHP guide.

What is the CLI?

The command line interface, better known in the industry as just, CLI, is a way to run scripts and computer commands, supported on all operating system variations, including Windows 10 and 11, Apple Mac, and all Linux-style distributions. It allows users to use the operating system without the need for a graphic interface. With that in mind, in web development, it means you can perform actions on your web application, without the need to go via a browser. Because of this, the CLI becomes a highly useful way to automate tasks. There are many examples of tasks that you'd likely want to automate, from clearing shopping baskets, to data processing. Using the CLI to automate means that can be run at any point, without directly impacting a user's page load. Therefore the CLI is a powerful tool that all developers will at some point be required to use, so let's find out how to use the CLI to run your PHP scripts and how to start automating more tasks.

How can I use the CLI to run PHP scripts?

To get started, first find out your PHP version, and ensure PHP is installed on your machine or server. On the command line type the following command as shown below. This is the most basic way to start using PHP on the CLI. Sometimes the CLI can seem a little intimidating at first, especially if you've never used the CLI before, but it is something you can practice on your local machine before attempting it on a production server.

php -v

To run a PHP script, you can perform the following on the command line.

php -f my_script.php

# or you can omit the -f flag
php my_script.php

How do I prevent a PHP script from only running in CLI mode?

Within your PHP script, if the logic is only to be run in CLI mode and you wish to prevent it from running when directly called by an HTTP request, you can use the php_sapi_name PHP function. This function is the easiest way to find out the type of interface running between your web server and PHP. This function will return a lowercase string value with the type of interface PHP is using. Therefore, when running a PHP script on the command line, the returned string would be "cli".

# Put this at the very top of your PHP script
if (php_sapi_name() !== 'cli') {
 echo 'Run this script via the command line instead.';
 die;
}

What is the PHP function php_sapi_name?

You can also just use the PHP constant PHP_SAPI which will return the same value as php_sapi_name. The type of interface will differ based on your server setup, for example, possible values include, litespeed, fpm-fcgi, or apache.

How can I run PHP scripts on servers running Plesk on the CLI?

When running a Plesk server, Plesk normally handles and loads PHP, outside of what you might not expect. Running 'php -v' may error asking if you'd like to install PHP. Instead, check your Plesk server has PHP installed by browsing the following;

# On Linux
cd /opt/plesk/php/

# On Windows
cd %plesk_dir%Additional\

Then, depending on your current installed PHP version, you can run a PHP script the same way

# On Linux
/opt/plesk/php/php8.2/php -v

# On Windows
%plesk_dir%Additional\PHP82\php.exe -v

How can I run PHP scripts on the CLI with arguments?

You can also pass arguments on the command line too, which is a great way to automate different tasks, away from the same repetitive task. Luckily, PHP accepts arguments from the CLI, and the number passed. The predefined variable argv is populated when passing arguments and therefore is what can be used in your PHP script.

# Running my_script.php followed by one space and then each argument
php my_script.php arg1 arg2

# Outputs an array of arguments
array(
[0] => my_script.php
[1] => arg1
[2] => arg2
);

Conclusion

Using the PHP function php_sapi_name is a great way to quickly determine if a PHP script is being run from the CLI or not. If your script is to only be run on the CLI, then using this trick and preventing the rest of the script from running ensures that your logic stays behind a CLI request rather than an HTTP request.

  • php_sapi_name will return false on failure
  • The interface type return from php_sapi_name function is always lowercase
  • The first item in the arg variable is always the script name
  • If 'register_argc_argv' is disabled, the argv variable won't be set.

Senior PHP developer. Author of Dev Lateral guides and tools. The complete place for PHP programmers. Available to hire to help you build or maintain your PHP application.

Looking for industry-leading PHP web development?

API development WordPress Hosting ★ and more 🐘

We use cookies to enhance your browsing experience, and analyse website traffic in accordance with our Privacy and Cookie Policy. Our cookies, including those provided by third parties, collect anonymous information about website usage and may be used for targeted advertising purposes. By clicking "Reject non-essential" you can opt out of non-essential cookies. By clicking "Accept all" you agree to the use of all cookies.


Reject non-essential Accept all