kwebble/directory-folder-path

Utility for manipulating strings that represent directory/folder/path names

1.1.0 2018-04-13 21:39 UTC

Requires

• php: >=5.6

Requires (Dev)

• phpunit/phpunit: ~6.0

MIT

• Rob Schlüter

README

Open source PHP software to manipulate strings that represent directory/folder/path names.

Copyright © 2015, 2018 Rob Schlüter

Licensed under the MIT License. For details see the LICENSE file.

Description

This small piece of software does 1 thing: manipulate strings that represent the name of a path of folders. You can add and remove folders of this path.

You can use / or \ as folder separators in every string representing a path. The result you get from getPath will always use /, so it's compatible with PHP functions that use paths.

The class can work with absolute and relative paths.

The methods implement a fluid API to make method chaining possible.

The folders to add or remove can start or end with a separator, that does not really matter. The only situation where it does matter is when you manipulate the root of a path. For example to remove the root of a path the path must start with a separator.

When you try to remove a folder that does not exist, an error of type E_USER_NOTICE will be generated.

This component is also used as an example of the files, folders and configuration I describe in the article Including PHPUnit tests in SonarQube analysis.

Examples

Create an object that represents a path:

use kwebble\directoryfolderpath\DirectoryFolderPath;

$base = new DirectoryFolderPath('/source/php/project/src/main/php');

To get the new name after manipulation use the getPath() method:

$name = $base->getName();

To add folders:

$base->push('child');
// result: /source/php/project/src/main/php/child

$base->push('child/with/sub/folders');
// result: /source/php/project/src/main/php/child/with/sub/folders

To remove folders:

$base->pop('php')
// result: /source/php/project/src/main

$base->pop('src/main/php')
// result: /source/php/project

The special value .. can be used to remove any folder:

$base->pop('..')
// result: /source/php/project/src/main

$base->pop('../..')
// result: /source/php/project/src

With method chaining:

$base->pop('..')
     ->push('java');
// result: /source/php/project/src/java

To find a specific parent folder and shorten the path to it:

$base->parent('project');
// result: /source/php/project

To get the individual parts of the path as an array, to perform your own processing:

$base->getParts();
// result: ['source', 'php', 'project']

This is the reason I made this class, I wanted to 'calculate' a path dynamically:

$dfp = new DirectoryFolderPath(__DIR__);

$path = $dfp->pop(__NAMESPACE__)
            ->pop(static::PHP_MAIN_PATH)
            ->push(static::DATA_FOLDER)
            ->push(static::IP_RANGES_FOLDER)
            ->getPath();

Development

The code is distributed as a Composer package, but you can also directly use the DirectoryFolderPath class. There are no other dependencies.

Tests

The package includes a set of PHPUnit tests. To run them use the command:

composer run-script test

This will create a build folder with files describing the test results in XML format. I use this output to run SonarQube to analyze the source code. The configuration for this tool is stored in sonar-project.properties.