Puli 1.0-beta8 Released

Today marks the release of Puli 1.0-beta8. This version features the following changes:

  • Support for discovering PHP classes in Puli packages.
  • Support for loading bindings that match dynamic expressions.
  • Full Windows support.
  • Support for migrating puli.json automatically.
  • Fixed various bugs in the path-mapping repository.

Continue reading to learn more about these changes.

Class Discovery

Puli's Discovery component was extended to discover not just resources, but also PHP classes in your Puli packages. A classic example where this feature is needed is a plugin system. As example, consider a batman/core package that provides an Application class and a Plugin interface for hooking plugins into that application. The Application class is used like this:

use Batman\Core\Application;

// load Composer's autoloader
require_once __DIR__.'/vendor/autoload.php';

// create the application
$app = new Application([
    new BlogPlugin(),
    new CommentsPlugin(),
    // ...
]);

Whenever you install a new plugin, you need to add the corresponding Plugin class to the application. With this Puli release, you can automate that.

Implementing the Plugin Infrastructure

In the batman/core package, add a binding type for the Plugin interface to puli.json:

$ puli type --define Batman\\Core\\Plugin

Change the Application class to load the plugins from Puli's Discovery:

namespace Batman\Core;

use Puli\Discovery\Api\Discovery;

class Application
{
    public function __construct(Discovery $discovery)
    {
        foreach ($discovery->findBindings(Plugin::class) as $binding) {
            $pluginClass = $binding->getClassName();

            $this->registerPlugin(new $pluginClass());
        }
    }
}

Any plugin can now bind its plugin class to the binding type Batman\Core\Plugin defined in the batman/core package.

Registering a Plugin

As example, let's register the BlogPlugin class in the puli.json file of the batman/blog package:

$ puli bind Batman\\Blog\\BlogPlugin Batman\\Core\\Plugin

Using the Application

Users of your packages now instantiate the application like this:

use Batman\Core\Application;

// load Composer's autoloader
require_once __DIR__.'/vendor/autoload.php';

// load Puli's Discovery service
$factoryClass = PULI_FACTORY_CLASS;
$factory = new $factoryClass();
$repo = $factory->createRepository();
$discovery = $factory->createDiscovery($repo);

// create the application
$app = new Application($discovery);

Any installed plugin will be recognized and loaded automatically.

Use Expressions to Load Bindings

The Discovery component now uses the Webmozart Expression library to load bindings that match specific criteria. For example, let's load all bindings for the thor/message-catalog binding type that have the parameter domain set to admin:

use Webmozart\Expression\Expr;

$expr = Expr::method('getParameterValue', 'domain', Expr::same('admin'));
$bindings = $discovery->findBindings('thor/message-catalog', $expr); 

Another example: Let's load all classes bound to the Plugin binding type that are located in the Webmozart\ namespace:

use Webmozart\Expression\Expr;

$expr = Expr::method('getClassName', Expr::startsWith('Webmozart\\'));
$bindings = $discovery->findBindings(Plugin::class, $expr); 

Windows Compatibility

All Puli repositories are now continuously tested on Windows thanks to AppVeyor. This change helped us to spot and fix various Windows issues. As of today, all Puli repositories build successfully on Windows.

JSON Migrations

In the past, you had to manually adapt your puli.json files when upgrading to a new beta release where the structure of that file had changed. As of this release, there is a puli upgrade command that upgrades your puli.json automatically:

$ puli upgrade

This will help us to improve the format of that file in future releases.

How to Upgrade

Upgrading the CLI

To upgrade the puli command line utility, run the self-update command:

$ puli self-update

This command requires PHP 5.6 or higher to work. If you have a lower PHP version, download the latest PHAR manually and replace the one you have installed.

Upgrading Your Packages

To upgrade a Puli package, simply run composer update to get the latest versions.

If the update fails, try to run it again. If it still fails, delete the file .puli/GeneratedPuliFactory.php and run it again. If you still have problems, head over to Puli's Gitter chat or report your problem on Puli's issue tracker.

Feedback

Leave feedback about this release in the comments below. Please report any bugs or issues that you find on Puli's issue tracker. If you have questions, join Puli's Gitter chat.

Read the documentation to learn more about Puli. Please note that the documentation is currently being adapted to the new release.

Discussion