Χρησιμοποιώντας την PHP από την γραμμή εντολών

Από την έκδοση 4.3.0, η PHP υποστηρίζει ένα νέο τύπο SAPI (Server Application Programming Interface) με όνομα CLI το οποίο σημαίνει Command Line Interface. Όπως υποδηλώνει το όνομα, το επίκεντρο αυτού του τύπου SAPI είναι η ανάπτυξη εφαρμογών για το shell (ή επίσης για desktop) με την PHP. Υπάρχουν αρκετές διαφορές μεταξύ του CLI SAPI και άλλων SAPI τα οποία εξηγούνται σε αυτό το κεφάλαιο. Αξίζει να σημειωθεί πως το CLI και το CGI είναι διαφορετικά SAPI αν και μοιράζονται πολλές ίδιες συμπεριφορές.

Το CLI SAPI έχει κυκλοφορήσει για πρώτο φορά με την PHP 4.2.0, αλλά ήταν ακόμη πειραματικό και έπρεπε να ενεργοποιηθεί ρητά με το --enable-cli όταν έτρεχε το ./configure. Από την PHP 4.3.0 το CLI SAPI δεν είναι πλέον πειραματικό και η επιλογή --enable-cli είναι προεπιλεγμένα ενεργοποιημένη. Μπορείτε να χρησιμοποιήσετε το --disable-cli για να την απενεργοποιήσετε.

Από την PHP 4.3.0, το όνομα, τοποθεσία και η ύπαρξη των CLI/CGI binaries θα διαφέρει ανάλογα με τον τρόπο που εγκαταστάθηκε η PHP στο σύστημα σας. Ως προεπιλογή, όταν εκτελείται το make, τόσο το CGI όσο και το CLI γίνονται build και τοποθετούνται ως sapi/cgi/php και sapi/cli/php αντίστοιχα, στον κατάλογο του source της php. Θα προσέξετε πως και τα δύο έχουν όνομα php. Αυτό που συμβαίνει κατά τη διάρκεια του make install εξαρτάται από τη γραμμή του configure σας. Αν ένα module SAPI επιλεγεί στο configure, όπως το apxs, ή η επιλογή --disable-cgi χρησιμοποιηθεί, το CLI αντιγράφεται στο {PREFIX}/bin/php στη διάρκεια του make install αλλιώς το CGI τοποθετείται εκεί. Έτσι, για παράδειγμα, αν το --with--apxs βρίσκεται στην configure γραμμή σας, το CLI αντιγράφεται στο {PREFIX}/bin/php κατά τη διάρκεια του make install. Αν θέλετε να παρακάμψετε την εγκατάσταση του CGI binary, χρησιμοποιήστε το make install-cli μετά το make install. Εναλλακτικά μπορείτε να ορίσετε το --disable-cgi στην configure γραμμή σας.

Note: Επειδή τόσο το --enable-cli όσο και το --enable-cgi είναι ενεργοποιημένα by default (ως προεπιλογή), απλά έχοντας το --enable-cli στην configure γραμμή σας δεν σημαίνει απαραίτητα πως το CLI θα αντιγραφεί ως {PREFIX}/bin/php κατά το make install.

Τα windows πακέτα μεταξύ της PHP 4.2.0 και της PHP 4.2.3 έδιναν το CLI σαν php-cli.exe, έχοντας το στον ίδιο κατάλογο με το CGI php.exe. Από την PHP 4.3.0 το windows πακέτο δίνει το CLI σαν php.exe σε ένα ξεχωριστό κατάλογο με όνομα cli, έτσι cli/php.exe.

Note: Τι SAPI έχω; Από ένα shell, η εντολή php -v θα σας πει αν η php είναι CGI ή CLI. Δείτε επίσης τη συνάρτηση php_sapi_name() και τη σταθερά PHP_SAPI.

Note: Μια manual σελίδα του unix έχει προστεθεί στην PHP 4.3.2. Μπορείτε να την δείτε γράφοντας man php στο shell περιβάλλον σας.

Οι κύριες διαφορές του CLI SAPI συγκριτικά με το SAPI είναι:

