Puli – The Post-Composer Epoch

December 25, 2015 - 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

Table of contents

1 Puli: PHP’s Next Package Revolution
2 How to install the Puli CLI
3 Puli project layout
4 Puli resource access
5 Puli resource mapping
6 Puli Discovery
7 Puli package overrides
8 Puli resource URLs
9 Puli Resource Installation
10 Puli vs Composer
11 Conclusion
12 Useful Links

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:

wget https://github.com/puli/cli/releases/download/1.0.0-beta7/puli.phar
chmod 755 puli.phar
sudo mv puli.phar /usr/local/bin

wget https://github.com/puli/cli/releases/download/1.0.0-beta7/puli.phar

chmod 755 puli.phar

sudo mv puli.phar /usr/local/bin

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

composer require --dev puli/cli:^1.0

1	composer require --dev puli/cli:^1.0

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

composer global require puli/cli:^1.0`

1	composer global require puli/cli:^1.0`

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:

// views/index.html.twig in the "batman/blog" package
echo $twig->render('/batman/blog/views/index.html.twig');

1 2	// views/index.html.twig in the "batman/blog" package echo $twig->render('/batman/blog/views/index.html.twig');

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:

puli.phar map /myapp res

1	puli.phar map /myapp res

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:

puli map /somepulipath @author/packagename:view

1	puli map /somepulipath @author/packagename:view

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:

$translator = new Translator($discovery);

1	$translator = new Translator($discovery);

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:

$ php puli.phar map /batman/blog/css/style.css res/css/blog/style.css

1	$ php puli.phar map /batman/blog/css/style.css res/css/blog/style.css

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:

<img src="{{ resource_url('/batman/blog/public/logo.png') }}" />

1	<img src="{{ resource_url('/batman/blog/public/logo.png') }}" />

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

$ php puli.phar publish /batman/blog/public localhost /blog/

1	$ php puli.phar publish /batman/blog/public localhost /blog/

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:

$ php puli.phar server --add localhost public_html

1	$ php puli.phar server --add localhost public_html

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:

<img src="/blog/logo.png" />

1	<img src="/blog/logo.png" />

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:

$ php puli.phar publish --install
Installing /batman/blog/public into public_html/blog via symlink...

1 2	$ php puli.phar publish --install Installing /batman/blog/public into public_html/blog via symlink...

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.

Conclusion

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.