Composr Tutorial: Commandr

Written by Philip Withnall

Commandr, the Composr Command-Line Environment, is designed for experienced system administrators who find command-lines faster to use than GUI-based alternatives.

Table of contents

Composr Tutorial: Commandr

Introduction

We designed Commandr to supplement the features of the Admin Zone, rather than to replace them. The interface allows you to enter commands in the form of:

PHP code
SQL database queries
Shell commands
Commandr-code scripts
Commandr-code commands, which you can use to fully interact with the Composr Repository

Commandr is accessed from:
Admin Zone > Tools > Commandr
Or, as an overlay using the button in the footer if you have left that enabled (this is very handy).

Commands

Although the system is very flexible, there are many commands to use, designed for interaction with the Composr Repository and other systems designed specifically for Commandr. Since UNIX is the grandparent of almost all of the operating systems where command-line use is most prevalent – and administrators comfortable with command-lines will probably be UNIX experts – many of the commands mirror their UNIX counterparts.

The basic format for a command is as follows:

Code

command_name -o -long_option -o2=value -long_option2="value 2" parameter1 "parameter 2" parameter3

This example consists of:

A command name (no spaces)
followed by a list of options (either in short or long format; this is decided by the command in question) with optional values (quoted if they contain spaces)
then a list of parameter values (quoted if they contain spaces).

Commandr supports backslashing, so you can escape any quotes in values you're passing:

Code

echo "Grandma said: \"Hello world!\""

For a full list of Commandr commands, simply execute the commands command in Commandr:

Code

commands

You can find help information about any command by simply using the command's -h help flag, or typing help <command>.

PHP code

PHP can be entered and executed by Commandr, simply by prefixing the code to be executed with a colon (":"). The returned data will be displayed as best as possible (its type will be determined and outputted as appropriate). Multiple PHP commands may be executed (separated by semi-colons, as per normal PHP code).
For example:

Code

:echo "Hello"; echo " World.";

Storage

Storage limit

There is a memory limit of 4Kb for variable storage, to avoid causing slow downs in requests and hitting maximum cookie size limits.

Commandr will attempt to store:

variables
included code
included language files

…between command requests.

This makes it possible to execute command sequences without having to put them all on one line.

It is implemented using cookies.

SQL queries

SQL queries can also be executed by Commandr, simply by prefixing the query to be executed with an 'at' symbol (@). As with PHP commands, the query results will be outputted in an appropriate manner.

Separating multiple queries using semicolons is not supported.

Even though Commandr commands are single-line, pasting multi-line commands in usually works. The only exception would be if the line breaks are a part of strings within the query, in which case they would end up replaced by spaces.

You are allowed to do non-read queries, such as INSERTs and DELETEs, but you'll be told "Error: Your search yielded no results.". Ignore that, it's just a generic messages to tell you explicitly that no results were shown.

Shell commands