• Αντίθετα με το CGI SAPI, δεν εκτυπώνονται headers στην έξοδο.

  Αν και το CGI SAPI προσφέρει ένα τρόπο για να μην φανούν HTTP headers, δεν υπάρχει παρόμοιος διακόπτης για να τους ενεργοποιήσει κανείς στο CLI SAPI.

  Το CLI ξεκινά σε quiet mode ως προεπιλογή, αν και ο -q διακόπτης κρατιέται για συμβατότητα για να μπορείτε να το χρησιμοποιείτε σε παλαιότερα CGI scripts.

  Δεν αλλάζει τον working κατάλογο σε αυτόν του script. (Ο διακόπτης -C υπάρχει για συμβατότητα)

  Απλά μηνύματα λάθους σε μορφή κειμένου (δεν υπάρχει HTML μορφοποίηση).

• Υπάρχουν συγκεκριμένα php.ini directives τα οποία γίνονται override από το CLI SAPI επειδή δεν έχουν νόημα σε shell περιβάλλοντα:

  php.ini directives που γίνονται οverride

  Directive	Προεπιλεγμένη τιμή του CLI SAPI	Σχόλια
  html_errors	FALSE	Μπορεί να είναι αρκετά δύσκολο να διαβαστούν τα μηνύματα σφαλμάτων στο shell όταν είναι γεμάτα με όλα εκείνα τα άσκοπα HTML tags, έτσι αυτό το έχει ως προεπιλογή το FALSE.
  implicit_flush	TRUE	Είναι θεμιτό οποιαδήποτε έξοδος προερχόμενη από τις print(), echo() και τους φίλους τους να γράφεται αμέσως στο output και να μην γίνονται cache σε κάποιο buffer. Μπορείτε ακόμη να χρησιμοποιήσετεoutput buffering αν θέλετε να αναβάλλετε ή να χειριστείτε το standard output.
  max_execution_time	0 (unlimited)	Λόγω των άπειρων δυνατοτήτων στη χρήση της PHP σε περιβάλλοντα shell, ο μέγιστος χρόνος εκτέλεσης έχει οριστεί να είναι απεριόριστος. Εκεί που οι εφαρμογές γραμμένες για το web συχνά εκτελούνται πολύ γρήγορα, οι shell εφαρμογές τείνουν να έχουν πολύ μεγαλύτερο χρόνο εκτέλεσης.
  register_argc_argv	TRUE	Επειδή αυτή η ρύθμιση είναι TRUE πάντα θα έχετε πρόσβαση στο argc (ο αριθμός των arguments που περνιούνται στην εφαρμογή) και το argv (array των ίδιων των argument) στο CLI SAPI. Από την PHP 4.3.0, οι PHP μεταβλητές $argc και $argv καταχωρούνται και τιμολογούνται με τις ανάλογες τιμές όταν χρησιμοποιείται το CLI SAPI. Πριν από αυτή την έκδοση, η δημιουργία αυτών των μεταβλητών συμπεριφερόταν όπως γίνεται στις CGI και MODULE εκδόσεις που απαιτούν το PHP directive register_globals να είναι ενεργοποιημένο. Ανεξάρτητα της έκδοσης ή της register_globals ρύθμισης, μπορείτε πάντα να πάτε μέσω του $_SERVER ή του $HTTP_SERVER_VARS. Για παράδειγμα: $_SERVER['argv']

  Note: Αυτά τα directives δεν μπορούν να αρχικοποιηθούν με κάποια άλλη τιμή από το αρχείο ρυθμίσεων php.ini ή ένα προσωπικό (αν οριστεί). Αυτός είναι ένας περιορισμός επειδή αυτές οι τιμές εφαρμόζονται μετά που αναλύονται όλα τα αρχεία ρυθμίσεων. Ωστόσο, οι τιμές τους μπορούν να αλλαχτούν κατά το runtime (κάτι το οποίο δεν έχει νόημα για όλα εκείνα τα directives, π.χ. register_argc_argv).
  

