Console Commands and Jobs

Edit

Improvements?

Let us know by posting here.

Command Line Interface

Concrete CMS uses commands that you can run in a terminal (like SSH sessions, bash and sh shells, Windows command prompts).

  Note: On Windows, change / to \.

To use these commands, open a terminal and go to the Concrete webroot folder (where index.php is). It's helpful but not required.

To see all commands, type:

concrete/bin/concrete5 list
  Note: On *nix or MacOS X, if you get a "Permission denied" error, run chmod a+x concrete/bin/concrete5.

This shows a list of commands. Each command starts with a prefix (or namespace).

We focus on c5 commands primarily here (type concrete/bin/concrete5 list c5 to see them). Other namespaces are:

To learn a command's details, add --help after it, like:

concrete/bin/concrete5 c5:job --help

This displays:

Usage:
  c5:job [options] [--] [<jobs>]...

Arguments:
  jobs        Jobs to run (separate multiple jobs with a space)

Options:
      --set   Find jobs by set instead of job handle
      --list  List available jobs
...

To run a command with different settings, use --env envname, like:

concrete/bin/concrete5 c5:update --env envname

For setting up different environments, see environment specific configurations.

Available c5 Commands

All commands return 0 for success and 1 for errors, unless stated otherwise.

Install Concrete with c5:install

Use this to install Concrete. Example:

 concrete/bin/concrete5 c5:install --db-server=DB_SERVER --db-username=DB_USERNAME --db-password=DB_PASSWORD --db-database=DB_NAME --site=SITE_NAME --starting-point=STARTING_POINT --admin-email=EMAIL --admin-password=PASSWORD --default-locale=LOCALE

Where:

  • DB_SERVER is the database server name (add :port for custom ports)
  • DB_USERNAME is the database username
  • DB_PASSWORD is the database password
  • DB_NAME is the database name (should exist and be empty)
  • SITE_NAME is the new Concrete site's name
  • STARTING_POINT is the initial data set (elemental_full or elemental_blank)
  • EMAIL is the admin account's email
  • PASSWORD is the admin account's password
  • LOCALE is the site language (default en_US)
 concrete/bin/concrete5 c5:install [--db-server DB-SERVER] [--db-username DB-USERNAME] [--db-password DB-PASSWORD] [--db-database DB-DATABASE] [--site SITE] [--canonical-url CANONICAL-URL] [--canonical-ssl-url CANONICAL-SSL-URL] [--starting-point STARTING-POINT] [--admin-email ADMIN-EMAIL] [--admin-password ADMIN-PASSWORD] [--demo-username DEMO-USERNAME] [--demo-password DEMO-PASSWORD] [--demo-email DEMO-EMAIL] [--language LANGUAGE] [--site-locale SITE-LOCALE] [--config CONFIG] [--attach] [--force-attach] [-i|--interactive]

Sample session:

$ concrete/bin/concrete5 c5:install ...
5%: Starting installation and creating directories.
10%: Creating database tables.
15%: Adding admin user.
...
95%: Finishing.
Installation Complete!

$

Reset a Concrete Installation with c5:reset

To reset Concrete, use this command. It's risky as it erases all site content and database tables so be sure that is what you want. Use --force to confirm.

Sample session:

$ concrete/bin/concrete5 c5:reset -f
Listing tables... done.
...
Deleting directory application/files... done.
Creating directory application/files... done.
Creating empty file application/files/index.html... done.

$

Generate IDE Symbols with c5:ide-symbols

Developers using IDEs for Concrete development can utilize c5:ide-symbols for better code recognition and auto-completion. This command addresses the issue of unrecognized facades and proxy classes (like \Core) in IDEs. It also assists IDEs in identifying the class names resulting from IoC calls (e.g., \Core::make('config')).

Running concrete/bin/concrete5 c5:ide-symbols generates two files:

  1. concrete/src/Support/__IDE_SYMBOLS__.php: Defines facade classes and their methods for method suggestions.
  2. concrete/src/Support/.phpstorm.meta.php: Helps PhpStorm (and potentially Eclipse PDT with a feature request) identify the type of results from calls like \Core::make('config').

Configure Concrete with c5:config

The c5:config CLI command lets you manage Concrete configuration options not available in the dashboard, or for scripting configuration changes. It can retrieve and set all Concrete parameters. For example, concrete/bin/concrete5 c5:config set concrete.i18n.choose_language_login true enables language selection on the login page. Settings applied via c5:config override dashboard values, but using --generated-overrides (-g) option retains dashboard control.

Run Concrete Jobs with c5:job

The c5:job CLI command enables direct execution of Concrete jobs or job sets. For example, concrete/bin/concrete5 c5:job generate_sitemap index_search runs specific jobs, while concrete/bin/concrete5 c5:job --set Default runs a job set named Default.

Clear Concrete Cache with c5:clear-cache

Clear the Concrete cache easily with concrete/bin/concrete5 c5:clear-cache.

Install Concrete Packages with c5:package-install

Use c5:package-install to install packages, passing the package handle and any required options. For example, concrete/bin/concrete5 c5:package-install theme_package_handle --full-content-swap installs a theme.

