Cron

From PhpCOIN Documentation

Jump to: navigation, search

Contents

Automation Capabilities

Cron is a *nix timer/scheduling daemon that runs in the background on most web-servers. Scripts or other programs can be registered with the Cron daemon to run "every so often". The equivalent for Windows is "Scheduled Tasks".

phpCOIN has several functions that must be called at regular intervals to handle automatic processing of invoices, late payment "nag" emails, and automatically creating new recurring invoices. The invoice functions are all contained within /coin_cron/invoices.php, which must be run once each day, every day ~ no exceptions, or you may end up not having some invoices auto-created, status updated, or nag emails sent.

If you track your expenses in phpCOIN, there are several functions that must be called at regular intervals to handle automatic processing of bills and automatically creating new recurring bills. The bill functions are all contained within /coin_cron/bills.php, which must be run once each day, every day ~ no exceptions, or you may end up not having some bills auto-created.

There is also an optional function (helpdesk.php) that will connect to an email box, check to see if messages are from existing clients, and if so either add a reply to a helpdesk ticket or create a new helpdesk ticket. This is useful if you have clients who hit "reply" to a helpdesk ticket rather than logging in to phpCOIN to respond, or who do not use the helpdesk and instead insist on emailing help requests. The helpdesk-import functions are contained within /coin_cron/helpdesk.php, which can be run as often as you want phpCOIN to check your email, or not run at all ~ your choice.

There is another optional function (paypal.php) that will connect to an email box, check to see if messages are from PayPal, and if so try to create a payment and apply it to an invoice. This is an alternative to the PayPal IPN system.


Configuring phpCOIN Cron Jobs

The /coin_cron files built-in to phpCOIN can be called two different ways:

1: The first is via curl or wget to simulate being called by a web-browser. If you call the file(s) this way, there are no configuration settings within phpCOIN for you to change. The actual command to execute would be curl/wget, with the URL to the cronfile as a parameter, ie:

 curl http://my.phpcoin.com/phpCOIN/coin_cron/helpdesk.php

2: The other method is to process the file(s) straight from the command line by php. In this event, you must tell phpCOIN where it is located, because the automatic 'where am I' code depends on being called from a web-browser. Edit the following line of the /coin_cron/cron_config.php file:

$_COINURL = 'http://my.phpcoin.com';

Change the http://my.phpcoin.com part of the line to the actual URL of your phpCOIN installation. You must keep the single quotes in place. If you placed the phpCOIN files in a directory called billing, you would have $_COINURL = 'http://my.phpcoin.com/billing'; If your phpCOIN installation runs under SSL, you would have $_COINURL = 'https://my.phpcoin.com'; Several examples are included in the comments of the file. The actual command to execute would be the path to the cronfile, ie:

 /home/html/path_to_phpcoin/coin_cron/helpdesk.php


Scheduling the phpCOIN Cron Jobs

Depending on your server setup you may need to edit crontab files manually, or you may have access to a control panel with scheduling capabilities.

Direct crontab editing

Add the following lines to your crontab

0,10,20,30,40,50 * * * * curl -s http://my.phpcoin.com/phpCOIN/coin_cron/helpdesk.php
30 4 * * * curl -s http://my.phpcoin.com/phpCOIN/coin_cron/invoices.php
30 5 * * * curl -s http://my.phpcoin.com/phpCOIN/coin_cron/bills.php

This will run the helpdesk-import script every 10 minutes, the invoices script once a day at 4:30 am, and the bills script once a day at 5:30 am. Feel free to use your own time intervals if you want them to run at different times ~ this is just an example. curl is just a plain text web browser. If curl doesn't work you can try lynx (though the -s may not be appropriate for lynx) or wget.

Control Panel Settings

For those of you using a reseller account on a web-host provider, you may have a cPanel or Plesk entry named "Cron Jobs" or something similar. Clicking it usually gives two options ~ Standard, and Advanced (Unix Style)

