README

A simple PHP function which takes the path to a PHP source file as an argument and returns the namespace of that file as a string.

Background

Due to PHP's dynamic nature, it can be useful, depending on your use case, to store a source file's namespace in a string for later use. While you can do this by simply returning the __NAMESPACE__ magical constant in the included file, you can't always rely on this, especially for external libraries. Moreover, you might need to obtain the file's namespace before including it in your code. In these cases, and possibly even more that I haven't thought of, this function comes in handy.

How to Include in your Projects

There are two ways to include this file: either as a Composer library, or including it manually.

Composer Library

All you need to do to include this library using Composer is require it. You can do this by adding the following to your composer.json file:

"require": {
	"chaos-designer/get-file-namespace": "1.0.*"
}

Alternatively, you can run the following command on your project's root directory:

composer require chaos-designer/get-file-namespace

Once you've done either of these things, all you need to do is include the Composer autoloader script in your project:

include "/vendor/autoloader.php";

You can also include the main library file directly, if you wish (the method above will automatically include all your other libraries, however):

include "/vendor/chaos-designer/get-file-namespace/src/main.php";

In either case, you can use include_once, require or require_once instead of include, depending on your needs.

Manual Method

In order to manually include this library, simply place main.php anywhere in your project's directory tree (you can, and probably should, rename it), then include it wherever you need it:

include "path/to/main.php";

If you renamed the file, remember to change main.php above with whatever name you chose. Also, just like before, you may use include_once, require or require_once instead of include.

Do note that, if you manually include the file, you also need to include the license notice (contained in LICENSE on the root of this repository). To know more about this, please read the notice.

How to Use

Once you have imported the library through either method above, all you need to do is call the function, like this:

$str = ChaosDesigner\GetFileNamespace\getFileNamespace("path/to/file/to/extract/namespace/from.php");

If you're going to call the function multiple times, it would probably be a good idea to import it so you don't have to type the long string above every time:

use function ChaosDesigner\GetFileNamespace\getFileNamespace;

You can also alias it by adding as someName before the semicolon above to make the name even shorter. Once you've done this, you can call the function by simply typing its name, or whichever alias you chose for it:

$str = getFileNamespace("path/to/file/to/extract/namespace/from.php");

If the argument provided is not a path to a file, the function will throw an exception, so be sure to handle errors like this appropriately. Additionally, it returns null if the contents of the file are not parsable as valid PHP code, or if they don't contain a namespace declaration.

Do note, however, that this function doesn't work well with source files which contain multiple namespaces. It will return only the first valid namespace it finds. The PHP manual advices against declaring multiple namespaces in the same file, and this function assumes its users are following the same principle.

Closing Words

I hope you find this library useful! If you find any bugs, please, remember to report them in this repo.

License

This library is licensed under the MIT license. For more information about this, please check the notice contained in the file LICENSE in the root of this repo.