Puli – The Post-Composer Epoch

- Fire development

Puli resource management

If you still haven’t heard about Puli, it is a new revolutionary toolkit designed to streamline the way developers manage and exchange various resources. Being built on top of Composer, Puli helps to maintain and share images, configuration files, translation catalogs, CSS files, and other resources across projects with the aid of a framework-agnostic platform. The toolkit keeps track of resource locations and does everything to avoid problems related to the usage of absolute or relative paths within various systems. Puli’s major goal is to replace “bundles”, “modules”, “plugins”, and other specialized packages of various frameworks with a universal solution.

There are three major principles on which the work of Puli is base. The first one is:

  • you take a CLI and map your resource within Puli.

The second principle is related to the resource tracking:

  • an appropriate puli.json file is used for keeping track of them.

The third principle is about resource handling:

  • a ResourceRepository instance is leveraged to handle them.

As for the generation of URLs, support for Twig, and other functionalities, they are provided via appropriate libraries. The following image illustrates Puli components:

Puli resource management

Puli: PHP’s Next Package Revolution

Puli resource management from the perspective of PHP is described in the following video.

How to install the Puli CLI

Please note that you can use Puli within your projects only after you’ve installed the Puli CLI. Therefore, below we will shed light on its installation.

Install the Puli CLI as a phar:

  • Go to the Puli CLI on GitHub

  • Find the latest available version.

  • Place it in the /usr/local/bin directory. Thus, you will provide global access.

A quick installation in Unix-like systems (in the following example we deal with the 1.0.0-beta7 pre-release) looks as follows:

If you are wondering, how to install Puli as a Composer dependency, it is a quite simple procedure:

In case of a global Composer package, the command has the following look:

Congratulations! Now, you can use Puli in your PHP Application, Symfony Project, or Composer package.

Puli project layout

It is also necessary to mention that Puli provides the ability to implement an accurate directory project structure, since it separates the PHP code and keeps it apart from non-PHP resources. The following image illustrates an example of a proper directory layout:

Puli resource management

Puli resource access

Puli provides the ability to access non-PHP files, such as XML, HTML, CSS, images, and others, from a Puli package via a naming convention or so called Puli paths. The following code describes the aforementioned approach:

Each path is resolved after reading path mappings available in puli.json files related to Puli packages.

Puli resource mapping

Use the Puli map command to map single files or entire directories. The following command illustrates, how to map the res directory’s content:

where myapp is a Puli path (resource name).

As for the map, it is stored in the puli.json file. In its turn the file is generated within the project folder. All mapped resources can be reached from PHP via /myapp (Puli path). Other important commands utilized for Puli resource mapping are:

  • ls. All resources can be listed via this Puli command.

  • tree. The command is used for printing the resource list tree.

  • find. The command is designed to find a resource with a filter criteria.

  • map. This one is used with -u or -d arguments in order to update or delete a map.

As for Puli resource mapping in Composer packages, it is possible with the following command:

where you are going to map the/view directory within a /vendor/author/packagename directory.

Puli Discovery

Consumers and providers are two roles available for Puli packages in case of resources and PHP classes. For instance, there is a translator package which acts as a consumer. This package may request translation files from other packages which act as providers.

Puli resource management

Consumers provide resources they want to load with a name. On the picture above, it is “thor/translations”. Such name is dubbed a binding type.

As for the resource providers, they assign their translation files to this type. The process is dubbed binding.

As a user of both packages, you only should pass Puli’s Discovery (further information on Puli’s discovery) to the Translator class:

Finally, the translator takes all bound translation files and loads them from the discovery. No further configuration is required.

Puli package overrides

Another important feature of Puli and its packages is the ability to override other packages. For instance, you can easily replace the style.css file with your app or a specialized theme package. In case of a generic package “batman/blog”, the command looks as follows:

Puli resource URLs

It is also necessary to mention that Puli not only publishes CSS, JavaScript, and image files bundled in packages, but it generates their public URLs as well. It is possible to pass Puli paths to simple utility functions for generating URLs in both PHP or HTML code:

To mark Puli paths public, use the Puli CLI and the following command:

where the /batman/blog/public directory is published to the /blog/ subdirectory of the server “localhost”.

Now, it is necessary to define the server. Use the Puli CLI once again:

The command registers the server “localhost” with the directory public_html. As for the directory itself, it acts as a document root. Now, there is enough information available for  generating URLs:

Puli Resource Installation

Below, we describe, how to use Puli for installing public resources on a server. In a situation when the server is your localhost, the tool generates file copies or simple symbolic links in a document root:

Please note that this functionality will be removed in the final Puli release. Instead, it will be available in plugins for Brunch, Gulp, or similar tools.

Puli vs Composer

If you are not satisfied with the work of Composer, you should pay attention to Puli. If you think that there is no need to use it along with Composer, check this  presentation, since it describes the following facts:

  • your development with Puli is more efficient than with Composer;
  • Puli requires minimum effort to install packages;
  • Puli is framework agnostic and use high-level packages across frameworks;
  • Resource URLs generation with Puli is a piece of cake;
  • Puli provides literally no impact on performance;
  • Puli supports such features as Resource Installation as well as Class and Resource Discovery.


Although Puli introduces a revolutionary approach to resource management and solves a bunch of problems related to this development niche, it will never replace Composer. Composer installs packages and manages their dependencies. So once those packages are installed, Puli can be used to connect those packages or load resources or classes from the packages. Thus, Puli is tightly connected to a good old tool, but introduces much wider opportunities. Here at Firebear, we are looking forward to seeing the first stable release of Puli which will start the post-Composer epoch.

Useful Links