Choose "Standard" and you will see a screen (might be called "Entry 1", or a higher number if you already have a cron job set-up) that has "command to run" and then a number of boxes with time and date (day & month) options. You might also have an option to send the results of the crontab to an e-mail address. If so, please do enter your e-mail address.

Enter the appropriate phpCOIN filename in the command to run box, making sure that the path to the file is correct. We recommend that you run the invoice.php and bills.php daily and any other desired files hourly. To do this choose the best minutes (0 is on the hour - you will have the choice of 0 to 59) and in the hours box select every hour. Check the other boxes but they are most likely already set to every day, weekday, and month. Click the [save crontab] button. Follow the same procedure for invoices.php. Select a time in minutes (not one of the every options) and likewise in hours. To choose 3:15 am, select "15" in minutes and "3" (3am) in hours. Make sure "every day" is selected in days, and the "every" option is selected in the remaining two. Again, save this new entry by clicking the [save crontab] button.

Output from cronjob

When run, the /coin_cron/helpdesk.php file can provide the aggregate results of all messages processed, or it can provide step-by-step details of each message processed. Aggregate results is recommended for normal operation, while detailed results is recommended for trouble-shooting.

In phpCOIN v1.2.6 and higher, goto [Admin] -> [Parameters] -> [cronjobs] -> [helpdesk] -> [Auto-import: Verbose] and set it to YES for detailed results or NO for aggregate results.

In phpCOIN v1.2.5 or lower, edit the value of the variable $Silent in /coin_cron/helpdesk.php

$Silent=0;

Will give detailed results, while

$Silent=1;

will give aggregate results


Setting up a phpCOIN LAMP cron job

A linux users guide to getting phpCOIN cron jobs working without actually tearing all your hair out!

Before we dive into the details of all the ways a phpCOIN cron job can be run, and explore the pros and cons of each, let's establish a few ground rules.

You must know where your files reside on your server – it's no use asking us – we don't know!!! We know where our files are on our servers :)

I am not going to make any attempt to explain how to write a cron job from the command line, nor deal with the actual scheduling. You can read all about that using some simple Google searches or by consulting your control panel manual.

