writing command line scripts in php: part 1; args, preflighting and more
php has a lot of strengths as a web language, but it is also perfectly serviceable for general-purpose scripting. in this series of posts we’re going to go over building command line scripts in php. this is part one.
why even do this?
- reuse of existing code: if you have a php web application and you wish to write a command line interface to leverage some or all of its functionality, it makes much more sense to use php for your script and re-use your existing code, rather than rewrite everything from scratch in, say, python.
- available skills: if you or your team is long on php skills and short on python or bash, it often makes sense to just play to your strengths.
- the language itself: php is actually a pretty powerful language for command scripting. not only does it provide all the standard features, but it also gives us access to things like handling signals, forking processes and even semaphores if we need it.
assumptions
we’re going to be looking at writing command line scripts for unix-like operating systems. all the examples here were built on ubuntu 20.04 using php 7.4.9.
the flyover
in this installment, we’re going to go over:
- making our php script runnable on the command line
- preflighting our environment to ensure our script runs right
- parsing common command line argument strucutres, and finally
- giving our script a nice name that ps recognizes
first, make it runnable
traditionally, when running a php script on the command line, you invoke the php command and pass the script as an argument, ie php /path/to/my/script.php . this works, but is ugly.
to fix this, we’ll be putting a shebang at the top of our php script. the shebang is a specially-formatted first line that informs the operating system which interpreter to use when executing the script. if you’ve done any shell scripting, you’re probably familiar with #!/bin/bash . that’s a shebang.
let’s open our sample script ourfancyscript.php in the editor of our choice and add:
one thing that we notice about this shebang is that it calls env . normally, in shell scripting, we reference the direct path to bash with #!/bin/bash . but, here, we’ll be calling env so that the operating system searches the user’s $PATH to find the php intepreter. this is important since, while bash is almost always in /bin , we have no guarantee that we know where the php interpreter lives. using env in our shebang helps increase the portability of our script across different systems. that’s a good thing.
now that we have our shebang, we’ll set our script to be executable. we’ll use the standard permssions set for this:
chmod 755 ourfancyscript.php once we have the execution permissions set, we can run the script simply by calling it:
of course, the script does nothing, but it actually does do that nothing. so that’s progress.
preflight
when we write php for a web application, we generally have a good idea of the environment it will run in. we provisioned the web server, after all.
command line scripts, however, are a different story. we have no control over the environment. it’s someone else’s computer.
with that in mind, it’s good idea to always start your script with a call to a ‘preflight’ function that confirms the system has everything necessary to run the script. if any of our preflight tests do not pass, we can halt the script with an appropriate error instead of just barging ahead and making a mess.
common things we can check for in our preflight include:
minimum php version: of course we’re writing for the lowest possible php version we can (portability and all!), but we should still check that we meet the minimum version. keep in mind that a three year-old amazon linux ec2 runs php 5.3 by default!
checking the php version is as straightforward as a call to the built-in phpversion() command.
necessary extensions are loaded: if our script calls for an extension, we should make sure that it’s actually loaded before we start. we can do this with the built-in command extension_loaded(). so, for instance, if we want to confirm php has ‘imagick’ available, we could test that in our ‘preflight’ function like so:
if (!extension_loaded('imagick')) die('imagick extension required. exiting.'); > file access: we may want to read files or write to files or directories. it’s a good idea to confirm that the user running our script has permissions to do that before starting. php has a number of built-in commands to accomplish this:
- file_exists to confirm if the file exists
- is_dir to determine if the file is a directory
- is_writable() to test if the user has write access to the file or directory
let’s put all of that together into a short sample preflight function:
#!/usr/bin/env php /** * Confirm system can run script */ function preflight() $phpversion_array = explode('.', phpversion()); if ((int)$phpversion_array[0].$phpversion_array[1] 56) die('minimum php required is 5.6. exiting'); > if(!extension_loaded('posix')) die('posix required. exiting'); > if(!is_writable('/tmp')) die('must be able to write to /tmp to continue. exiting.'); > if(!file_exists(posix_getpwuid(posix_getuid())['dir'].'/.aws/credentials')) die('an aws credentials file is required. exiting'); > > in the first if block of this function we check the php version is at least 5.6. we do a little clumsy casting here to accomplish this as we only care about the major and minor numbers.
next, we confirm that the posix extension is loaded. posix is basically a set of standard ways to interface with the host operating system. definitely something we will want for our script.
we then do a fast confirmation that we can write to the /tmp directory and, finally, determine that the user has an aws credentials file.
one thing to note is in the last if block, we used a couple of those posix commands to get the running user’s home directory. the ‘~/’ construction will not work here. instead, we get the user’s id number with posix_getuid() and then pass that to posix_getpwuid() to get an array of information about the user, including their home directory, from the /etc/passwd file.
parse command line arguments
handling command line arguments and switches is something most scripts need to do, so we’re going to write a short function that takes the arguments passed to our script and processes them into an array that we can reference later when determining what functionality to provide.
this function handles four basic types of arguments:
switches
these are single letter arguments that are preceded by a dash, think the -a argument to ls to show hidden files.
long switches
these are the same as switches except. longer. an example would be curl accepting —silent as a synonym for -s . long switches are preceded by two dashes.
asignments
this is for passing data into our script. assignment arguments take two dashes and use an equal sign to indicate the value, ie. —outfile=/path/to/file or mysql’s horrifying —password=mynothiddenpassword .
positional arguments
these are arguments without any preceding dashes; their usage is determined entirely by their position. think the linux ‘move’ command mv /path/to/origin /path/to/destination . there are two positional arguments here, and we know which value is assigned to the origin and which to the destination by the order they are written in.
with that in mind, we can add this function to our command line scripts to parse arguments for us:
#!/usr/bin/env php /** * Parses command line args and returns array of args and their values * * @param Array $args The array from $argv * @return Array */ function parseargs($args) $parsed_args = []; $args = array_slice($args, 1); for ($i=0;$icount($args);$i++) switch (substr_count($args[$i], "-", 0, 2)) case 1: foreach (str_split(ltrim($args[$i], "-")) as $a) $parsed_args[$a] = isset($parsed_args[$a]) ? $parsed_args[$a] + 1 : 1; > break; case 2: $parsed_args[ltrim(preg_replace("/=.*/", '', $args[$i]), '-')] = strpos($args[$i], '=') !== false ? substr($args[$i], strpos($args[$i], '=') + 1) : 1; break; default: $parsed_args['positional'][] = $args[$i]; > > return $parsed_args; > we can then call that function in our script with
$our_parsed_args = parseargs($argv); $argv
Содержит массив ( array ) всех аргументов, переданных скрипту при запуске из командной строки.
Замечание: Первый аргумент $argv[0] всегда содержит имя файла запущенного скрипта.
Замечание: Эта переменная недоступна, если register_argc_argv отключён.
Примеры
Пример #1 Пример использования $argv
Запустим пример в командной строке: php script.php arg1 arg2 arg3
Результатом выполнения данного примера будет что-то подобное:
array(4) < [0]=>string(10) "script.php" [1]=> string(4) "arg1" [2]=> string(4) "arg2" [3]=> string(4) "arg3" >
Примечания
Смотрите также
User Contributed Notes 6 notes
Please note that, $argv and $argc need to be declared global, while trying to access within a class method.
class A
public static function b ()
var_dump ( $argv );
var_dump (isset( $argv ));
>
>
A :: b ();
?>
will output NULL bool(false) with a notice of «Undefined variable . «
whereas global $argv fixes that.
To use $_GET so you dont need to support both if it could be used from command line and from web browser.
foreach ($argv as $arg) $e=explode(» note» >
You can reinitialize the argument variables for web applications.
So if you created a command line, with some additional tweaks you can make it work on the web.
If you come from a shell scripting background, you might expect to find this topic under the heading «positional parameters».
Sometimes $argv can be null, such as when «register-argc-argv» is set to false. In some cases I’ve found the variable is populated correctly when running «php-cli» instead of just «php» from the command line (or cron).
I discovered that `register_argc_argv` is alway OFF if you use php internal webserver, even if it is set to `On` in the php.ini.
What means there seems to be no way to access argv / argc in php internal commandline server.