---
description: >-
  Learn how to develop a custom package for ProcessMaker Platform to extend its
  functionality.
---

# Creating Your First ProcessMaker Package

## Overview <a href="#overview" id="overview"></a>

Extend ProcessMaker's functionality with custom functions and/or integrations with third-party services by developing your own [package](..).

## Requirements <a href="#requirements" id="requirements"></a>

The following are required or assumed to successfully create a package for ProcessMaker Platform:

<table data-full-width="false"><thead><tr><th width="273">Requirement</th><th width="469">Function</th></tr></thead><tbody><tr><td>Working programming knowledge</td><td>To code the package. Familiarity with <a href="https://laravel.com">Laravel</a> &#x26; <a href="https://php.net">PHP</a> is a big plus.<br>This is an advanced development topic.</td></tr><tr><td>Access to ProcessMaker Platform</td><td>CLI access to a ProcessMaker instance with super user privileges. Typically, this is done in a local development environment.</td></tr></tbody></table>

## Step 1: Creating the Package <a href="#create-a-package" id="create-a-package"></a>

First, let's start by creating a sibling directory to your ProcessMaker Platform installation folder. This example names the new directory `processmaker-plugins.` For example, if your ProcessMaker installation is located at `/opt/processmaker`, you can create the `processmaker-plugins` directory at `/opt/processmaker-plugins.`

Clone and follow the instructions for setting up the [package-skeleton](the-package-skeleton) template from our GitHub repository into your `processmaker-plugins` directory.

Then edit your packages `composer.json` file, similar to the below:

{% code overflow="wrap" %}
```json
{
    "name": "processmaker/my-first-package",
    "friendlY_name": "My First Package",
    "description": "Package Skeleton to develop a package for ProcessMaker Platform"
}
```
{% endcode %}

Next, locate the the `composer.json` file for your ProcessMaker application (not to be confused with your packages composer.json file).

{% hint style="info" %}
You can find the applications main `composer.json` file at the root of the ProcessMaker application, assuming you are following along, it would be located at `/opt/processmaker/composer.json`
{% endhint %}

Now we need to add a reference to your package in the `repositories` block of the `composer.json` in order for the application to know of it's existence.

{% code overflow="wrap" %}
```json
"repositories": 
    [
        {
            "type": "path",
            "url": "../processmaker-plugins/my-first-package"
        }
    ]
```
{% endcode %}

### Extras

There are still a few things that will need to be fixed by hand:

You will need to rename your core controller from `PackageSkeletonController.php` to your package's name (e.g. `MyFirstPackageController.php`Located here, assuming you are following along: `/opt/processmaker-plugins/my-first-package/src/Http/Controllers` )

Now, let's confirm that the controller name is right in addition to the filename.

Open your renamed controller and change the controller name, assuming you are following our conventions, to `MyFirstPackageController` .&#x20;

## Step 2: Creating PHP Artisan Commands

A good practice is to make sure your install and uninstall commands work well.

Assuming the package is located within `/opt/processmaker-plugins/my-first-package` you will want to edit the file `/opt/processmaker-plugins/my-first-package/routes/console.php` located inside your package to set up the artisan commands.

{% hint style="info" %}
Depending on your preference, the install and uninstall can also be object oriented and done via classes, which would be located at `src/Console/Commands/Install.php` and `src/Console/Commands/Uninstall.php` , respectfully.
{% endhint %}

### The Install Command

Perhaps you want to install a database table with your package for specific configuration needs.

{% hint style="info" %}
_We are assuming that you might have a seeder class named `MyFirstPackageSeeder` that would be responsible for seeding the database with your table and data._
{% endhint %}

{% code overflow="wrap" %}
```php
Artisan::command('my-first-package:install', function () {
    
    Artisan::call('vendor:publish', [
        '--tag' => 'my-first-package',
        '--force' => true
    ]);

    Artisan::call('db:seed',
        [
            '--class' => 'ProcessMaker\Package\MyFirstPackage\Seeds\MyFirstPackageSeeder',
            '--force' => true,
        ]
    );

    $this->info('MyFirstPackage been installed!');
})->describe('Installs MyFirstPackage');
```
{% endcode %}

### The Uninstall Command

An example of an uninstall command might be to delete your packages assets when uninstalling.

{% code overflow="wrap" %}
```php

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');
```
{% endcode %}

### Running the Artisan Commands

All artisan commands MUST be run within the ProcessMaker application root directory. E.g. `/opt/processmaker`

To execute the install command, you would then run this from your terminal:

```bash
cd /opt/processmaker
```

```bash
php artisan my-first-package:install
```

To execute the uninstall command, you would then run this from your terminal:

```bash
php artisan my-first-package:uninstall
```

You may want to additionally execute the following lines to completely eliminate the package from the environment:

```bash
composer remove processmaker/my-first-package --ignore-platform-reqs
```

## Step 3: Building Front End Assets

If you are doing any kind of UI related work or sometimes even other backend work that you need to include npm modules, here is how you can go about it.

Make sure to add all your configuration and dependencies within your packages `package.json` , located in the root directory of your package (`/opt/processmaker-plugins/my-first-package` if you have been following along).

Then run your npm commands:

```
npm install && npm run dev
```

## Step 4: The Service Provider

Finally, the service provider class is what contains the instructions that laravel will execute when your package is loaded.

Here is an example of what can be contained inside a service provider class, specifically within the boot method:

{% code overflow="wrap" %}
```php
public function boot(){
        //Load any blade views
        $this->loadViewsFrom(__DIR__ . '/../resources/views/', 'my-first-package');
        //Publish package specific assets
        $this->publishes([
            __DIR__.'/../public' => public_path('vendor/processmaker/my-first-package'),
        ], 'my-first-package');

        if ($this->app->runningInConsole()) {
            require(__DIR__ . '/../routes/console.php');
        } else {
            // Assigning to the web middleware will ensure all other middleware assigned to 'web'
            // will execute. If you wish to extend the user interface, you'll use the web middleware
            Route::middleware('web')
                ->namespace($this->namespace)
                ->group(__DIR__ . '/../routes/web.php');
            Route::middleware('api')
                ->namespace($this->namespace)
                ->prefix('api/1.0')
                ->group(__DIR__ . '/../routes/api.php');
            //Push the menu class, if you have one
            Route::pushMiddlewareToGroup('web', AddMyFirstPackageMenus::class);
        }
        //Load any migrations you may have for the database
        $this->loadMigrationsFrom(__DIR__ . '/../database/migrations');
        // Register a seeder that will be executed in php artisan db:seed
        $this->registerSeeder(MyFirstPackageSeeder::class);
        // Complete the connector boot
        $this->completePluginBoot();

    }
```
{% endcode %}

{% hint style="info" %}
This can also be used in the install and uninstall commands above.
{% endhint %}



