dflydev/psr0-resource-locator

dev-master / 1.0.x-dev 2014-07-16 21:18 UTC

README

Locate resources by namespaceish paths using PSR-0 mappings.

Locating resources relative to a class within the same package can be done by __DIR__.'/../Resources. The downside to this method is that it only works if the target resources are in the same package.

This project aims to allow for locating resources from any namespace whether the intended directory is in the same package or not.

The term namespaceish is used instead of namespace as it should be understood that we are overloading the PSR-0 conventions to find files and not PHP code. In fact, we may often be looking for directories under a namespace that are in fact not namespaces at all.

Requirements

Installation

This library can installed by Composer.

Usage

The following is an example using the Composer PSR-0 Resource Locator implementation (dflydev/psr0-resource-locator-composer):

<?php

use Dflydev\Psr0ResourceLocator\Composer\ComposerResourceLocator;

$resourceLocator = new ComposerResourceLocator;

// Search all PSR-0 namespaces registered by Composer
// to find the first directory found looking like:
// "/Vendor/Project/Resources/mappings"
$mappingDirectory = $resourceLocator->findFirstDirectory(
    'Vendor\Project\Resources\mappings'
);

// Search all PSR-0 namespaces registered by Composer
// to find all templates directories looking like:
// "/Vendor/Project/Resources/templates"
$templateDirs = $resourceLocator->findDirectories(
    'Vendor\Project\Resources\templates',
);

The use of Resources in these examples is not meant to imply that only /Resources/ paths can be found. Implementations should be capable of finding any directory/directories as long as they follow PSR-0 naming guidelines and the mapping was registered.

Gotchas

Keep in mind a few rules:

  • Only resources that actually exist will be returned.
  • The order in which namespaces are checked will be determined by the underlying implementation. However, it is recommended that implementations search more specific namespace prefixes first. That is, Foo\Bar\Baz should be checked before Foo\Bar if both are registered.

Know Implementations

Composer — dflydev/psr0-resource-locator-composer

The Composer PSR-0 Resource Locator implementation leverages dflydev/composer-autoload to locate the effective Composer autoloader in use at runtime and accesses its namespace map.

For any project that uses Composer this is the implementation you are looking for.

Implementation Guidelines

Ensure that more specific namespace prefixes are searched first. That is, Foo\Bar\Baz should be checked before Foo\Bar if both are registered.

License

MIT, see LICENSE.

Community

If you have questions or want to help out, join us in the #dflydev channel on irc.freenode.net.

Not Invented Here

Based on the classpath: concept from Spring Framework.