• Για να γίνει πιο εύκολη η εργασία στο περιβάλλον του shell, οι παρακάτω σταθερές ορίζονται:

  Σταθερές ειδικές για το CLI

  Σταθερά	Περιγραφή
  STDIN	Ένα ήδη ανοιχτό stream στο stdin. Αυτό αποθηκεύεται ανοίγοντας το με την $stdin = fopen('php://stdin', 'r');
  STDOUT	Ένα ήδη ανοιχτό stream στο stdout. Αυτό αποθηκεύεται ανοίγοντας το με την $stdout = fopen('php://stdout', 'w');
  STDERR	Ένα ήδη ανοιχτό stream στο stderr. Αυτό αποθηκεύεται ανοίγοντας το με την $stderr = fopen('php://stderr', 'w');

  Δεδομένων των παραπάνω, αδεν χρειάζεστε να ανοίξετε π.χ. ένα stream για το stderr οι ίδιοι, απλά χρησιμοποιήστε τη σταθερά αντί του ίδιου του stream resource:

  php -r 'fwrite(STDERR, "stderr\n");'
  Δεν χρειάζεται να κλείσετε ρητά αυτά τα stream, μια και κλείνονται αυτόματα από την PHP όταν το script τερματίζει.

• Το CLI SAPI δεν αλλάζει τον τρέχων κατάλογο στον κατάλογο του script που εκτελείται!

  Παράδειγμα που δείχνει τις διαφορές στο CGI SAPI:

  <?php
    /* Our simple test application named test.php*/
    echo getcwd(), "\n";
?>

  Όταν χρησιμοποιείτε την CGI έκδοση, η έξοδος είναι:

  $ pwd
  /tmp
  
  $ php -q another_directory/test.php
  /tmp/another_directory
  
       

  Αυτό δείχνει καθαρά ότι η PHP αλλάζει τον τρέχων κατάλογο σε αυτό του script που εκτελείται.

  Χρησιμοποιώντας το CLI SAPI γίνεται:

  $ pwd
  /tmp
  
  $ php -f another_directory/test.php
  /tmp
  
       

  Αυτό επιτρέπει μεγαλύτερη ευελιξία όταν γράφετε shell εργαλεία με την PHP.

  Note: Το CGI SAPI υποστηρίζει την CLI SAPI συμπεριφορά μέσω του -C switch όταν εκτελείται από την γραμμή εντολών.
  

Η λίστα των επιλογών του command line options που δίνεται με το PHP binary μπορούν να ερωτηθούν ανά πάσα στιγμή τρέχοντας την PHP με το -h switch:

Usage: php [options] [-f] <file> [args...]
       php [options] -r <code> [args...]
       php [options] [-- args...]
  -s               Display colour syntax highlighted source.
  -w               Display source with stripped comments and whitespace.
  -f <file>        Parse <file>.
  -v               Version number
  -c <path>|<file> Look for php.ini file in this directory
  -a               Run interactively
  -d foo[=bar]     Define INI entry foo with value 'bar'
  -e               Generate extended information for debugger/profiler
  -z <file>        Load Zend extension <file>.
  -l               Syntax check only (lint)
  -m               Show compiled in modules
  -i               PHP information
  -r <code>        Run PHP <code> without using script tags <?..?>
  -h               This help

  args...          Arguments passed to script. Use -- args when first argument 
                   starts with - or script is read from stdin

  

Το CLI SAPI έχει τρεις διαφορετικούς τρόπους για να πάρει τον PHP κώδικα που θέλετε να εκτελέσετε:

1. Λέγοντας της PHP να εκτελέσει ένα συγκεκριμένο αρχείο.

   php my_script.php
   
   php -f my_script.php
   
        

   Και οι δύο τρόποι (χρησιμοποιώντας το -f switch ή όχι) εκτελούν το αρχείο my_script.php. Μπορείτε να διαλέξετε οποιοδήποτε αρχείο για να εκτελεστεί - τα PHP script σας δεν χρειάζεται να τελειώνουν με την .php επέκταση αλλά μπορείτε να έχετε οποιοδήποτε όνομα ή επέκταση θέλετε.

