It's helpful to understand how Composer works and how to best utilize the environment as you implement your PSR-0 Namespace. There are factors that you, where you, as a user of the environment, will not be able to change and you should be aware of those points. There are areas where your choices directly impact the folder path and the implementation of your namespace.
##1. Composer Name Parameter##
The first data relevant to the package install path is the name you provide to Composer.
###What is the purpose of the name parameter?###
Composer requires a two-part, lowercase name that serves as a unique key for installing the package.
This two-part name represents the vendor name and the package name.
You enter these values into the name parameter of your package composer.json file.
In many cases, the same value is used for vendor name and package name.
These values are used as a key to locate a package in the package repository. (Most use Packagist for this purposes and match the name entered there.)
###Install path and folders###
Composer uses the literal vendor and the two-part name to begin the install path to your package.
vendor/vendor-name/package-name
###Examples###
vendor/molajo/filters
vendor/monolog/monolog
vendor/symphony/http-foundation
###Relevance to Namespacing###
Since the Composer name is required in lowercase, it is unlikely that you will find it is useful as a node in your package namespace.
If you enter the same value for Vendor name as Package name, that value will still be used two times in the install path.
It is important to remember that the purpose of this data is to enable Composer to use it as a key to locate and install packages.
##2. Composer target_dir parameter##
Next, Composer uses the value entered as target-dir to extend the path and folder structure.
A folder is created for each node in the target-dir value.
vendor/vendor-name/package-name/Values/Provided/In/Target/Dir
###Example:###
vendor/symphony/http-foundation/Symfony/Component/HttpFoundation
###Relevance to Namespacing###
If your package folder structure does not contain the beginning of your namespace, you can use target-dir to add nodes needed to implement your namespace.
If your package folder structure contains the entirety of your namespace (or if you were able to reuse the lowercase Composer name as the start of your namespace), you do not need to provide a value for target-dir.
##3. Your Package Repository##
Finally, Composer copies in the folders and files from your package repository at the current location of the install path.
If you did not specify a target_dir, that location begins:
vendor/vendor-name/package-name/
If you specified a target_dir, that location begins:
vendor/vendor-name/package-name/Values/Provided/In/Target/Dir/
###Install Path Examples with Package Folder Inclusion### Each folder in your repository becomes a folder and part of the install path. If your package repository looks like this:
doc
etc
src
Packagename
Folder1
Folder2
Folder3
Class1
tests
etc
Path to Class1 if you did not specify a target_dir, that location begins:
vendor/vendor-name/package-name/src/Packagename/Folder3/Class1
Path to Class1 if you did specify a target_dir, that location begins:
vendor/vendor-name/package-name/Values/Provided/In/Target/Dir/Packagename/Folder3/Class1
###Namespace Implications### Given good knowledge of the facts above, consider the best way to implement your namespace. There are techniques to minimize the folder structure, if such is a concern. There are ways to organize collections for those vendors with many packages. Just under, your package folder structure, as it is, will be used in the install path.
##Conclusion## It is a good idea to take time to think through the implications of how Composer works, how your package repository can be structured, and the impact of that software and those decisions on the implementation of the PSR-0 namespace.
###Advice to achieve the minimum install path, possible
- Leverage the Composer name key, if you can use lowercase nodes in your namespace.
- If you cannot do that, specify the Vendorname/Packagename (or, just "Vendorname", if appropriate) using the Composer target_dir parameter -or- the highest level(s) of your package repository folder structure.
- Do not add folders to the "top" of your package repository that are not a part of your namespace.
- Remember, your entire repository is distributed; include only those files you wish to distribute.
For vendors with multiple packages, the minimum package install path can look like:
vendor/vendorname/packagename/VendorName/PackageName/Class
For vendors with a single package, the minimum package install path can look like:
vendor/vendorname/packagename/VendorName/Class
Bear in mind, this could be confusing, perhaps even frustrating, at first. It's not a perfect situation and there are little things that would be nice if they were possible, like:
- If the Composer name values were allowed in mixed case and then could be used as part of the namespace;
- If Composer did not use the same value for name twice in the path;
- If Composer were able to install a package from a subfolder.
But, as is true with our own software, incremental improvements, code in hand, people willing to help solve problems, etc., is the way the things advance. Patience is always appreciated.
In the broader scheme of things, Composer and PSR-0 are ushering in a level of coordination that is quite remarkable and it is good that your work will now be a part.
Just a suggestion Amy (and thanks for doing this). It might be worth documenting the source code snippets that "got me into trouble" (under the "Relevance to Namespacing" headings?).
I'm also at the point of trying to work out the best strategy for organising the application that actually uses all the vendor code, but maybe that's for another thread.