Mapping Resources¶
Puli paths can be mapped to files or directories with the map
command of
the Puli CLI:
$ php puli.phar map /acme/blog res
The first argument is a path prefix, followed by one or more paths in your
project. By convention, the path prefix should equal the name of your Composer
package with an additional leading slash (“/”). The resulting path mapping is
added to the puli.json
file of your package.
Tip
If you develop an application that is not used as Composer dependency by
other packages, use /app
as path prefix.
You cannot just map directories, but also individual files. This is helpful if you need to cherry-pick files from specific locations:
$ php puli.phar map /acme/blog/css/reset.css shared/reset.css
Listing Mappings¶
The current path mappings can be displayed by calling the map
command
without arguments:
$ php puli.phar map
The following path mappings are currently enabled:
Package: puli/acme-blog
Puli Path Real Path(s)
/acme/blog res
The path displays all path mappings currently found in your project. If you
want to display just the path mappings of your own package (the root package),
pass the --root
option. If you want to display just the path mappings of a
package with a specific name, use the --package
option. With map -h
, you
can learn more about the map
command:
$ php puli.phar map -h
Listing Mapped Files¶
Now that we mapped paths to the repository, it would be nice to know which
resources the repository actually contains. You can use ls
– just like
the ls
command on UNIX – to list the resources in the repository:
$ php puli.phar ls
acme
$ php puli.phar ls /acme/blog/config
config.yml config-dev.yml doctrine
You can also print the resources as tree with tree
:
$ php puli.phar tree
/
├── acme
│ └── blog
│ └── config
│ └── ...
└── app
└── ...
This command prints the whole repository by default. You can also pass the Puli path of an individual resource if you want to print just a part of the repository:
$ php puli.phar tree /acme/blog/config
/acme/blog/config
├── config.yml
├── config-dev.yml
├── doctrine
│ ├── Acme.Blog.Post.dcm.xml
│ └── ...
└── ...
At last, use find
to list resources according to different criteria:
$ php puli.phar find --name *.yml
FileResource /acme/blog/config/config.yml
FileResource /acme/blog/config/config-dev.yml
Pass -h
to find out more about each command’s arguments and options:
$ php puli.phar find -h
Changing a Mapping¶
You can add paths to a path mapping with the map -u
(or --update
)
command:
$ php puli.phar map -u /acme/blog --add assets
$ php puli.phar map
The following path mappings are currently enabled:
Package: puli/acme-blog
Puli Path Real Path(s)
/acme/blog res, assets
When a path mapping contains multiple files or directories, later mappings
override earlier mappings. That means, the file /acme/blog/css/style.css
will be looked for first in assets/css/style.css
, then in
res/css/style.css
.
Likewise, paths can be removed from a path mapping with the --remove
option:
$ php puli.phar map -u /acme/blog --remove assets
$ php puli.phar map
The following path mappings are currently enabled:
Package: puli/acme-blog
Puli Path Real Path(s)
/acme/blog res
Deleting a Mapping¶
Path mappings can be removed completely with map -d
(or --delete
):
$ php puli.phar map -d /acme/blog
Referencing Other Packages¶
Sometimes it is necessary to map path prefixes to files or directories in other
Composer packages. A typical use case is when you use packages that don’t
contain a puli.json
file.
Use the prefix @<vendor/package>:
to reference the install path of another
package:
$ php puli.phar map /acme/theme @acme/theme:res
The example above maps the Puli path /acme/theme
to the res
directory of
the “acme/theme” package.
Further Reading¶
- Read Working with Resources to learn how to use the resources returned by the resource repository.