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:
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
In case of a global Composer package, the command has the following look:
composer globalrequire 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 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
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
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.
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.
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.
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:
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
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:
$php puli.phar publish--install
Installing/batman/blog/publicinto 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.
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.