empress/updater

Providing auto-updating for your self-hosted Empress application.

v1.0.3 2017-05-23 19:57 UTC

README

This package provides some basic methods to implement self updating for your Empress application. Already bundled are some methods to provide a self-update mechanism via Github.

Usually you need this when distributing a self-hosted Empress application that needs some updating mechanism, as you do not want to bother your lovely users with Git and/or Composer commands ;-)

Install with Composer

There are currently two branches:

  • master: Compatible with PHP 7.x
  • 5.x: Compatible with PHP 5.5 + 5.6

Please select the right branch for your PHP version accordingly.

To install the latest version from the master using Composer:

$ composer require empress/updater

This adds the empress/updater package to your composer.json and downloads the package.

You need to include the service provider in your config/app.php [1] and optionally the facade [2]:

// config/app.php

return [

    //...
    
    'providers' => [
        // ...
        
        Empress\Updater\UpdaterServiceProvider::class, // [1]
    ],
    
    // ...
    
    'aliases' => [
        // ...
        
        'Updater' => Empress\Updater\UpdaterManager::class, // [2]

]

Additionally add the listener to your app/Providers/EventServiceProvider.php:

// app/Providers/EventServiceProvider.php

/**
 * The event handler mappings for the application.
 *
 * @var array
 */
protected $listen = [
    // ...
    
    \Empress\Updater\Events\UpdateAvailable::class => [
        \Empress\Updater\Listeners\SendUpdateAvailableNotification::class
    ],
    \Empress\Updater\Events\UpdateSucceeded::class => [
        \Empress\Updater\Listeners\SendUpdateSucceededNotification::class
    ],

];

Configuration

After installing the package you need to publish the configuration file via

$ php artisan vendor:publish --provider="Empress\Updater\UpdaterServiceProvider"

Note: Please enter correct value for vendor and repository name in your config/self-updater.php if you want to use Github as source for your updates.

Running artisan commands

Artisan commands can be run before or after the update process and can be configured in config/self-updater.php:

Example:

'artisan_commands' => [
    'pre_update' => [
        'updater:prepare' => [
            'class' => \Empress\Console\Commands\PreUpdateTasks::class,
            'params' => []
        ],
    ],
    'post_update' => [
        'postupdate:cleanup' => [
            'class' => \Empress\Console\Commands\PostUpdateCleanup::class,
            'params' => [
                'log' => 1,
                'reset' => false,
                // etc.
            ]
        ]
    ]
]

Notifications via email

You need to specify a recipient email address and a recipient name to receive update available notifications. You can specify these values by adding EMPRESS_UPDATER_MAILTO_NAME and EMPRESS_UPDATER_MAILTO_ADDRESS to your .env file.

Config name Description
EMPRESS_UPDATER_MAILTO_NAME Name of email recipient
EMPRESS_UPDATER_MAILTO_ADDRESS Address of email recipient
EMPRESS_UPDATER_MAILTO_UPDATE_AVAILABLE_SUBJECT Subject of update available email
EMPRESS_UPDATER_MAILTO_UPDATE_SUCCEEDED_SUBJECT Subject of update succeeded email

Usage

To start an update process, i. e. in a controller, just use:

public function update()
{
    // This downloads and install the latest version of your repo
    Updater::update();
    
    // Just download the source and do the actual update elsewhere
    Updater::fetch();
    
    // Check if a new version is available and pass current version
    Updater::isNewVersionAvailable('1.2');
}

Of course you can inject the updater via method injection:

public function update(UpdaterManager $updater)
{

    $updater->update(); // Same as above
    
    // .. and shorthand for this:
    $updater->source()->update;
    
    $updater->fetch() // Same as above...
}

Note: Currently the fetching of the source is a synchronous process. It is not run in background.

Using Github

The package comes with a Github source repository type to fetch releases from Github - basically use Github to pull the latest version of your software.

Just make sure you set the proper repository in your config/self-updater.php file.

Extending and adding new source repository types

You want to pull your new versions from elsewhere? Feel free to create your own source repository type somewhere but keep in mind for the new source repository type:

  • It needs to extend AbstractRepositoryType
  • It needs to implement SourceRepositoryTypeContract

So the perfect class head looks like

class BitbucketRepositoryType extends AbstractRepositoryType implements SourceRepositoryTypeContract

Afterwards you may create your own service provider, i. e. BitbucketUpdaterServiceProvider, with your boot method like so:

public function boot()
{
    Updater::extend('bitbucket', function($app) {
        return Updater::sourceRepository(new BitbucketRepositoryType);
    });
}

Now you call your own update source with:

public function update(UpdaterManager $updater)
{
    $updater->source('bitbucket')->update();
}

Licence

The MIT License (MIT). Please see Licencse file for more information.