Shell commands can be executed by Commandr by prefixing the query to be executed with a 'hash' (or "pound") symbol (#).
The actual behaviour of these commands depends on your operating system.

The filesystem

One of the main features of Commandr is the fact that various facets of Composr can be manipulated through a virtual filesystem, known as the Composr Repository (aka Commandr-fs). There are many different kinds of directory tied into the filesystem, representing different parts of the Composr system.

It is quite simple to write more as hooks if you know how to program.

To use the repository, simply navigate around using the standard UNIX filesystem commands (cd, pwd, ls, etc.), and modify files in a similar fashion to change the appropriate behind-the-scenes value.

To learn more about the filesystem, which is also used by other parts of Composr, see the The Composr Enterprise Repository tutorial.

Running from a normal operating system command prompt

Commandr can be loaded up directly from your operating system shell. For example, on Linux you can start it up with this command:

Code (`Bash`)

php data/commandr.php

Commandr is primarily designed for use from an HTML interface (i.e. within Composr), so things like the text file editor will not work. Most things do work though.

Example commands

In this section we will show you some of the quick tasks which can be performed efficiently using Commandr.

Quick function search

It can get quite hectic trying to find a particular function in a big application like Composr, where there are thousands of functions in use, especially if you don't have the code available on your own computer.

Fortunately you can an simply use the find_codes command to help you. For example:

Code

find_codes "function require_code("

This example will show you what file this bit of code is in, i.e. where the require_code function is defined.
In this case it will show sources/global.php.

Open page links on the go

You might often want to quickly test a newly modified page link or just any random page but that'd mean you have to open a new tab window and then manually enter the whole URL.

Commandr comes with a powerful command call which can open up a screen for you on the go, with just a page-link as the only parameter.

For example:

Code

call cms:cms_downloads:add

This example opens up the "Add download" form.

Looking up members

The whois command can be used to quickly find out a member's details such as their member ID, Username and IP address.
This command takes either a username, a member ID, an IP address, or an e-mail address, as the identifying information.

For example:

Code

eg: whois 2

This example looks up member ID #2.

Banning members

You can use the ban_member command to ban a specific member using their username or ID.

For example:

Code

ban_member Sam_Witwicky

For example:

Code

ban_member 4

Giving points

The give command is useful to give points to a member. The command takes 4 parameters: Recipient Member ID/Username, Number of points, The reason for the points, and optionally the Sending Member ID/Username. You can also send points anonymously using the -a flag.

For example:

Code

give -a 7334 "Nice User" "I love you"

This example anonymously gives 7334 points anonymously to a user named "Nice User", with the message "I love you".

Changing passwords

The passwd command works pretty much like the native Linux command of the same name. It will help you change the password of a member using their username or Member ID.

For example:

Code

passwd -u johnDoe newpassword

Directory and table sizes

The directory_sizes command can come handy to quickly find out the size of any directory within the Composr system.
It will output a nice formatted list of all the directories for you.

The db_table_sizes command will output a tabular list of all the database tables within Composr with their respective size.

These commands are very useful when trying to cut down on disk usage (for example, maybe you are up against a quota limit, or are finding backup files too large).

Clearing caches

Caching is important to maintain performance within Composr; however while testing new changes you might want to clear cached values.
You can use clear_cache command to clear all the caches immediately – or even better, only delete specific caches by passing a comma-separated list of the caches to clear.

For example:

Code

clear_caches comcode_pages,templates

Note: If parameters are not given for clear_caches then whole cache will be cleared.

Opening and closing the site

We can use Commandr and Commandr-fs to manipulate config options like files. All the files in /etc directly correspond to config options.

With:

Code

edit /etc/closed

… we can edit the closed-site message (edit in the text box that appears to your custom message and click Proceed).

With:

Code

edit /etc/site_closed

… we can close the site (edit in the text box that appears to 1 and click Proceed).

An alternative to the above is:

Code

echo 1 > /etc/site_closed

… which saves the edit directly.

Accessing system info using Commandr/PHP as a tunnel

You can run almost any PHP code or function from Commandr. This can be useful for quickly testing small code snippets or functions.

This shows info about the server's CPU (Linux servers only, although a Mac-equivalent is shown in a screenshot also):

Code

:echo file_get_contents('/proc/cpuinfo');

This shows the server CPU load (Linux and Mac servers only):

Code

:echo shell_exec('uptime');

Please note that the leading : is needed for Commandr to identify that the input's going to be something for PHP.

Scripts (advanced)

Commands can be put together in scripts and saved for later use in the bin filesystem. These can be executed on the Commandr command-line just by entering the name of the script, or can alternatively be scheduled for execution by the calendar to run at some point in the future (possibly routinely).

Bulk actions using Composr

Commandr is a very effective way to automate tedious maintenance tasks. For example, if you want to delete a set of images and you have their IDs, you could execute this Commandr code:

Code

:require_code('galleries2');
$ids=array(1,2,3,4,5);
foreach ($ids as $id) delete_image($id,true);

(paste it all in one go, not as separate line inputs)

The code simply interfaces with the standard Composr APIs.

Feedback

Please rate this tutorial:

Have a suggestion? Report an issue on the tracker.

Composr Tutorial: Commandr

Introduction

Commands

Code

Code

Code

PHP code

Code

Storage

Storage limit

SQL queries

Shell commands

The filesystem

Running from a normal operating system command prompt

Code (Bash)

Example commands

Quick function search

Code

Open page links on the go

Code

Looking up members

Code

Banning members

Code

Code

Giving points

Code

Changing passwords

Code

Directory and table sizes

Clearing caches

Code

Opening and closing the site

Code

Code

Code

Accessing system info using Commandr/PHP as a tunnel

Code

Code

Scripts (advanced)

Bulk actions using Composr

Code

See also

Feedback

Statistics

Code (`Bash`)