tonyair/silverstripe-framework
1
0
Fork 0
mirror of https://github.com/silverstripe/silverstripe-framework synced 2024-10-01 13:48:37 +02:00
Code Issues Projects Releases Wiki Activity

Review, clean up of CLI documentation

Browse Source
This commit is contained in:
Will Rossiter 2014-09-27 17:53:21 +12:00 committed by Cam Findlay
parent 80d4127f43
commit 65309fa5d4
1 changed files with 67 additions and 72 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

127
docs/en/02_Developer_Guides/17_CLI/index.md
View File

@ -1,36 +1,33 @@
summary: Automate SilverStripe, run cronjobs or sync with other platforms through the sake Command Line Interface. summary: Automate SilverStripe, run Cron Jobs or sync with other platforms through the Command Line Interface.
# Command line usage # Command Line
## Introduction SilverStripe can call [controllers](../controllers) through a command line interface (CLI) just as easily as through a
web browser. This can be used to automate tasks with cron jobs, run unit tests, or anything else that needs to interface
SilverStripe can call controllers through commandline `php` just as easily as through a web browser. over the command line.
This can be handy to automate tasks with cron jobs, run unit tests and maintenance tasks,
and a whole bunch of other scripted goodness.
The main entry point for any command line execution is `cli-script.php`. For example, to run a database rebuild The main entry point for any command line execution is `cli-script.php`. For example, to run a database rebuild
from the command line, use this command: from the command line, use this command:
:::bash
cd your-webroot/ cd your-webroot/
php framework/cli-script.php dev/build php framework/cli-script.php dev/build
Make sure that your commandline php version uses the same configuration as your webserver (run `php -i` to find out more). <div class="notice">
Your command line php version is likely to use a different configuration as your webserver (run `php -i` to find out
more). This can be a good thing, your CLI can be configured to use higher memory limits than you would want your website
to have.
</div>
## GET parameters as arguments ## Sake: SilverStripe Make
You can add parameters to the command by using normal form encoding. Sake is a simple wrapper around `cli-script.php`. It also tries to detect which `php` executable to use if more than one
All parameters will be available in `$_GET` within SilverStripe. are available.
cd your-webroot/ <div class="info" markdown='1'>
php framework/cli-script.php myurl myparam=1 myotherparam=2 If you are using a debian server: Check you have the php-cli package installed for sake to work. If you get an error
when running the command php -v, then you may not have php-cli installed so sake won't work.
## SAKE: SilverStripe make </div>
Sake is a simple wrapper around `cli-script.php`. It also tries to detect which `php` executable to use
if more than one are available.
**If you are using a debian server:** Check you have the php-cli package installed for sake to work.
If you get an error when running the command php -v, then you may not have php-cli installed so sake won't work.
### Installation ### Installation
@ -39,66 +36,65 @@ You can copy the `sake` file into `/usr/bin/sake` for easier access (this is opt
cd your-webroot/ cd your-webroot/
sudo ./framework/sake installsake sudo ./framework/sake installsake
Note: This currently only works on unix-like systems, not on Windows. <div class="warning">
This currently only works on UNIX-like systems, not on Windows.
</div>
## Configuration ### Configuration
Sometimes SilverStripe needs to know the URL of your site, for example, when sending an email. When you're visiting Sometimes SilverStripe needs to know the URL of your site, for example, when sending an email or generating static
your site in a web browser this is easy to work out, but if you're executing scripts on the command-line, it has no way files. When you're visiting your site in a web browser this is easy to work out, but if you're executing scripts on the
of knowing. command line, it has no way of knowing.
To work this out, you should add lines of this form to your [_ss_environment.php](/topics/environment-management) file. To work this out, you should add lines of this form to your [_ss_environment.php](/getting_started/environment_management)
file.
:::php :::php
global $_FILE_TO_URL_MAPPING; global $_FILE_TO_URL_MAPPING;
$_FILE_TO_URL_MAPPING['/Users/sminnee/Sites'] = 'http://localhost'; $_FILE_TO_URL_MAPPING['/Users/sminnee/Sites'] = 'http://localhost';
The above statement tells SilverStripe that anything executed under the `/Users/sminnee/Sites` directly will have the
What the line says is that any Folder under /Users/sminnee/Sites/ can be accessed in a web browser from base URL `http://localhost`.
http://localhost. For example, /Users/sminnee/Sites/mysite will be available at http://localhost/mysite.
You can add multiple file to url mapping definitions. The most specific mapping will be used. For example: You can add multiple file to url mapping definitions. The most specific mapping will be used. For example:
:::php :::php
global $_FILE_TO_URL_MAPPING; global $_FILE_TO_URL_MAPPING;
$_FILE_TO_URL_MAPPING['/Users/sminnee/Sites'] = 'http://localhost'; $_FILE_TO_URL_MAPPING['/Users/sminnee/Sites'] = 'http://localhost';
$_FILE_TO_URL_MAPPING['/Users/sminnee/Sites/mysite'] = 'http://mysite.localhost'; $_FILE_TO_URL_MAPPING['/Users/sminnee/Sites/mysite'] = 'http://mysite.localhost';
### Usage
Using this example, /Users/sminnee/Sites/mysite/ would be accessed at http://mysite.localhost/, and Sake is particularly useful for running build tasks
/Users/sminnee/Sites/othersite/ would be accessed at http://localhost/othersite/
## Usage
Sake will either run `./framework/cli-script.php` or `./cli-script.php`, depending on what's available.
It's particularly useful for running build tasks...
:::bash
cd /your/site/folder cd /your/site/folder
sake dev/build "flush=1" sake dev/build "flush=1"
sake dev/tests/all sake dev/tests/all
It can also be handy if you have a long running script. It can also be handy if you have a long running script.
:::bash
cd /your/site/folder cd /your/site/folder
sake dev/tasks/MyReallyLongTask sake dev/tasks/MyReallyLongTask
### Running processes ### Running processes
You can use sake to make daemon processes for your application. You can use sake to make daemon processes for your application.
Step 1: Make a task or controller class that runs a loop. Because SilverStripe has memory leaks, you should make the PHP Step 1: Make a task or controller class that runs a loop. To avoid memory leaks, you should make the PHP process exit
process exit when it hits some reasonable memory limit. Sake will automatically restart your process whenever it exits. when it hits some reasonable memory limit. Sake will automatically restart your process whenever it exits.
The other thing you should do is include some appropriate sleep()s so that your process doesn't hog the system. The Step 2: Include some appropriate sleep()s so that your process doesn't hog the system. The best thing to do is to have
best thing to do is to have a short sleep when the process is in the middle of doing things, and a long sleep when a short sleep when the process is in the middle of doing things, and a long sleep when doesn't have anything to do.
doesn't have anything to do.
This code provides a good template: This code provides a good template:
:::php :::php
<?php
class MyProcess extends Controller { class MyProcess extends Controller {
private static $allowed_actions = array( private static $allowed_actions = array(
@ -119,37 +115,36 @@ This code provides a good template:
} }
} }
Step 2: Install the "daemon" command-line tool on your server. Step 3: Install the "daemon" command-line tool on your server.
Step 3: Use sake to start and stop your process Step 4: Use sake to start and stop your process
:::bash
sake -start MyProcess sake -start MyProcess
sake -stop MyProcess sake -stop MyProcess
<div class="notice">
Sake stores Pid and log files in the site root directory.
</div>
Note that sake processes are currently a little brittle, in that the pid and log ## GET parameters as arguments
files are placed in the site root directory, rather than somewhere sensible like
/var/log or /var/run.
### Running Regular Tasks With Cron You can add parameters to the command by using normal form encoding. All parameters will be available in `$_GET` within
SilverStripe. Using the `cli-script.php` directly:
On a unix machine, you can typically run a scheduled task with a [cron job](http://en.wikipedia.org/wiki/Cron), :::bash
using one of the following command-line calls: cd your-webroot/
php framework/cli-script.php myurl myparam=1 myotherparam=2
``` Or if you're using `sake`
/path/to/site_root/framework/sake dev/tasks/MyTask
php /path/to/site_root/framework/cli-script.php dev/tasks/MyTask
```
If you find that your cron job appears to be retrieving the login screen, then you may need to use `php-cli` :::bash
instead. This is typical of a cPanel-based setup. sake myurl "myparam=1&myotherparam=2"
``` ## Running Regular Tasks With Cron
php-cli /path/to/site_root/framework/cli-script.php dev/tasks/MyTask
```
A good approach to setting up and testing your task to run with cron is: On a UNIX machine, you can typically run a scheduled task with a [cron job](http://en.wikipedia.org/wiki/Cron). You can
execute any `BuildTask` in SilverStripe as a cron job using `Sake`.
1. Try running the task via the command-line on your server. `/path/to/site_root/framework/sake dev/tasks/MyTask` :::bash
2. Set up a cron job to run the task every minute. `* * * * * /path/to/site_root/framework/sake dev/tasks/MyTask` * * * * * /your/site/folder/sake dev/tasks/MyTask
3. Finally, set the task to run when you want it to. `0 2 * * * /path/to/site_root/framework/sake dev/tasks/MyTask` (2am)