Permalink
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
184 lines (123 sloc) 5.06 KB

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