Develop a Custom Package for Use in ProcessMaker Platform
Learn how to develop a custom package for ProcessMaker Platform to extend its functionality.
Overview
Extend ProcessMaker's functionality with custom functions and/or integrations with third-party services by developing your own package.
Requirements
The following are required or assumed to successfully create a package for ProcessMaker Platform:
You are a developer that is comfortable performing command-line operations. This is an advanced development topic.
You are comfortable and knowledgeable about Laravel artisan commands. See Laravel documentation.
ProcessMaker Platform is installed on your local computer.
PHP version 7 or later.
Create a Package
Follow these steps to create a package for ProcessMaker Platform:
Create a directory as a sibling directory to your local ProcessMaker Platform installation directory. This example names the new directory
processmaker-plugins
.For example, if your ProcessMaker Platform installation is within the directory
opt/processmaker
, create theprocessmaker-plugins
directory atDocuments/processmaker-plugins
.mkdir processmaker-plugins
Clone the
package-skeleton
GitHub repository into yourprocessmaker-plugins
directory.cd processmaker-plugins
git clone https://github.com/ProcessMaker/package-skeleton
Rename the cloned directory. This example uses the new name
my-first-package
.mv package-skeleton my-first-package
Change to the renamed directory,
my-first-package
.cd my-first-package
Rename the references of "package-skeleton" to the revised name of your package skeleton, "my-first-package". The following command renames all instances in the project.
php rename-project.php my-first-package
Edit the following JSON objects in the
composer.json
file from the package:name: Edit the
name
JSON object that references the directory path to your package development environment, such asmy-first-package
.friendly_name: Edit the
friendly_name
JSON object to the name of your revised project directory, such as "My First Package".
Perform these commands:
cd my-first-package
vim composer.json
Below is an example of these JSON objects in the
composer.json
file in themy-first-package
directory after they are edited:{
"name": "processmaker/my-first-package",
"friendly_name": "My First Package",
…
}
Save the changes: press the Esc key and enter
:wq
to save thecomposer.json
file and exit from vim.In your local ProcessMaker Platform installation, locate the
composer.json
file, and add a reference to your package in therepositories
JSON array.cd /opt/processmaker
vim composer.json
Below is an example of the
repositories
JSON array in thecomposer.json
file in themy-first-package
directory after they are edited:“repositories”: [
{
"type": "path",
"url": "../processmaker-plugins/my-first-package"
}
]
Save the changes: press the Esc key and enter
:wq
to save thecomposer.json
file and exit from vim.Edit the
console.php
file located inside your package to set up that package with the artisan commands in line 3 of that file. The commands below reference theprocessmaker-plugins/my-first-package
directory since this example names the package as such:cd /opt/
cd processmaker-plugins/my-first-package
cd routes
vim console.php
Save the changes: press the Esc key and enter
:wq
to save thecomposer.json
file and exit from vim.Build your package repository assets inside your package. The second command below references the
processmaker-plugins/my-first-package
directory since this example names the package as such:cd /opt/
cd processmaker-plugins/my-first-package/
npm install
npm run development
Rename the controller file
PackageSkeletonController.php
to the name of your package's name. Since this package uses the nameprocessmaker-plugins/my-first-package
, this example changesPackageSkeletonController.php
toMyFirstPackageController.php
:cd processmaker-plugins/my-first-package
cd src/Http/Controllers
ls
Inside your package, locate the controller file.
mv PackageSkeletonController.php MyFirstPackageController.php
Open your renamed file and ensure the controller file
MyFirstPackageController.php
has the same class name as your package project's name. Since in this example usesMyFirstPackageController.php
as renamed in the previous step, this example uses the following in line 12:class MyFirstPackageController extends Controller
Exit the file: press the Esc key and enter
:q
.Optionally, to delete your package when uninstalling it, include the code below in the
console.php
file of your package located in the file/opt/processmaker-plugins/my-first-package/routes/console.php
. Since this package uses the namemy-first-package
for this example, the second and fourth commands below references this name:// Uninstall package-skeleton
Artisan::command('my-first-package:uninstall', function () {
// Remove the vendor assets
Illuminate\Support\Facades\File::deleteDirectory(public_path('vendor/processmaker/my-first-package'));
$this->info('The package has been uninstalled');
})->describe('Uninstalls package');
Install the package using composer. Install the package via composer in your ProcessMaker Platform root folder. Since this package uses the name
my-first-package
for this example, the second command below references this name:cd /opt/processmaker
composer require processmaker/my-first-package --ignore-platform-reqs
Setup the package with the
php artisan
command in your ProcessMaker Platform root folder, referencing the name of your package. Since this package uses the namemy-first-package
for this example, the command below references this name:php artisan my-first-package:install
Uninstall the Package
Follow these steps to uninstall a custom package:
Go to the ProcessMaker root directory, such as
/opt/processmaker
.Run the following commands, changing
my-first-package
in the second command to the directory name of your package:php artisan my-first-package:uninstall
composer remove processmaker/my-first-package --ignore-platform-reqs
Related Topics
What is a Package?Last updated