April 2020 Archives

Octopus – Basic ” Staging First ” Lifecycle

In this post, I am going to show you how to prevent a release from being deployed directly to production if it hasn’t been deployed to staging. Octopus has a great feature called ( Lifecycles ) that allows you to create advanced deployment workflows for any type of project.

This way you are able to force your team to follow a strict deployment process that will definitely improve your test routine and the way how you deploy code changes. No more untested code changes on production!

Okay, let’s start. Here is how you can create a custom Lifecycle.

From the Lifecycle page, click on the ADD LIFECYCLE button.
Give the Lifecycle a name and add a description. For example ” Project X “.
You can leave the Retention Policy unchanged ( Keep all ) for now.

Scroll down and continue with the next tab.

Click ADD PHASE, to explicitly define the phases of the lifecycle.
Give the phase a name. For example ” Staging ” because I want you deploy and review your changes on staging first.
Click ADD ENVIRONMENT to define which environments can be deployed to during this phase of the lifecycle. Choose your staging environment from the dropdown list.

If you haven’t add an environment yet, you must create at least two ( staging, production ). Learn more about Environments.

Scroll up again and save the new Lifecycle. Now go back to your project and click the link Process in the left sidebar. Next, hit the button Change on the right-hand side and select the Lifecycle that you’ve just created and save the changes.

After that, try to deploy a new release. You will see that there is no option to deploy on production. Just must deploy your code successfully to your staging environment first in order to be able to push changes to production.

This is just one of many examples of how you can improve your deployment routine with Octopus.

Octopus – How to fix ” Missing deployment buttons “

I saw a few comments on Stackoverflow where people ask how to setup or re-enable deployment buttons for staging or production. The answer is not quite straightforward, because you have to review a few things. Here is a quick checklist that may help you to identify the cause of missing deployment buttons.

1. Process

Make sure you have selected the right Lifecycle in Projects > Your Client > Deployments > Process.

2. Lifecycles

If you believe one Phase / Environment missing, go to Library > Lifecycles and try to add the missing environment in the Phases section.

3. Environments

In order to be able to add a new phase, make sure all required environments are listed in Infrastructure > Environments.

Learn more about Environments.

October CMS – Execute Console Commands Sequentially

In this tutorial, I am going to show you how to execute long running PHP processes sequentially in October CMS from anywhere of your code.

First, you must define a default driver, which is pretty much a handler for managing how to run a queued job, identifying whether the jobs succeeded or failed, and trying the job again. In October CMS, the driver settings are located in the file in ./config/queue.php.

<?php