2. Δίνοντας τον PHP κώδικα προς εκτέλεση κατ' ευθείαν στην γραμμή εντολών.

   php -r 'print_r(get_defined_constants());'
   
        

   Προσοχή πρέπει να δίνεται σχετικά με την αντικατάσταση των μεταβλητών του shell και τη χρήση εισαγωγικών (quoting).

   Note: Διαβάστε το παράδειγμα προσεκτικά, δεν υπάρχουν tags αρχής ή τέλους! Το -r switch απλά δεν τις χρειάζεται. Χρησιμοποιώντας τις θα οδηγήσει σε ένα σφάλμα του μεταφραστή.
   

3. Δίνοντας τον PHP κώδικα προς εκτέλεση μέσω του standard input (stdin).

   Αυτό δίνει την ισχυρή δυνατότητα δυναμικής δημιουργίας PHP κώδικα και τροφοδοσίας του στο binary, όπως φαίνεται σε αυτό το (φανταστικό) παράδειγμα:

   $ some_application | some_filter | php | sort -u >final_output.txt
   
        

Όπως οποιαδήποτε shell εφαρμογή, το PHP binary δέχεται ένα αριθμό από ορίσματα (arguments) αλλά το PHP script μπορεί επίσης να δεχτεί ορίσματα. Ο αριθμός των ορισμάτων που μπορούν να περαστούν στο script σας δεν περιορίζεται από την PHP (το shell έχει ένα ορισμένο όριο μεγέθους του αριθμού των χαρακτήρων που μπορούν να περαστούν, συνήθως δεν θα φτάσετε αυτό το όριο). Τα arguments που περνιούνται στο script σας είναι διαθέσιμα μέσω του global array $argv. Ο μηδενικός δείκτης (index) πάντα περιέχει το όνομα του script (το οποίο είναι - σε περίπτωση που ο PHP κώδικας έρχεται από είτε το standard input ή από το switch της γραμμής εντολών -r). Η δεύτερη registered global μεταβλητή είναι η $argc η οποία περιέχει τον αριθμό των στοιχείων στο $argv array (όχι τον αριθμό των arguments που δίνονται στο script).

Όσο τα arguments που θέλετε να περάσετε στο script σας δεν αρχίζουν με τον χαρακτήρα -, δεν υπάρχει τίποτα ιδιαίτερο που πρέπει να προσέξετε. Περνώντας ένα argument στο script σας το οποίο αρχίζει με - θα δημιουργήσει προβλήματα επειδή η ίδια η PHP νομίζει πως πρέπει να το χειριστεί. Για να το αποφύγετε αυτό, χρησιμοποιήστε το argument list separator (διαχωριστής) --. Μετά που αναλύεται αυτός ο διαχωριστής στην PHP, κάθε argument που ακολουθεί περνιέται ανέπαφος στο script σας.

# This will not execute the given code but will show the PHP usage
$ php -r 'var_dump($argv);' -h
Usage: php [options] [-f] <file> [args...]
[...]

# This will pass the '-h' argument to your script and prevent PHP from showing it's usage
$ php -r 'var_dump($argv);' -- -h
array(2) {
  [0]=>
  string(1) "-"
  [1]=>
  string(2) "-h"
}

 

Ωστόσο, υπάρχει ακόμη ένας τρόπος χρήσης της PHP για shell scripting. Μπορείτε να γράψετε ένα script όπου η πρώτη γραμμή αρχίζει με #!/usr/bin/php. Ακολουθώντας αυτό μπορείτε να τοποθετήσετε κανονικό PHP κώδικα μεταξύ των PHP tags αρχής και τέλους. Από τη στιγμή που έχετε ορίσει τα attribute εκτέλεσης του αρχείου κατάλληλα (π.χ. chmod +x test) το script σας μπορεί να εκτελεστεί όπως ένα κανονικό shell ή perl script:

$ chmod 755 test
$ ./test -h -- foo
array(4) {
  [0]=>
  string(6) "./test"
  [1]=>
  string(2) "-h"
  [2]=>
  string(2) "--"
  [3]=>
  string(3) "foo"
}

  

$ php -v
PHP 4.3.0 (cli), Copyright (c) 1997-2002 The PHP Group
Zend Engine v1.3.0, Copyright (c) 1998-2002 Zend Technologies

        

