Puli is a new toolkit built on top of Composer that helps to manage and exchange resources like configuration files, images, CSS files, translation catalogs, and others. These are, you’ll agree, often difficult to maintain and share across projects.
Puli是在Composer之上构建的新工具包,可帮助管理和交换资源,例如配置文件,图像,CSS文件,翻译目录等。 您会同意,这些通常很难在项目之间进行维护和共享。
![Puli logo Puli logo](https://dab1nmslvvntp.cloudfront.net/wp-content/uploads/2015/09/1443698752puli-logo.png)
Puli provides a framework-agnostic solution to this problem, keeping track of every resource location and avoiding the problems of using absolute or relative paths inside different systems.
Puli为该问题提供了一个与框架无关的解决方案,可以跟踪每个资源的位置,并避免在不同系统内部使用绝对或相对路径的问题。
这个怎么运作 (How it works)
- You map resources via CLI. 您可以通过CLI映射资源。
A
puli.json
file keeps track of them.puli.json
文件会跟踪它们。You use a
ResourceRepository
instance to handle resources.您使用
ResourceRepository
实例来处理资源。
The Puli project also provides libraries for other functionalities like URL generation, or Twig support.
Puli项目还提供了用于其他功能的库,例如URL生成或Twig支持。
![Puli components Puli components](https://dab1nmslvvntp.cloudfront.net/wp-content/uploads/2015/10/1443699749puli-components.png)
安装Puli CLI (Install the Puli CLI)
To use Puli, first you need to install the Puli CLI. It’s recommended to install it as a phar, which can be done by downloading the latest release from GitHub.
要使用Puli,首先需要安装Puli CLI。 建议将其安装为phar,可以通过从GitHub下载最新版本来完成。
It can be placed in the /usr/local/bin
directory for global access.
可以将其放在/usr/local/bin
目录中以进行全局访问。
Below there are command line steps for a quick installation of the 1.0.0-beta7 pre-release in Unix-like systems:
以下是在类似Unix的系统中快速安装1.0.0-beta7预发行版的命令行步骤:
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
You can also install Puli as a Composer dependency in your project folder:
您也可以在项目文件夹中将Puli安装为Composer依赖项:
composer require --dev puli/cli:^1.0
or as a global Composer package with:
或作为具有以下内容的全局 Composer软件包:
composer global require puli/cli:^1.0`
Once you have installed the CLI, you can use Puli in a Symfony Project, in a PHP Application or a Composer package. You can find more information on your specific project’s type in the getting started guide.
一旦安装了CLI,就可以在Symfony项目,PHP应用程序或Composer软件包中使用Puli。 您可以在《 入门指南》中找到有关特定项目类型的更多信息。
项目布局 (Project layout)
It’s always recommended to have a neat directory project structure. The Puli docs reinforce this suggestion, adding a clear separation between the PHP code and the other non-PHP resources. Below is a recommended directory layout example:
始终建议您使用整洁的目录项目结构。 Puli文档加强了这一建议,在PHP代码和其他非PHP资源之间添加了清晰的分隔。 下面是一个推荐的目录布局示例:
![Puli recommended directory layout Puli recommended directory layout](https://dab1nmslvvntp.cloudfront.net/wp-content/uploads/2015/10/1443699859folders-layout.png)
映射资源 (Mapping resources)
Mapping single files or entire directories can be performed with the Puli map
command. For example, to map the res
directory’s content using myapp
as a resource name (Puli path), you can run:
可以使用Puli map
命令来映射单个文件或整个目录。 例如,要使用myapp
作为资源名称(Puli路径)来映射res
目录的内容,可以运行:
puli.phar map /myapp res
You will notice that the map is stored in the puli.json
file generated inside the project folder.
您会注意到该地图存储在项目文件夹内生成的puli.json
文件中。
It is now possible to reach all the mapped resources from PHP using the Puli path /myapp
.
现在可以使用Puli路径/myapp
从PHP获取所有映射的资源。
The Puli CLI offers other useful commands to manage the mappings. Some of the most used are:
Puli CLI提供了其他有用的命令来管理映射。 一些最常用的是:
ls
, to list all the resources.ls
,列出所有资源。tree
, to print the resource list tree.tree
,以打印资源列表树。find
, to find a resource with some filter criteria, (i.e.puli find --name *.css
will find all the.css
files).find
,以查找具有某些过滤条件的资源(即puli find --name *.css
将找到所有.css
文件)。map
with-u
or-d
arguments, to update/delete a map (ie:puli map -u myapp --add /new/folder
).map
与-u
或-d
参数,以更新/删除地图(即:puli map -u myapp --add /new/folder
)。
Another important feature is the ability to map resources in Composer packages. For example, to map the /view
directory inside a /vendor/author/packagename
directory you could use:
另一个重要功能是能够映射Composer软件包中的资源。 例如,要将/view
目录映射到/view
/vendor/author/packagename
目录中,可以使用:
puli map /somepulipath @author/packagename:view
实际例子 (Pratical example)
To show Puli in action, I have created an example project with Symfony: an image gallery. The demo displays all the images stored in an images_resource
folder.
为了展示Puli的实际效果,我使用Symfony创建了一个示例项目:一个图像库。 该演示显示了存储在images_resource
文件夹中的所有图像。
资产管理 (Asset management)
Before moving on, it’s worth pointing out a few things about the asset management:
在继续之前,值得指出有关资产管理的一些事项:
Symfony uses the
web
folder to store all the front controller files and the web assets (CSS, JS, images, other). Theweb
folder is, by default, the web application’s public access point. In other words, direct URL access to the other project directories is not possible.Symfony使用
web
文件夹存储所有前端控制器文件和Web资产(CSS,JS,图像等)。 默认情况下,web
文件夹是Web应用程序的公共访问点。 换句话说,无法直接URL访问其他项目目录。The demo project contains one
AppBundle
with its CSS and views stored insrc/AppBundle/Resources
.该演示项目包含一个
AppBundle
及其CSS和视图,这些视图和视图存储在src/AppBundle/Resources
。The Symfony asset management automatically copies every bundle’s resources into the public
web
folder.Symfony资产管理会自动将每个捆绑软件的资源复制到公共
web
文件夹中。
You will see how asset management with Puli is more flexible and provides extra configuration options.
您将看到使用Puli进行资产管理如何更加灵活并提供额外的配置选项。
演示安装 (Installation of the demo)
Check out the first version with:
签出第一个版本:
git clone -b 1.0 https://github.com/niklongstone/symfony-gallery-demo.git
then enter the project’s root directory and run: composer install
.
然后进入项目的根目录并运行: composer install
。
The Symfony console will ask you to configure some parameters, but you can just press enter to accept the default values.
Symfony控制台将要求您配置一些参数,但是您可以按Enter接受默认值。
The two important parameters are:
两个重要参数是:
images_resource
: the images folderimages_resource
:图片文件夹images_url
: the public images URLimages_url
:公共图像URL
Finally, in the project root, you can run app/console server:start
to run the server and see the app in the browser.
最后,您可以在项目根目录中运行app/console server:start
运行服务器并在浏览器中查看该应用程序。
![Sample gallery homepage Demo project home logo](https://dab1nmslvvntp.cloudfront.net/wp-content/uploads/2015/10/1443700259sample-homepage.png)
映射项目 (Mapping the project)
To map all the resources in the demo project Bundle you can run:
要映射演示项目捆绑包中的所有资源,可以运行:
puli.phar map /myapp/ src/AppBundle/Resources
With puli.phar tree
you will see something like:
使用puli.phar tree
您将看到类似以下内容:
![Puli tree Puli demo project tree](https://dab1nmslvvntp.cloudfront.net/wp-content/uploads/2015/10/1443700312puli-tree.jpg)
控制器 (The Controller)
To use the mapped view in the Controller, you can change the DefaultController
as follows:
要在Controller中使用映射视图,可以如下更改DefaultController
:
//old value: $this->template->render('AppBundle:Default:index.html.twig',
$this->template->render('/myapp/views/Default/index.html.twig',
You can reopen the project’s page to see that nothing has changed, because Puli perfectly called the mapped view.
您可以重新打开项目的页面以查看没有任何更改,因为Puli完美地调用了映射视图。
风景 (The View)
The next goal is to refactor the view using a Puli path for the CSS.
下一个目标是使用CSS的Puli路径重构视图。
You can publish the resources of /myapp/public
into the public folder of the demo project, the web
directory. Publishing is essentially copying or symlinking the resources over.
您可以将/myapp/public
的资源发布到演示项目的公共文件夹( web
目录)中。 发布本质上是在复制或符号链接资源。
Let’s do it step by step:
让我们逐步进行:
Create a server and link the public folder to it with:
创建服务器并将公用文件夹链接到:
puli.phar server --add localhost web
Register the Puli public path with:
在以下位置注册Puli公共路径:
puli.phar publish /myapp/public localhost /app
Install the resources with:
使用以下命令安装资源:
puli.phar publish --install
The command will create symlinks of the /myapp/public
elements into the /web/app
path.
该命令将/myapp/public
元素的符号链接创建到/web/app
路径中。
Now, it’s time to change the CSS path in the index.html.twig
as follows:
现在,是时候更改index.html.twig
CSS路径,如下所示:
<link href="{{ resource_url('/myapp/public/css/style.css') }}" rel="stylesheet">
At this point you can find all the progress you have made till now in the version 2.0 of the demo project:
此时,您可以在演示项目的2.0版中找到到目前为止所取得的所有进展:
git clone -b 2.0 https://github.com/niklongstone/symfony-gallery-demo.git
or
要么
git checkout 2.0
if you already have the demo.
如果您已经有演示。
Don’t forget to run composer install
in the project’s folder, then puli.phar publish --install
.
不要忘记在项目文件夹中运行composer install
,然后puli.phar publish --install
。
URL生成 (URL generation)
One of Puli’s advantages is to support different server resource locations. For example, if you want to move your resources to a different server like https://www.sitepoint.com/res/
you can run:
Puli的优点之一是支持不同的服务器资源位置。 例如,如果要将资源移动到其他服务器,例如https://www.sitepoint.com/res/
,则可以运行:
puli.phar server -u localhost --url-format https://www.sitepoint.com/res/%s
and every mapped URL will be updated automatically.
并且每个映射的URL都会自动更新。
Another use case can be creating a simple cache invalidation system, appending to the query string something like %s?v1
.
另一个用例是创建一个简单的缓存失效系统,在查询字符串后附加%s?v1
。
资源发现 (Resource discovery)
The demo project is quite flexible and allows us to change the images folder and URL. Puli provides a Discovery component which can add even more flexibility – for example in filtering specific resources.
该演示项目非常灵活,使我们可以更改images文件夹和URL。 埔里提供了一个发现组件,它可以增加更大的灵活性,例如在过滤特定资源时。
The Discovery component manages the connection between resource providers and resource consumers. In other words, it can connect resources with services that will use them.
发现组件管理资源提供者和资源使用者之间的连接。 换句话说,它可以将资源与将使用资源的服务连接起来。
In the example, the controller can be a resource consumer, and the image folder can be a resource provider. To handle a resource with the Discovery component, you first define a resource type, then link it to a resource path.
在该示例中,控制器可以是资源使用者,图像文件夹可以是资源提供者。 要使用发现组件处理资源,您首先要定义资源类型,然后将其链接到资源路径。
In the example, we will create an app/image
resource type linked to the web/images
folder with a filter to get only JPEG images.
在示例中,我们将使用过滤器创建链接到web/images
文件夹的app/image
资源类型,以仅获取JPEG图像。
First, we need to map the web/images
folder with:
首先,我们需要使用以下命令映射web/images
文件夹:
puli.phar map /myapp/images /web/images
then, you create a resource type:
然后,您创建一种资源类型:
puli.phar type --define mygallery/image
finally, you can bind the mapped folder with the jpg
query:
最后,您可以将映射的文件夹与jpg
查询绑定:
puli.phar bind /myapp/images/*.jpg mygallery/image
Now, you can refactor the DefaultController
as follows:
现在,您可以按以下方式重构DefaultController
:
// The constructor needs the puli Discovery component instead of the images folder
public function __construct(EngineInterface $template, KeyValueStoreDiscovery $puliDiscovery)
{
$this->template = $template;
$this->puliDiscovery = $puliDiscovery;
}
// [...]
private function getImages()
{
$images = array();
//the discovery component will find the bind type with the filter
$bindings = $this->puliDiscovery->findByType('mygallery/image');
//the loop gets the resources image names
foreach ($bindings as $binding) {
foreach ($binding->getResources() as $resource) {
$images[] = $resource->getName();
}
}
return $images;
}
The AppBundle/Resource/config/service.xml
might be:
AppBundle/Resource/config/service.xml
可能是:
services:
app.default_controller:
class: AppBundle\Controller\DefaultController
arguments:
- @templating
- @puli.discovery
If you reopen the homepage, you should notice that only .png
images are missing, as expected.
如果重新打开主页,则应注意,按预期,仅缺少.png
图像。
To see the final version of the demo project, check out version 3.0 and run composer install
and puli publish --install
to see the correct result.
要查看演示项目的最终版本,请签出版本3.0,然后运行composer install
和puli publish --install
以查看正确的结果。
The Discovery component was built mainly to connect Composer packages and make this integration easy. You can find more information on The Discovery Component official page.
Discovery组件的主要目的是连接Composer软件包并使此集成变得容易。 您可以在“发现组件”官方页面上找到更多信息。
最后的想法 (Final thoughts)
Puli solves a real problem about resource management. The CLI is easy to use, and the Composer connection is one of the strongpoints of the project. Thanks to the author and all the contributors, there will soon be a stable release; although the beta works quite well.
埔里解决了有关资源管理的实际问题。 CLI易于使用,并且Composer连接是该项目的强项之一。 感谢作者和所有贡献者,很快将发布一个稳定的版本; 尽管Beta的效果很好。
You can find more information about Puli in the official documentation and share your personal thoughts in the comments below.
您可以在官方文档中找到有关Puli的更多信息,并在下面的评论中分享您的个人想法。
翻译自: https://www.sitepoint.com/can-puliphp-re-revolutionize-php-package-development/