Usage

Basic Usage

Depending on the settings for the channel, you can use three different triggers to run your PHP code:

For the first two options, the whitespace after the trigger is mandatory.
While <?= does not require the whitespace, you should be aware that this -just like the according opening tag in PHP- outputs the code following it, so be careful what you put there: Starting the code with if, while or similar keywords will result in a parse error. You can consider "<?=" to be equivalent to "!php echo ".

If you just want to test code that is of no importance to any channel, you can do so either by querying scriptkitty directly (don't forget the trigger) or by joining the test channel on QuakeNet.

Storing Data

One trigger in scriptkitty is considered one script: Variables in one invocation are volatile and will not be available in the next invocation. To keep track of data between invocations, you have the following options:

Sessions

scriptkitty manages sessions, so you can just put your data into the $_SESSION array, just like you would do in a normal script.
Each user has his own session, so noone else can modify your session data. Then again, you cannot pass your session to anyone else, either, so this method has its disadvantages, too.

Superglobals

Although they are empty in the beginning, you can set $_GET, $_POST and $_SERVER with values of your liking. They will automatically be stored with your session and recreated on the next invocation.
The same limitations as to the session apply.

Cookies

You can set your cookie data with setcookie() and read it from $_COOKIE on the next invocation; just like you are used to it from normal scripts. (This might also come in handy to show to people that their cookies will not show up instantly but on the next request.)
scriptkitty does understand secure cookies, however, lacking an HTTP(S) connection, in scriptkitty these refer to query cookies and are only registered to your $_COOKIE variable if you are using a query (they can, however, be set on a channel).
The same limitations as to the session apply.

Globals

Additionally to the mentioned options, you can also have any ordinary variable in global scope being rescued over multiple invocations. For this, scriptkitty offers two functions:
scriptkitty\register_global('varname') will register $varname from the global scope to be stored. You can then for example just $calls++ at the beginning of each of your invocations to keep track of how many times you used the bot.
scriptkitty\unregister_global('varname') will make it an ordinary variable again, which will be lost once the script ran through.

Additionally, there are two ways to store data in a way that allows you to share it with others:

Files

You can use most of the file system functions to read, write and work on files. See file system access for details.

MySQL

scriptkitty has both the MySQL and MySQLi extensions enabled. See MySQL for details.

While data stored in these ways will not vanish with your session (except of the $_UPLOAD variable), it doesn't last forever, either: When not being used it will be deleted after at most three days (depending on the amount of storage used).
Also, in both cases others will be able to read and modify your data, though.

File System Access

As opposed to most PHP parser bots out there (except of some badly written ones), scriptkitty gives you access to the file system through the file system functions (local access only - sorry guys :)).

The following limits apply: The space and inode limits include the size of the MySQL databases data segment.

The file system is regularly tidied up. The more cluttered the file system is, the more rigid the tidying process will be. However, unused files and tables will at most last for three days.

You do not necessarily have to import data line by line through fwrite statements on IRC; the option to upload files exists as well.
Also, all files can be viewed online.

Uploading Files

To make file system access usable, data can be uploaded to the bot to be used in IRC.
Please notice that scriptkitty is not a pastebin; if you just want to upload something to pass it around, please use one of them instead of the bot!

That said, the process is pretty straightforward: On any channel on which you can execute PHP code in scriptkitty, you can issue the !php upload command.
scriptkitty will notice you a URI to a page where you can paste text or choose a file to upload.
Regardless whether you choose to paste text or upload a file, the size limit is 2 MB.

Once you uploaded the file, you get to a confirmation page that links you to the file.
At the same time, the variable $_UPLOAD in your session is set to the internal name of the file you just uploaded, so you can use it right away by opening, reading or including $_UPLOAD.

Web Output

Because IRC is somewhat limited in regards of the output length, this feature allows you to redirect your output into a file which you can then view on the web.
All you need to do is to call ob_web() before your output. Your output is then put into a file and you are given a link to it.
As with all output buffering functions, you can stop the behaviour using ob_end().

Example

!php ob_web(); echo "Hello, world!";

Web Output Functions

bool scriptkitty\ob_web\active()

If web output is currently activated, this function will return true, otherwise the return value is false.

string scriptkitty\ob_web\file()

This function returns the local name of the file to which the output is sent. You do not have to start web output for the file name to be set.

string scriptkitty\ob_web\url()

This function returns the URI at which the output file can be viewed.
Notice: If you neither started web output, nor created the file named by ob_web_filename(), this will only result in a 404.

MySQL Access

You can use both the MySQL or the MySQLi extension to access the MySQL 6 database. For MySQL, the default connection is opened automatically and you can just start using it. For MySQLi, the connection data is configured as well, so a simple $db = new MySQLi(); will do.

Should you need it for whatever reason, the MySQL host is 127.0.0.1:3306, user name, password and database all are "scriptkitty".

The mysql_query() function is tweaked so that, should an error occur, an E_WARNING is automatically issued to report this error. This means: No need for explicitly checking mysql_error(). (It won't hurt to do so, though.)
There is also a "smart" querying function: mysql_dump($query[, $connection]) will send the query and report the result status and (for SELECT querys) the data as well. Small data will be reported back to IRC, huge data blocks are put on web instead. Of course you can manually start web buffering before using mysql_dump and it will always give you the nice output.

Overrides

scriptkitty allows you to permanently override locale and time zone settings:

Locales

If you want to override one or all locales (list), instead of calling setlocale(...), you call scriptkitty\setlocale(...) with exactly the same set of parameters. The override is effective immediately. The return value corresponds to the value returned by setlocale(): If the return value is false, no override is set.
To remove the override, call scriptkitty\restorelocale($cat), where $cat is the LC_* constant of the locale override you want removed. scriptkitty\unsetlocale(LC_ALL) removes all locale overrides in place.

Time Zone

Overriding the time zone (list) works in a similar way:
Instead of calling date_default_timezone_set(...), you call scriptkitty\settimezone(...). As with the locale overrides: Same parameters, same return value as the original function. Return value of false means the override wasn't changed.
Similarly to undo the time zone override, call scriptkitty\unsettimezone() (no parameters).

Removal of overrides takes effect on your next request to scriptkitty.