Puli 1.0 Beta Released

Today marks the end of a month of very intense development of the Puli library. On December 3rd, 2014 the first alpha version of most of the Puli components and extensions was released. Today, a little more than a month later, I am proud to present to you the first beta release of all the libraries in the Puli ecosystem!

What is Puli?

Update : This post is partially obsolete. Please check the Puli website for up-to date information about Puli.

If you missed my previous blog post, you are probably wondering what this Puli thing is. In short, Puli (pronounced "poo-lee") is a toolkit which lets you map paths of a virtual resource repository to paths in your Composer package. For example, as the developer of the "acme/blog" package, I can map the path "/acme/blog" to the res directory in my package:

$ puli map /acme/blog res

After running this command, I can access all the files in my res directory through the Puli path "/acme/blog". For example, if I'm using Puli's Twig extension:

// res/views/post.html.twig
echo $twig->render('/acme/blog/views/post.html.twig');

But not only I can do this. Every developer using my package can do the same. And I can use the Puli paths of every other package. Basically, Puli is like PSR-4 autoloading for anything that's not PHP.

You should read the Overview page in the documentation to learn more about Puli's exciting possibilities.

The Puli Components

Puli consists of a few core components that implement Puli's basic functionality. First, let's talk about the components that you are most likely to integrate into your applications and libraries:

  • The Repository Component implements a PHP API for the persistent storage of arbitrary resources in a resource repository:

    use Puli\Repository\FilesystemRepository;
    use Puli\Repository\Resource\DirectoryResource;
    
    $repo = new FilesystemRepository();
    $repo->add('/config', new DirectoryResource('/path/to/resources/config'));
    
    // /path/to/resources/config/routing.yml
    echo $repo->get('/config/routing.yml')->getBody();
    
  • The Discovery Component allows you to define binding types and let other packages bind resources to these types. Read the Resource Discovery guide in the documentation to learn more about this topic.

  • The Factory Component contains a single interface PuliFactory. This interface creates repositories and discoveries for you. You can either implement the interface manually, or – and that's what you usually do – let Puli generate one for you.

Next come the components that you use as a developer in your daily life:

  • The Command Line Interface (CLI) lets you map repository paths, browse the repository, define binding types and bindings and much more by typing a few simple commands in your terminal. The CLI also builds a factory that you can use to load the repository and the discovery in your code:

    $factoryClass = PULI_FACTORY_CLASS;
    $factory = new $factoryClass();
    
    // If you need the resource repository
    $repo = $factory->createRepository();
    
    // If you need the resource discovery
    $discovery = $factory->createDiscovery($repo);
    

    The configuration that you pass to the CLI is stored in a puli.json file in the root of your Composer package. This file should be distributed with your package.

  • The Composer Plugin loads the puli.json files of all installed Composer packages. Through the plugin, you can access any of the resources and bindings that come with any of the libraries you use.

  • The Repository Manager implements the actual business logic behind the CLI and the Composer Plugin. This is Puli's workhorse.

The Puli Extensions

Currently, Puli features a few extensions that are mostly targeted at the Symfony ecosystem, because – quite simply – that's the framework I know best. As soon as the first stable release of Puli is out, I would like to work on extensions for other PHP frameworks, but I could need your help with that.

The following extensions are currently available:

Supporting Libraries

During Puli's development, I created a few small supporting libraries that I couldn't find in the high quality that I needed to build a solid foundation for Puli. These libraries also had their release today:

  • webmozart/path-util provides robust, cross-platform utility functions for normalizing and transforming filesystem paths. After using it for a few months, I love its simplicity already. I highly recommend to give it a try.

  • webmozart/key-value-store provides a simple yet robust KeyValueStore interface with implementations for various backends.

  • webmozart/json is a wrapper for json_encode()/json_decode() that normalizes their behavior across PHP versions and features integrated JSON Schema validation.

  • webmozart/glob implements Git-like globbing in that wildcards ("*") match both characters and directory separators. I was made aware today that a similar utility seems to exist in the Symfony Finder component, so I'll look about merging the two packages.

Road Map

I would like to release a stable version of the fundamental Repository, Discovery and Factory components by the end of January 2015. These components are quite stable already and I don't expect any serious changes.

The CLI, Composer Plugin and Repository Manager are a bit more complex. They have undergone heavy changes during the last weeks. All the functionality that is planned for the final release is implemented now, but the components need testing and polishing. I plan to release a final version of these packages in February or March 2015.

Feedback Wanted

To permit a successful stable release, I need your feedback! Please integrate Puli, test it and use it. However – as with any beta version – please don't use it in production.

Read the installation guide to get started. Happy coding! :)

Please leave me your feedback below. Follow PuliPHP on Twitter to receive all the latest news about Puli.

Discussion