This guide assumes you have some sort of control panel and are competent enough to have clicked the right icons to land on the cron setup page and are wondering what to do next. (If you can't get this far, you need to go hire someone that can)

There are several ways that one can invoke a php file under cron and I shall examine them one by one and attempt to highlight any issues you may find.


WGET

For many years, the wget method of calling a php file was an easy means to an end.

It may work for you but you do need to be aware of some potential pitfalls. Wget is a utility for non-interactive download of files from the Web. It supports HTTP, HTTPS, and FTP protocols. It would appear that, if run by a user that is not a member of the httpd group or the file ownership group, it tries to download the file to a folder within the home directory of the user that called it instead of caching the output into a tmp file and attempting to send the result by mail to the cron users mail account or discarding the output to /dev/null if specified.

Since it calls a php file, and assuming the php executes, the html output is what is downloaded and stored in the cron users home folder (probably “root” which you may not have access to) under the same filename as was called (if the php fails to execute, the resulting file will just contain the same code as the php file that was called). Subsequent calls will create additional files with the same name with an appended iteration number as described below.

Since wget was designed as a background, non-interactive downloader of html files, it would seem to be doing exactly as it was designed to do. The fact that we have been able to exploit it in the past within many server environments, to call and parse a php file and get the result we were looking for, was a bonus which is perhaps becoming obsolete as server security is progressively tightened up. Our implementation of wget is a bit like using a screwdriver as a chisel, it often works but it was never really designed to be used that way.

Running the 'wget' cron job as root in a shared vhost environment,

/usr/bin/wget http://my.phpcoin.com/coin_cron/helpdesk.php > /dev/null 2>&1

I observed that cron was ignoring the null output and writing a file into the root folder every run. The files were named:

helpdesk.php
helpdesk.php.1
helpdesk.php.2
helpdesk.php.3
.......etc

Each file contained the html output of the parsed php file

Obviously, this could create a huge number of files in a home/root folder after a short time if you are running the helpdesk import every few minutes!!!

Adding the --delete-after switch to the call seems to be effective in taming this behavior eg

/usr/bin/wget --delete-after http://my.phpcoin.com/coin_cron/helpdesk.php > /dev/null 2>&1

An alternative may be to pipe the output file into a /tmp folder and let the linux garbage collection process periodically clean them up.


CURL

curl is a tool to transfer data from or to a server, using one of the supported protocols (HTTP, HTTPS, FTP, FTPS, TFTP, DICT, TELNET, LDAP or FILE). The command is designed to work without user interaction.

I should imagine the same criteria applies as above although you will have to consult your curl manual for the correct syntax to delete any downloaded file after use.


LYNX

Lynx is a text-only browser that is occasionally deployed on server environments – if you have it, you may be able to use it directly to call your php files.


PHP

OK – this is the interesting bit and requires the most explanations! Firstly, let's examine the Crontab Environment

cron invokes the command from the user's HOME directory with the shell, (/usr/bin/sh)

cron supplies a default environment for every shell, defining:

HOME=user's-home-directory
LOGNAME=user's-login-id
PATH=/usr/bin:/usr/sbin:.
SHELL=/usr/bin/sh

Now we must take into account that, for various reasons connected to cron hierarchy permissions in SELinux, most control panel developers seem to have opted to run all cron jobs under the 'root' user and avoid any complications in their lives. Unfortunately, this has complicated our lives instead. Users who desire to have their .profile executed must explicitly do so in the crontab entry or in a script called by the entry, so you do have an option of writing your own perl/python/shell script if you want to run under a different user.

For many years it was simple to run a php cron under lamp, all we had to do was issue a command something like:

/usr/bin/php -q /var/www/vhosts/phpcoin.com/httpdocs/files/coin_cron/helpdesk.php

and everything worked!

More recently, running a phpCOIN cron job on a reasonably up-to-date lamp server as the root user often results in the error message similar to:

PHP Warning: require_once(/root/coin_includes/core.php):
 failed to open stream: No such file or directory in
 /var/www/vhosts/phpcoin.com/httpdocs/files/coin_cron/helpdesk.php on line 24

We can see the cron job assumes the file-set is relative to the users (root) home directory instead of where the file-set actually resides.

There are several ways we can address this issue:

1) A user can hard code the absolute path to their include file from within the files
   called by cron.  But many users did not know their own path, which is why phpCOIN
   developed our exclusive "where am I" code

2) A user can set the include path in htaccess or from within their php files with the
   ini_set() function.  But again many users did not know their own path, which is why
   phpCOIN developed our exclusive "where am I" code

3) (My preferred solution)
   A user can issue a cron command as follows (without editing any of their php files):
     cd /var/www/vhosts/phpcoin.com/httpdocs/files && /usr/bin/php -q
     /var/www/vhosts/phpcoin.com/httpdocs/files/coin_cron/helpdesk.php
     > /dev/null 2>&1

You can see in option three we first CD (Change Directory) to the web-root folder of the vhost containing the phpCOIN file-set – in this case /httpdocs/files which in this example translates to an absolute path of /var/www/vhosts/phpcoin.com/httpdocs/files and, now we are in the correct starting folder, we then run the second part of the cron job (the && means “and”) by running our PHP call.


Well, that's all I am going to write on the subject of linux cron jobs – it's not really a phpCOIN configuration issue, and if you have got this far and still have no idea what I am talking about, perhaps you need to hire a competent systems administrator that does – and maybe ponder on how you are going to support your own hosting clients if they ever ask you to set up a cron job for them  :(

Personal tools

Inscrita el Registro Mercantil de Mallorca Tomo 2140, Hoja No. PM-51034, Folio 135
This website owned and operated by: Technology Services RPVW S.L. CIF# B57345084
Avda Constitucion 48 Bajos Alaro 07340 Baleares SPAIN
Tel:+34 971518362    Fax: +34 971518368    eMail: support@phpcoin.com