Update Concrete Packages with c5:package-update

Update packages with c5:package-update, using options like --force (-f) for forcing updates without version change, and --all (-a) for updating all installed packages.

Uninstall Concrete Packages with c5:package-uninstall

Uninstall packages using concrete/bin/concrete5 c5:package-uninstall PACKAGE_HANDLE. Optionally, use --trash to move the package to Concrete trash.

Manage Package Translations with c5:package-translate

Refer to the Localization section of the Developers manual for details.

Pack Concrete Packages with c5:package-pack

The c5:package-pack command offers several functions for package development:

  • Expand short PHP tags with --short-tags (-s).
  • Create PNG icons from SVG files with --compile-icons (-i).
  • Compile translation files with --compile-translations (-t).

Results can be saved to the package directory (--update-source-directory or -u) or as a ZIP archive (--zip or -z). Use --keep (-k) to include dotfiles and source files in the ZIP. Inkscape is needed for SVG to PNG conversion.

  • Update source directory: concrete/bin/concrete5 c5:package-pack PACKAGE_HANDLE -u
  • Create ZIP file: concrete/bin/concrete5 c5:package-pack PACKAGE_HANDLE -z

Execute PHP Scripts with c5:exec

Run PHP scripts within the Concrete environment using c5:exec. For example, concrete/bin/concrete5 c5:exec create-users.php executes a script to add users.

Control Web Server Configuration with c5:service

Manage .htaccess file for Apache web server settings aligned with Pretty URL configurations. Specify your web server (currently apache or nginx) when using this command.

Jobs Overview

Jobs are scripts in the Optimization sections of the System & Settings area in the Dashboard, designed for tasks that are intensive, periodic, and require no user interface.

Each icon represents an installed Job. The play button executes the job, which can also be triggered via external schedulers like cron or set to run at specific times during page visits on your Concrete CMS site. Developers can easily create and include these jobs in packages.

Creating a Job

To create a job in Concrete CMS, first make a PHP file with a lowercase, underscored name (like "summarize_statistics.php") for your task. Place this file in the application/jobs directory. In the file, define a PHP class named after the file, extending \Concrete\Core\Job\Job. This class should reside in the Application\Job namespace, and include getJobName(), getJobDescription(), and run() methods. The run() method holds your job's logic.

namespace Application\Job;
use \Concrete\Core\Job\Job as AbstractJob;

class SummarizeStatistics extends AbstractJob
{
    public function getJobName()
    {
        return t("Summarize Statistics.");
    }

    public function getJobDescription()
    {
        return t("Takes all detailed statistics and summarizes them.");
    }

    public function run()
    {
        // Job logic here
    }
}

Results

The run() method's return string displays in the Jobs Dashboard, typically showing success details and processed items count.

Error Handling

Errors are managed by throwing exceptions within the Job.

Installing the Job

Install jobs via the Dashboard (System & Settings > Optimization > Jobs) before running them. Uninstalled jobs appear at the bottom of the page.

Including in a Package

To include a job in a package:

  1. Create a jobs directory in your package (e.g., packages/super_stats/jobs/).
  2. Move your job class file there (packages/super_stats/jobs/summarize_statistics.php).
  3. Change the namespace to Concrete\Package\SuperStats\Job.

Install the job in your package's install() method using \Concrete\Core\Job\Job::installByPackage('summarize_statistics', $pkg);. Jobs are automatically uninstalled with the package.

Creating & Scheduling a Queueable Job

Queueable Jobs in Concrete CMS manage long or memory-intensive operations efficiently by working on a subset of items, maintaining low memory usage.

Creating a Queueable Job

Queueable Jobs extend a different class and implement specific methods using the \Concrete\Core\Foundation\Queue class. Consider transforming a basic job into a Queueable Job for performance improvement, especially for large-scale tasks.

  1. Extending the QueueableJob Class: Replace \Concrete\Core\Job\Job with \Concrete\Core\Job\QueueableJob.

  2. Implement Required Methods: Implement the abstract methods from QueueableJob class involving \ZendQueue\Queue and \ZendQueue\Message.

  • Start Method: Seed the queue with page IDs using $q->send($queryRow['cID']); after fetching them with a lightweight database query.

    php public function start(\ZendQueue\Queue $q) { // Code to seed the queue }

  • ProcessQueueItem Method: Process each queue item. $msg->body contains the data sent to the queue.

    php public function processQueueItem(\ZendQueue\Message $msg) { // Code to process each item }

  • Finish Method: Conclude the job, usually without needing data about processed items.

    php public function finish(\ZendQueue\Queue $q) { return t('All pages processed'); }

Scheduling a Queueable Job

To schedule Queueable Jobs differently than regular jobs:

  1. Start the Job: Schedule the Job URL for the Queueable Job to initiate it.

    http://www.yoursite.com/index.php/ccm/system/jobs/run_single?auth=authenticationHash&jID=1

  2. Schedule Job Watcher Process: Run this URL frequently to process next items in any queue.

    http://www.yoursite.com/index.php/ccm/system/jobs/check_queue?auth=authenticationHash

    This works for multiple Queueable Jobs, handling items in batches.