The install() method from a Package controller is automatically run when the package is installed. In our block type example, we use the Concrete\Core\Block\BlockType\BlockType::installBlockTypeFromPackage() method, which takes a block type handle, and a Concrete\Core\Package\Package object as its second parameter.
public function install()
{
$pkg = parent::install();
BlockType::installBlockType('document_library', $pkg);
}
The package object is created by using the parent::install() method, which returns a fully instantiated Package object. In general, most items that can be installed through packages will have an install() method (or something very similar) which takes this package object as one of its parameters. This package object must be passed through when installing the item through a package, or Concrete CMS won't know where to look for the files used by that block type, theme, or other item of functionality.
Note: the install() method is not required in the package's custom controller – but almost all packages will want to include it, because they're installing one or more items of functionality that need to have their custom installation routines run. If your package doesn't install anything like a block type or a theme, and instead just needs to run some custom functionality on every page load, you might be able to get away with not specifying an install() method at all. This is not usually the case.
Error Handling in Installation
Sometimes you might need to abort an installation – for example, say your package requires PHP 5.4 and the version of PHP installed is only 5.3. Just throw an exception from within the install() method before you run parent::install() and the error will be nicely displayed to the end user, and installation aborted.
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);
}