Puli 1.0-beta10 Released

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

  • Added resource versioning.
  • Added improved JsonRepository and OptimizedJsonRepository classes.
  • Added JsonDiscovery class.
  • Fixed PHP 7 compatibility.
  • Fixed Symfony 3 compatibility.
  • Fixed installation and upgrading on PHP < 5.6.

Continue reading to learn more about these changes.

Resource Versioning

Puli packages may override the resources shipped in other packages. Assume that you created a package acme/blog that contains the file res/config.yml. Assume further that you want to customize the config.yml file in your application acme/app. You could solve this by adding the following puli.json to those projects:


    "version": "1.0",
    "name": "acme/blog",
    "path-mappings": {
        "/acme/blog": "res"


    "version": "1.0",
    "name": "acme/app",
    "path-mappings": {
        "/acme/app": "res"
        "/acme/blog/config.yml": "res/config/blog-config.yml"
    "override": ["acme/blog"]

The second file contains two very important entries:

  1. We told Puli to look for /acme/blog/config.yml in our own file: res/config/blog-config.yml
  2. We told Puli to prefer acme/app over acme/blog by adding that package to the override key.

Unfortunately you have to copy the complete original config.yml to the application, even if you just want to change a single entry. Wouldn't it be much nicer if we could merge the original and the customized file?

As of Puli 1.0-beta10, this is possible. You can access the different versions of a resource with ResourceRepository::getVersions():

$versions = $repo->getVersions('/acme/blog/config.yml');

// vendor/acme/blog/res/config.yml
$original = $versions->getFirst()->getBody();

// res/config/blog-config.yml
$custom = $versions->getCurrent()->getBody();

// TODO: merge $original and $custom

Versioning gives you a very flexible tool for building modular frameworks.

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, use the Puli installer to download the PHAR:

$ curl https://puli.io/installer | php

Upgrading Your Packages

To upgrade a Puli package, update your Composer dependencies:

$ rm -rf .puli && composer update

As shown in this example, you need to delete the .puli directory before updating your dependencies. Alternatively, you can run composer update twice (once with an exception, the second time without) which has the same effect.


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.