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/concrete list
  Note: On *nix or MacOS X, if you get a "Permission denied" error, run chmod a+x concrete/bin/concrete.

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

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

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

concrete/bin/concrete 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/concrete 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.

Refresh Content for Boards with c5:boards:refresh

Use this command to refresh the content on boards and board instances:

concrete/bin/concrete c5:boards:refresh

Clear Cache with c5:clear-cache

Quickly clear the Concrete cache with this command:

concrete/bin/concrete c5:clear-cache

Compare Database Schema with c5:compare-schema

This command compares the Concrete XML schema, entity files, and database tables, and prints any differences:

concrete/bin/concrete c5:compare-schema

Manage Configurations with c5:config

Set or get configuration parameters for Concrete with this command:

concrete/bin/concrete c5:config set PARAMETER_NAME VALUE

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/concrete 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.

Set Database Charset with c5:database:charset:set

Set the character set and collation of your database connection using this command:

concrete/bin/concrete c5:database:charset:set CHARSET COLLATION

Fix Foreign Keys with c5:database:foreignkey:fix

Fix broken or missing foreign keys in the database using this command:

concrete/bin/concrete c5:database:foreignkey:fix

Clear Denylist Data with c5:denylist:clear

Clear denylist-related data (e.g., spam blockers, IP denylist):

concrete/bin/concrete c5:denylist:clear

Refresh Doctrine Entities with c5:entities:refresh

Refresh Doctrine database entities using this command:

concrete/bin/concrete c5:entities:refresh

Run PHP Scripts with c5:exec

Execute a PHP script within the Concrete environment with this command:

concrete/bin/concrete c5:exec SCRIPT_NAME.php

For example, concrete/bin/concrete c5:exec create-users.php executes a script to add users.

Export Express Entries with c5:express:export

Export express entries in Concrete:

concrete/bin/concrete c5:express:export

Generate File Identifiers with c5:files:generate-identifiers

Generate unique file identifiers for existing files:

concrete/bin/concrete c5:files:generate-identifiers

Generate IDE Symbols with c5:ide-symbols

Generate symbols to improve IDE support for facades and IoC calls in Concrete:

concrete/bin/concrete 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/concrete 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').

Get Installation Info with c5:info

Retrieve detailed information about the current Concrete installation:

concrete/bin/concrete c5:info

Install Concrete with c5:install

Use this command to install Concrete:

concrete/bin/concrete 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/concrete 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/concrete c5:install ...
5%: Starting installation and creating directories.
10%: Creating database tables.
15%: Adding admin user.
...
95%: Finishing.
Installation Complete!

$

Check if Concrete is already installed with c5:is-installed

Check if Concrete is already installed

concrete/bin/concrete c5:is-installed

Run a Concrete Job with c5:job

Run a specific job or job set:

concrete/bin/concrete c5:job JOB_HANDLE

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

Install or Update Languages with c5:language-install (alias: c5:install-language)

Install or update languages for the Concrete site:

concrete/bin/concrete c5:language-install LANGUAGE_CODE

Install a Package with c5:package:install (aliases: c5:package-install, c5:install-package)

Install a package:

concrete/bin/concrete c5:package-install PACKAGE_HANDLE

Pack Concrete Packages with c5:package:pack (aliases: c5:pack-package, c5:package-pack)

Pack a package into a zip file or update the source directory:

concrete/bin/concrete c5:package-pack PACKAGE_HANDLE --zip

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/concrete c5:package:pack PACKAGE_HANDLE -u {#concrete/bin/concrete c5-package-pack PACKAGE_HANDLE -u}
  • Create ZIP file: concrete/bin/concrete c5:package:pack PACKAGE_HANDLE -z {#concrete/bin/concrete c5-package-pack PACKAGE_HANDLE -z}

Translate a Package with c5:package-translate (aliases: c5:package-translate, c5:translate-package)

Generate or update translation files for a package:

concrete/bin/concrete c5:package-translate PACKAGE_HANDLE

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

Uninstall a Package with c5:package-uninstall (aliases: c5:package-uninstall, c5:uninstall-package)

Uninstall a package:

concrete/bin/concrete c5:package-uninstall PACKAGE_HANDLE

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

Update a Package with c5:package:update (aliases: c5:package-update, c5:update-package)

Update an installed package:

concrete/bin/concrete c5:package-update PACKAGE_HANDLE

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.

Check PHP Coding Style with c5:phpcs

Check or fix the PHP coding style across your project:

concrete/bin/concrete c5:phpcs [fix]

Reindex Pages, Files, Users, and Entities with c5:reindex

Reindex all content for search functionality:

concrete/bin/concrete c5:reindex

Rescan Files with c5:rescan-files

Rescan files in the file manager:

concrete/bin/concrete c5:rescan-files

Reset a Concrete Installation with c5:reset

This command resets a Concrete installation, deleting all files and emptying the database. Use with caution, and confirm using --force.

Example:

concrete/bin/concrete c5:reset -f

Sample session:

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

$

Manage Web Server Configuration with c5:service

Check or update the web server configuration (e.g., .htaccess for Apache):

concrete/bin/concrete c5:service SERVER_TYPE

Generate Sitemap with c5:sitemap:generate

Generate an XML sitemap for SEO purposes:

concrete/bin/concrete c5:sitemap:generate

Install a Theme with c5:theme:install

Install a Concrete theme:

concrete/bin/concrete c5:theme:install THEME_HANDLE

Run Database Migrations with c5:update

Bring your Concrete installation up to date by running all database migrations:

concrete/bin/concrete c5:update

Bulk Assign Users to Groups with c5:user-group:bulk-assign-users

Assign users to groups in bulk from a CSV file:

concrete/bin/concrete c5:user-group:bulk-assign-users FILE_PATH

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.