$ php -c /custom/directory/ my_script.php

$ php -c /custom/directory/custom-file.ini my_script.php

        

-d configuration_directive[=value]

        

# Omitting the value part will set the given configuration directive to "1"
$ php -d max_execution_time -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(1) "1"

# Passing an empty value part will set the configuration directive to ""
php -d max_execution_time= -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(0) ""

# The configuration directive will be set to anything passed after the '=' character
$  php -d max_execution_time=20 -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(2) "20"
$  php -d max_execution_time=doesntmakesense -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(15) "doesntmakesense"

        

$ php -m
[PHP Modules]
xml
tokenizer
standard
session
posix
pcre
overload
mysql
mbstring
ctype

[Zend Modules]

        

Το εκτελέσιμο της PHP μπορεί να χρησιμοποιηθεί για να τρέξουν script της PHP απόλυτα ανεξάρητα από τον web server. Αν είστε σε ένα Unix σύστημα, θα πρέπει να προσθέσετε μια ειδική πρώτη γραμμή στο PHP script σας, και να το κάνετε εκτελέσιμο, ώστε το σύστημα να ξέρει, ποιό πρόγραμμα θα πρέπει να τρέξει το script. Σε ένα Windows σύστημα μπορείτε να συσχετίσετε το php.exe με την double click επιλογή των .php αρχείων, ή να κάνετε ένα batch αρχείο να τρέχει το script μέσω της PHP. Η πρώτη γραμμή που προστίθεται στο script για να δουλεύει στο Unix δεν θα βλάψει στα Windows, έτσι μπορείτε να γράψετε cross platform προγράμματα με αυτό τον τρόπο. Ένα απλό παράδειγμα γραφής ενός προγράμματος PHP της γραμμής εντολών μπορεί να βρεθεί παρακάτω.

Στο παραπάνω script, χρησιμοποιήσαμε την ειδική πρώτη γραμμή για να δείξουμε πως αυτό το αρχείο θα πρέπει να εκτελεστεί από την PHP. Δουλεύουμε με μια CLI έκδοση εδώ, έτσι δεν θα υπάρχουν εκτυπώσεις από HTTP headers. Υπάρχουν δύο μεταβλητές που μπορείτε να χρησιμοποιήσετε όταν γράφετε εφαρμογές γραμμής εντολών με την PHP: Οι $argc και $argv. Η πρώτη αποτελεί τον αριθμό των argument συν ένα (το όνομα του script που εκτελείται). Η δεύτερη είναι ένα array το οποίο περιέχει τα arguments, αρχίζοντας με το όνομα του script σαν τον αριθμό μηδέν ($argv[0]).

Στο παραπάνω πρόγραμμα ελέγξαμε αν υπάρχουν λιγότερα ή περισσότερα από ένα arguments. Επίσης αν το argument ήταν --help, -help, -h ή -?, εκτυπώσαμε ένα μήνυμα βοήθειας, εκτυπώνοντας το όνομα του script δυναμικά. Αν λαμβάναμε κάποια άλλα argument τα εκτυπώναμε και αυτά.

Αν θέλατε να εκτελέσετε το παραπάνω script στο Unix, χρειάζεται να το κάνετε εκτελέσιμο και απλά να το καλέσετε με το script.php echothis ή script.php -h. Στα Windows, μπορείτε να δημιουργήσετε ένα batch αρχείο για αυτό το σκοπό:

@c:\php\cli\php.exe script.php %1 %2 %3 %4
  

Υποθέτοντας πως ονομάσατε το παραπάνω πρόγραμμα script.php, και έχετε το CLI php.exe σας στο c:\php\cli\php.exe αυτό το batch αρχείο θα εκτελεστεί για σας με τις επιπλέον επιλογές: script.bat echothis ή script.bat -h.

Δείτε επίσης το documentation (τεκμηρίωση) της Readline επέκτασης για περισσότερες συναρτήσεις που μπορείτε να χρησιμοποιήσετε για να βελτιώσετε τις εφαρμογές γραμμής εντολών σας στην PHP.