Installation

Package Installation in Concrete CMS

When installing a package in Concrete CMS, the install() method in the Package controller is used. This method is critical for registering new items like block types or themes within the system. Here's a basic implementation:

public function install()
{
    $pkg = parent::install();
    BlockType::installBlockType('document_library', $pkg);
}

The parent::install() method is crucial as it creates and returns a Package object. This object is then passed to methods like installBlockTypeFromPackage() for proper installation and file location.

When to Include install() Method

The install() method isn't mandatory but is commonly used for registering new functionalities. If your package doesn't introduce new block types, themes, or similar components, and just runs custom code, you might not need this method.

Error Handling During Installation

To handle errors during installation, such as version incompatibility, you can throw exceptions before the parent::install() call:

public function install()
{
    if (version_compare(phpversion(), '5.4.0', '<')) {
        throw new \Exception('You must be run PHP 5.4 or greater to use this package.');
    }
    $pkg = parent::install();
    BlockType::installBlockType('document_library', $pkg);
}

This approach ensures the installation process is halted and an informative error message is displayed to the user if certain requirements aren't met.

Custom Installation Messaging

You can add custom messages or forms to the installation process of a package in Concrete CMS. This is helpful for providing extra information or obtaining user input before the installation completes.

Creating Custom Installation Messages

To display a custom message or form during installation, create a file at packages/package_handle/elements/dashboard/install.php. Content in this file appears to the user after they initiate but before they confirm the package installation.

Adding a Form to Installation

To incorporate a form, add it to the custom message file:

<input type="checkbox" name="installSampleContent" value="1" /> Install sample content.

Then, in the install() method of controller.php, you can process the form data:

public function install()
{
    $pkg = parent::install();

    $r = \Request::getInstance();
    if ($r->request->get('installSampleContent')) {
        // install sample content.
    }
}

Package Dependencies in Concrete CMS

Concrete CMS has a package dependency system for defining requirements and incompatibilities between packages.

Declaring Dependencies

Declare dependencies in your package's controller.php using either a public method or a protected property:

Using getPackageDependencies Method

public function getPackageDependencies()
{
    return [];
}

Using $packageDependencies Property {#using-$packagedependencies-property}

protected $packageDependencies = [];

Requiring Other Packages

To require another package other_package_handle:

Basic Requirement

[
    'other_package_handle' => true,
]

This ensures your package installs only if other_package_handle is already installed.

Minimum Version Requirement

[
    'other_package_handle' => '2.0.0',
]

Requires at least version 2.0.0 of other_package_handle.

Version Range Requirement

[
    'other_package_handle' => ['2.0.0', '2.2.99'],
]

Requires a version between 2.0.0 and 2.2.99 of other_package_handle.

Declaring Incompatibilities

To prevent installation alongside other_package_handle:

[
    'other_package_handle' => false,
]

Complete Example

Here's an example with various dependency scenarios:

protected $packageDependencies = [
    'package_a' => true,
    'package_b' => '2.0.0',
    'package_c' => ['2.0.0', '2.2.99'],
    'package_d' => false,
];

Uninstallation of Concrete CMS Packages

To uninstall packages in Concrete CMS, create an uninstall() method in your package and execute parent::uninstall() before your custom code. For instance, to remove custom database tables:

public function uninstall()
{
    parent::uninstall();
    $db = \Database::connection();
    $db->query('drop table FooBar');
    $db->query('drop table FooBaz');
}

Note: Most packages don't require a custom uninstall() method since core elements like block types and themes are automatically removed.

Custom Options During Uninstallation

For custom messages or forms during uninstallation, add a file at packages/package_handle/elements/dashboard/uninstall.php. Anything in this file appears before the final confirmation of uninstallation.

Including a Form

To include a form, add HTML directly and check the post request in the uninstall() method:

<input type="checkbox" name="removeFrontendContent" value="1" /> Remove front-end pages beneath /store.

Then, handle it in the uninstall() method:

public function uninstall()
{
    parent::uninstall();
    $r = \Request::getInstance();
    if ($r->request->get('removeFrontendContent')) {
        // Custom removal logic
    }
}