Package Magic - Build Tool Plugin Documentation

Dashboard > Extend concrete5 > Package Tools

To help you prepare packages for download, Package Magic provides a suite of tools to help build and validate packages.

When checking for best practice code in packages, the Prohibited Code Check build tool utilizes further plugins for Prohibited Code Cheks. Latest documentation can be found at Prohibited Code Check Plugin Documentation.

All automated changes to package files are made safely through intermediaries and checked for compilation errors before replacing the actual package files.

Package Magic provides a lot more than dashboard equivalents to the core CLI tools. Most tools can operate on installed packages and on uploaded packages that are 'Awaiting Installation', so you don't need to actually install a package before applying a tool to it. As noted below, some tools such as Force Update are only applicable to packages that are installed.

[ Package Magic ]

Build Tools Plugins

Package Magic can applly a range of tools provided by Build Tool plugins.

Functionality can be extended by adding plugin classes for additional Build Tools. Build Tool plugins are simple classes that provide the functionality to apply tools to packages . They should inherit from BuildToolPluginBase. Details are provided by comments in the code.

Plugins can be added by placing the plugin classes at packages/anyPackageName/src/PackageMagic/BuildTools/Plugins/PluginName or application/src/PackageMagic/BuildTools/Plugins/PluginName. Plugins can also be similarly placed beneath any namespace declared in a package controller's AutoloaderRegistries.

[ Package Magic ]

Block Usage

List blocks and templates with usage.

Knowing where a block or template is used is important when deciding whether a package can be uninstalled. This report lists all blocks and block templates provided by a package and where they have been used. Use is categorised by currently approved pages and pages that are unapproved or on old versions.

[ Package Magic ]

CSS Validate

Validate CSS files.

CSS files and fragments of CSS embedded in php files are vaildated by submitting to the W3C Validation Service.

[ Package Magic ]

Clear All Translations

Removes all translations and removes the /languages directory.

Select an installed or available to install concrete5 package and apply this tool to clear all translations. The /languages directory will be removed and with it all .pot, .po and .mo files and all locale subdirectories.

[ Package Magic ]

Comment Density

Calculate comment density for php.

Select an installed or available to install concrete5 package and apply this tool to calculate comment density for all php files in the package. This is based on counting characters within comments with white space compressed for each file as a proportion of all characters in the file.

[ Package Magic ]

Compile Check

Checks that all .php files compile.

Select an installed or available to install concrete5 package and apply this tool to run a compilation check on all php files in the package. This makes most sense for packages that are awaiting installation. Any package already installed is unlikely to have faulty php files within it (but you never know).

[ Package Magic ]

Edit Package Version

Increment the package version.

Select an installed or available to install concrete5 package and use this tool to increment the version number in the package controller. This should normally be immediately followed by running the package update. Use this prior to downloading a modified package archive.

[ Package Magic ]

Expand Short Tags

Expand short tags in all php source files, replacing the original file with the same file with tags expanded.

Select an installed or available to install concrete5 package and apply this tool to expand short tags <? and <?=. This will only expand short tags if they are compilable. i.e. Short tags need to be enabled in php.ini.

[ Package Magic ]

Extract Translation Strings

Extract translatable strings and create an associated pot file.

Select an installed or available to install concrete5 package and apply this tool to extract translatable strings. Translatable strings are extracted from t(), tc() and t2() functions in the package source and collected into a .pot file. This is the first step of translating a package - these strings then need to be translated for each language at concrete5 Translate.

[ Package Magic ]

Force Package Update

Force concrete5 to execute the package update, even if the version number has not been incremented.

Select an installed concrete5 package and apply this tool to force the package update() method to be applied, together with other update processing from the core. Can sometimes be helpful while developing packages to avoid messing with new version numbers.

[ Package Magic ]

Icon Add

Add a package icon sourced from the concrete5 file manager.

Select an image file from the file manager and use it to add or replace the icon.png for a package. Icons are generally 97x97px, but on more recent versions of concrete5 can be up to 200x200px.

[ Package Magic ]

Inspect

Inspect package contents.

Select an installed concrete5 package and apply this tool to inspect package contents, as in the core Uninstall dialog.

[ Package Magic ]

JavaScript Validate

Validate JavaScript files.

JavaScript files and fragments of JavaScript embedded in php files are vaildated by submitting to the Google Closure Compiler web service.

[ Package Magic ]

LESS Compiler

Compile LESS files.

Compile LESS source files within the package. By default, any file called view.less is compiled to view.css within the same directory. Text options enable other LESS source and CSS output file names to be configured.

By default, paths between view.css (or equivalent) and assets such as images used as backgrounds are relative to view.css. A checkbox option allows paths to be made absolute with respect to the web root. This can be convenient for complicated paths to assets or where you intend to move view.css to another directory, but can cause broken URLs when packages need to be portable between web root and subdirectories.

Compression and sourcemap generation follow the site cache settings.

[ Package Magic ]

Manage Locales

Manage the package translation locales.

Select an installed or available to install concrete5 package and apply this tool to manage locales. A list of all locales will be presented with currently configured locales checked. When run, the configured locales will be populated with available translations from concrete5 Translate.

[ Package Magic ]

Prohibited Code Check

Searches source for deprecated code and a forbidden functions.

Select an installed or available to install concrete5 package and apply this tool to anayze the package file-by-file for deprecated code and forbidden functions. This check is not complete as the semantics of some unwanted code is too complex for simple analysis. For a full markeplace Linter check, please use the Linter test page.
These are all things that may be considered by the PRB, but are not absolutes. Deprecated code changes with core versions and forbidden functions can be granted exceptions where there use is relevant to the application.
Individual checks are implemented through a further level of Prohibited Code Check plugins.

[ Package Magic ]

Remove Package Files

Removes all files associated with an uninstalled package.

The core Add Functionality page provides a means to remove all files associated with a package at the time it is installed, but only at the time it is unistalled. This tool will remove all files and directories associated with a package as long as it is not currently installed, so can be used to clear up packages uploaded but never installed, or packages uninstalled but not removed at the time.

[ Package Magic ]

Review Files

Conveniently see the files report without running any other tools.

Select an installed or available to install concrete5 package and apply this tool to review the files. The files report is presented without any other tools needing to be run first.

[ Package Magic ]

SVG Icon Compile

Compile package and block icons in SVG format into .png files.

Select an installed or available to install concrete5 package and apply this tool to compile package and block icon.svg files to a corresponding icon.png.

[ Package Magic ]

Translation Completeness

Report on the completeness for locales in package.

Select an installed or available to install concrete5 package and apply this tool to report on the completeness of translations.

[ Package Magic ]

View Translation Strings

View translatable strings in the package pot file.

Select an installed or available to install concrete5 package and apply this tool to review translatable strings from the package .pot file.