return [

    /*
    |-------------------------------------------------------------------------
    | Default Queue Driver
    |-------------------------------------------------------------------------
    |
    | The Laravel queue API supports a variety of back-ends via an unified
    | API, giving you convenient access to each back-end using the same
    | syntax for each one. Here you may set the default queue driver.
    |
    | Supported: "null", "sync", "database", "beanstalkd",
    |            "sqs", "iron", "redis"
    |
    */

    'default' => 'database',

<?php

return [

|-------------------------------------------------------------------------

| Default Queue Driver

|-------------------------------------------------------------------------

| The Laravel queue API supports a variety of back-ends via an unified

| API, giving you convenient access to each back-end using the same

| syntax for each one. Here you may set the default queue driver.

| Supported: "null", "sync", "database", "beanstalkd",

| "sqs", "iron", "redis"

'default' => 'database',

If you are new to this, I recommend to start with the database driver. This driver is good enough to execute your console commands synchronously in the background without slowing down your PHP calls. As a next step, you have to register a custom console command in your Plugin.php file. For example company.pluginname.

/**
 * Register console commands
 */
public function register() {

    $this->registerConsoleCommand('company.pluginname', 'Company\Pluginname\Console\Test');
}

/**

* Register console commands

public function register() {

$this->registerConsoleCommand('company.pluginname', 'Company\Pluginname\Console\Test');

}

For test purposes, I created a console command company.pluginname which will execute the method backupList.

bash-4.4# php artisan company:pluginname 123 --customer=list
Parameter ID 123 passed.

1 2	bash-4.4# php artisan company:pluginname 123 --customer=list Parameter ID 123 passed.

<?php namespace Company\Pluginname\Console;

use Illuminate\Console\Command;
use Symfony\Component\Console\Input\InputOption;
use Symfony\Component\Console\Input\InputArgument;

class Test extends Command
{
    /**
     * @var string The console command name.
     */
    protected $name = 'company:pluginname';

    /**
     * @var int
     */
    protected $customerId = 0;

    /**
     * @var string
     */
    protected $description = 'No description provided yet...';

    /**
     *
     */
    public function backupList()
    {
        $this->output->writeln(sprintf('Parameter ID %s passed.', $this->customerId));
        
        // Call API
        // Compress response and save on disk
        // Write information into Log table
    }

    /**
     * Execute the console command.
     * @return void
     */
    public function handle()
    {
        $this->customerId = $this->argument('customerId');

        $option = $this->option('customer');

        $args = explode(',', $option);

        if (in_array('list', $args)) {
            $this->backupList();
        }
    }

    /**
     * Get the console command arguments.
     * @return array
     */
    protected function getArguments()
    {
        return [
            ['customerId', InputArgument::REQUIRED, '(Required) Customer Id']
        ];
    }

    /**
     * Get the console command options.
     * @return array
     */
    protected function getOptions()
    {
        return [
            ['customer', null, InputOption::VALUE_REQUIRED, 'An example option.', null],
            ['queue', null, InputOption::VALUE_OPTIONAL, 'An example option.', null]
        ];
    }
}

<?php namespace Company\Pluginname\Console;

use Illuminate\Console\Command;

use Symfony\Component\Console\Input\InputOption;

use Symfony\Component\Console\Input\InputArgument;

class Test extends Command

{

/**

* @var string The console command name.

protected $name = 'company:pluginname';

/**

* @var int

protected $customerId = 0;

/**

* @var string

protected $description = 'No description provided yet...';

/**

public function backupList()

{

$this->output->writeln(sprintf('Parameter ID %s passed.', $this->customerId));

// Call API

// Compress response and save on disk

// Write information into Log table

}

/**

* Execute the console command.

* @return void

public function handle()

{

$this->customerId = $this->argument('customerId');

$option = $this->option('customer');

$args = explode(',', $option);

if (in_array('list', $args)) {

$this->backupList();

}

/**

* Get the console command arguments.

* @return array

protected function getArguments()

{

return [

['customerId', InputArgument::REQUIRED, '(Required) Customer Id']

];

}

/**

* Get the console command options.

* @return array

protected function getOptions()

{

return [

['customer', null, InputOption::VALUE_REQUIRED, 'An example option.', null],

['queue', null, InputOption::VALUE_OPTIONAL, 'An example option.', null]

];

}

Let’s assume you have a front-end controller http://yourpage.dev/customer/list that calls an API, creates a list and saves it on disk. Executing all these steps can be time-consuming and simply slow down your controller. Instead, you can run such processes in the background with Artisan::queue.

<?php namespace Company\Pluginname\Controllers;

use Illuminate\Routing\Controller;
use Illuminate\Support\Facades\Artisan;

class Customer extends Controller
{
    public function list($id)
    {
        Artisan::queue('company:pluginname', [
            'customerId' => 123,
            '--customer' => 'list',
            '--queue' => 'default'
        ]);
    }
}

<?php namespace Company\Pluginname\Controllers;

use Illuminate\Routing\Controller;

use Illuminate\Support\Facades\Artisan;

class Customer extends Controller

{

public function list($id)

{

Artisan::queue('company:pluginname', [

'customerId' => 123,

'--customer' => 'list',

'--queue' => 'default'

]);

}

As soon as you hit the controller, artisan will queue a new record in the table jobs and wait until a queue worker executes the job. You just have to make sure that a Queue Worker is running in the background, otherwise jobs won’t get executed.

bash-4.4# php artisan queue:work --tries=3
[2020-04-14 04:11:52] Processing: Illuminate\Foundation\Console\QueuedCommand
[2020-04-14 04:11:54] Processed:  Illuminate\Foundation\Console\QueuedCommand
[2020-04-14 04:11:54] Processing: Illuminate\Foundation\Console\QueuedCommand
[2020-04-14 04:11:55] Processed:  Illuminate\Foundation\Console\QueuedCommand
[2020-04-14 04:11:55] Processing: Illuminate\Foundation\Console\QueuedCommand
[2020-04-14 04:12:14] Processed:  Illuminate\Foundation\Console\QueuedCommand

bash-4.4# php artisan queue:work --tries=3

[2020-04-14 04:11:52] Processing: Illuminate\Foundation\Console\QueuedCommand

[2020-04-14 04:11:54] Processed: Illuminate\Foundation\Console\QueuedCommand

[2020-04-14 04:11:54] Processing: Illuminate\Foundation\Console\QueuedCommand

[2020-04-14 04:11:55] Processed: Illuminate\Foundation\Console\QueuedCommand

[2020-04-14 04:11:55] Processing: Illuminate\Foundation\Console\QueuedCommand

[2020-04-14 04:12:14] Processed: Illuminate\Foundation\Console\QueuedCommand

I recommend to start a queue worker with Supervisor which is well explained on https://medium.com/@rohit_shirke/configuring-supervisor-for-laravel-queues-81e555e550c6

October CMS – How To Use Models In Custom Components

Components in October CMS can be used for custom output, such as JavaScript snippets, dynamic content from a web service or models. Components can also handle AJAX requests or other incoming data. In this tutorial, I will simply show you how to register a new component and output a list with records from the users table.

First of all, you have to register a new component in your Plugin.php file. For example, users.

<?php namespace Playground\Sandbox;

use System\Classes\PluginBase;
use System\Classes\SettingsManager;

class Plugin extends PluginBase
{

    /**
     * Register Component
     *
     * @return array
     */
    public function registerComponents()
    {
        return [
            'Playground\Sandbox\Components\Users' => 'users'
        ];
    }
}

<?php namespace Playground\Sandbox;

use System\Classes\PluginBase;

use System\Classes\SettingsManager;

class Plugin extends PluginBase

{

/**

* Register Component

* @return array

public function registerComponents()

{

return [

'Playground\Sandbox\Components\Users' => 'users'

];

}

Create the following structure within the components folder which must contain the file Users.php and users/default.htm.

.
└── playground
    └── sandbox
        ├── Plugin.php
        ├── components
        │   ├── Users.php
        │   └── users
        │       └── default.htm

└── playground

└── sandbox

├── Plugin.php

├── components

│ ├── Users.php

│ └── users

│ └── default.htm

Below you will find the content for the default.htm file which will basically output a list of all users.

<div class="list-users">
    {% for person in __SELF__.getPeople %}
        {{ person.username }} {{ person.email }}
    {% endfor %}
</div>

{% for person in __SELF__.getPeople %}

{% endfor %}

</div>

The Users.php file only requires a method getPeople and a reference to the new model, called UsersModel.

<?php namespace Playground\Sandbox\Components;

use Cms\Classes\ComponentBase;
use Playground\Sandbox\Models\Users as UsersModel;

class Users extends ComponentBase
{
    /**
     * Define component details.
     *
     * @return array
     */
    public function componentDetails()
    {
        return [
            'name' => 'playground.sandbox::lang.plugin.name',
            'description' => 'playground.sandbox::lang.plugin.description'
        ];
    }

    public function getPeople()
    {
        return (new UsersModel())->getPeople();
    }
}

<?php namespace Playground\Sandbox\Components;

use Cms\Classes\ComponentBase;

use Playground\Sandbox\Models\Users as UsersModel;

class Users extends ComponentBase

{

/**

* Define component details.

* @return array

public function componentDetails()

{

return [

'name' => 'playground.sandbox::lang.plugin.name',

'description' => 'playground.sandbox::lang.plugin.description'

];

}

public function getPeople()

{

return (new UsersModel())->getPeople();

}

In order to access a model, you must create one within the models folder.

├── models
│   └── Users.php

1 2	├── models │ └── Users.php

For test purposes, I simply return all records from the users table.

<?php namespace Playground\Sandbox\Models;

use Model;

/**
 * Class Users
 * @package Playground\Sandbox\Models
 */
class Users extends Model
{
    /**
     * @var string The database table used by the model.
     */
    public $table = 'users';

    /**
     * Return all records from users table.
     *
     * @return mixed
     */
    public function getPeople()
    {
        return self::all();
    }
}

<?php namespace Playground\Sandbox\Models;

use Model;

/**

* Class Users

* @package Playground\Sandbox\Models

class Users extends Model

{

/**

* @var string The database table used by the model.

public $table = 'users';

/**

* Return all records from users table.

* @return mixed

public function getPeople()

{

return self::all();

}

Now you can use the new component anywhere in your template files. I recommend to use [users] in your parent template file, because it will allow you to use the component in your child templates.

description = "Default layout"

[users]
==
<!doctype html>
<html lang="en">
<head>
</head>
<body>

<section id="body">
    <div class="wrapper">
        {% component 'users' %}
    </div>
</section>

{% scripts %}
{% framework extras %}
</body>

</html>

description = "Default layout"

[users]

<!doctype html>

<head>

</head>

<body>

{% component 'users' %}

</div>

</section>

{% scripts %}

{% framework extras %}

</body>

</html>

After a page reload, should you immediately see the list.

For more information, check out https://octobercms.com/docs/cms/components. The source code of this tutorial can be found on https://github.com/tobias-forkel/october-cms-playground

Octopus – How to fix ” There must be at least one enabled healthy machine to deploy “

I am pretty new to Octopus and just started implementing a deployment process for a new PHP project. After creating a new machine in Infrastructure > Deployment Targets I went back to Projects > My Project > Create Release and tried to start a deployment to our dev environment which caused the following error.

There must be at least one enabled healthy machine to deploy to in the environment, or the Project Deployment Target settings must be set to allow deployments to empty environments. Once you have corrected these problems you can try again. If the problem is related to a variable you will need to update the variables for this release or recreate the release for the changes to take effect. If the problem is related to the deployment process you will need to create a new release for the changes to take effect.

There must be at least one enabled healthy machine to deploy to in the environment, or the Project Deployment Target settings must be set to allow deployments to empty environments. Once you have corrected these problems you can try again. If the problem is related to a variable you will need to update the variables for this release or recreate the release for the changes to take effect. If the problem is related to the deployment process you will need to create a new release for the changes to take effect.

As you can see in the below screenshot, I tried to deploy a new release to the target Development.

The error message was strange because the target status of my Deployment Target was flagged as healthy. After comparing the settings I noticed that the environment Development in my deployment target settings was simply missing.

After adding the target Development to the list of Environments, I was able to proceed with the above deployment.

October CMS – Add Menu Item And Store Backend Settings

At some point you probably want to make your custom plugin for October CMS configurable and allow backend users to make changes within the plugin space. October CMS has a simple and intuitive backend navigation, which you can easily extend in no-time. Let’s assume you have a custom plugin that calls an external API. Here is how you can store API credentials by using the Settings Manager.

First of all, you must register the settings in your Plugin.php file.

<?php namespace Playground\Sandbox;

use System\Classes\PluginBase;
use System\Classes\SettingsManager;

class Plugin extends PluginBase
{

    /**
     * Register Settings
     *
     * @return array
     */
    public function registerSettings()
    {
        return [
            'settings' => [
                'label'       => 'playground.sandbox::lang.settings.label',
                'description' => 'playground.sandbox::lang.settings.description',
                'icon'        => 'icon-flask',
                'category'    => SettingsManager::CATEGORY_SYSTEM,
                'class'       => 'Playground\Sandbox\Models\Settings',
                'keywords'    => 'playground sandbox other keyswords',
            ]
        ];
    }
}

<?php namespace Playground\Sandbox;

use System\Classes\PluginBase;

use System\Classes\SettingsManager;

class Plugin extends PluginBase

{

/**

* Register Settings

* @return array

public function registerSettings()

{

return [

'settings' => [

'label' => 'playground.sandbox::lang.settings.label',

'description' => 'playground.sandbox::lang.settings.description',

'icon' => 'icon-flask',

'category' => SettingsManager::CATEGORY_SYSTEM,

'class' => 'Playground\Sandbox\Models\Settings',

'keywords' => 'playground sandbox other keyswords',

]

];

}

After that you must create a Settings.php file with the following content inside your models folder.

<?php namespace Playground\Sandbox\Models;

use Model;

/**
 * Class Settings
 * @package Playground\Sandbox\Models
 */
class Settings extends Model
{
    /**
     * @var array
     */
    public $implement = ['System.Behaviors.SettingsModel'];

    /**
     * @var string
     */
    public $settingsCode = 'playground_sandbox_settings';

    /**
     * @var string
     */
    public $settingsFields = 'fields.yaml';

    // Set defaults
    public function initSettingsData()
    {
        $this->enabled = 0;
        $this->api_key = '';
    }
}

<?php namespace Playground\Sandbox\Models;

use Model;

/**

* Class Settings

* @package Playground\Sandbox\Models

class Settings extends Model

{

/**

* @var array

public $implement = ['System.Behaviors.SettingsModel'];

/**

* @var string

public $settingsCode = 'playground_sandbox_settings';

/**

* @var string

public $settingsFields = 'fields.yaml';

// Set defaults

public function initSettingsData()

{

$this->enabled = 0;

$this->api_key = '';

}

If you define default values inside the method initSettingsData, make sure the above fields match with the definitions inside the fields.yaml file.

tabs:
    fields:
        enabled:
            label: playground.sandbox::lang.settings.enabled
            comment: playground.sandbox::lang.settings.enabled_comment
            tab: playground.sandbox::lang.settings.tab_default
            type: checkbox
        api_key:
            label: playground.sandbox::lang.settings.api_key
            comment: playground.sandbox::lang.settings.api_key_comment
            tab: playground.sandbox::lang.settings.tab_default
            type: text

tabs:

fields:

enabled:

label: playground.sandbox::lang.settings.enabled

comment: playground.sandbox::lang.settings.enabled_comment

tab: playground.sandbox::lang.settings.tab_default

type: checkbox

api_key:

label: playground.sandbox::lang.settings.api_key

comment: playground.sandbox::lang.settings.api_key_comment

tab: playground.sandbox::lang.settings.tab_default

type: text

Once the fields.yaml file is created, you should see a new form within the new tab.

Now you can access the settings values within your controller, console or component by implementing the following model.

use Playground\Sandbox\Models\Settings;

1	use Playground\Sandbox\Models\Settings;

For test purposes, I created a new controller and implemented the above model to get access to the API key.

<?php namespace Playground\Sandbox\Controllers;

use Illuminate\Routing\Controller;
use Playground\Sandbox\Models\Settings;

class Swing extends Controller
{
    /**
     * @var Plugin settings
     */
    protected $settings;

    /**
     * Sandbox constructor.
     */
    public function __construct()
    {
        $this->settings = Settings::instance();
    }

    /**
     * @param $params
     */
    public function index($params)
    {
        try {

            $enabled = $this->settings->enabled;

            if ($enabled) {
                
                // Use settings values
                var_dump($this->settings->api_key);
            }
        }

        catch (\Exception $ex) {
            $ex->getMessage();
        }
    }
}

<?php namespace Playground\Sandbox\Controllers;

use Illuminate\Routing\Controller;

use Playground\Sandbox\Models\Settings;

class Swing extends Controller

{

/**

* @var Plugin settings

protected $settings;

/**

* Sandbox constructor.

public function __construct()

{

$this->settings = Settings::instance();

}

/**

* @param $params

public function index($params)

{

try {

$enabled = $this->settings->enabled;

if ($enabled) {

// Use settings values

var_dump($this->settings->api_key);

}

catch (\Exception $ex) {

$ex->getMessage();

}

Here you go.

The entire source code can be found on https://github.com/tobias-forkel/october-cms-playground.