Wallogit.com
2017 © Pedro Peláez
Path configuration library for PHP frameworks
PathConfig allows a single point of configuration for your application's paths., (*1)
The library's main purpose it to allow restructuring of applications, working around framework's existing limitations., (*2)
The animation below demonstrates restructuring a Laravel 5 project to silo less-used components to a "support" folder:, (*3)
, (*4)
The library provides both helper classes and Application class stubs to facilitate this., (*5)
config or storage
Create a paths.php file in your project's root folder., (*6)
Return from it a single array with as many key/path pairs as your application requires:, (*7)
return array
(
'app' => 'app',
'config' => 'resources/config',
'storage' => 'storage',
);
All paths should be relative to the project root, which is determined separately., (*8)
Example configurations for Laravel 5.x and Lumen 5.x are available in the config/ folder., (*9)
For configuration-free instantiation, it is important that the config file remain in the root of the project!, (*10)
There are 2 ways to use PathConfig:, (*11)
Load the PathConfig instance like so:, (*12)
$paths = pathconfig\PathConfig::instance()->load();
If a the basepath() option has not been set (the default) the library will search up the folder tree from it's vendor folder and look for the paths.php configuration file., (*13)
As soon as this has loaded, you're free to call get() methods on the $paths object as required., (*14)
Assuming you have already copied and edited your configuration file there are 4 steps you need to take to refactor your app:, (*15)
Firstly, you'll need to swap out your existing Illuminate Application class, with a pathconfig version that implements the new centralised path functionality, and overrides existing path-related methods., (*16)
In your application's bootstrap/app.php (or equivilent) file, replace the existing $app instantiation like so:, (*17)
$app = new pathconfig\apps\Laravel50();
Make sure to use the appropriate class for your framework and version., (*18)
Secondly, make sure you physically move the folders on your hard disk, reflecting the paths in your config file., (*19)
Thirdly, update and and ALL framework files that may refer to your moved folders:, (*20)
| File > location | Search | Replace |
|---|---|---|
| artisan | bootstrap/ | path to bootstrap |
| public/index.php | ../bootstrap/ | path to bootstrap |
| bootstrap/autoload.php | ../vendor/ | path to vendor |
| bootstrap/app.php | $app = new Illuminate\Foundation\Application(...); | $app = new pathconfig\apps\Laravel50; (or 51) |
| composer.json (autoload) | database | path to database |
| composer.json (autoload-dev) | tests/ | path to tests |
| File > location | Search | Replace |
|---|---|---|
| artisan | bootstrap/ | path to bootstrap |
| public/index.php | ../bootstrap/ | path to bootstrap |
| bootstrap/app.php (autoload) | ../vendor/ | path to vendor |
| bootstrap/app.php (Dotenv) | ../ | path to root |
| bootstrap/app.php (Application) | $app = new Laravel\Lumen\Application(...); | $app = new pathconfig\apps\Lumen50; |
| bootstrap/app.php (Routes) | require __DIR__.'/../app/Http/routes.php'; | require $app->getPath('routes.php'); |
| composer.json (autoload) | database | path to database |
| composer.json (autoload-dev) | tests/ | path to tests |
Finally, dump Composer's autoload with composer dump-autoload., (*21)
At this point, you should be able to reload your application, and everything should just work., (*22)
If your app errors, double-check your path edits (it's ALL about the path edits at this stage!) and make sure they are correct:, (*23)
composer dump-autoload - re-check your comsposer.json file../ fragments?Now you are up and running, you can start pulling paths out of your config., (*24)
Get paths directly from instance using the get() method:, (*25)
$config = $paths->get('config');
// /home/vagrant/code/project.app/support/config/
To append an additional filepath (which also resolves any ../ references) add it as the second argument:, (*26)
$file = $paths->get('config', 'path/to/file.php');
// /home/vagrant/code/project.app/support/config/path/to/file.php
Passing a single argument that is NOT an existing path key resolves the path from the base folder:, (*27)
$file = $paths->get('path/to/file/from/root.php');
// /home/vagrant/code/project.app/path/to/file/from/root.php
Passing no arguments (or the word base) returns the base folder:, (*28)
$root = $paths->get(); // /home/vagrant/code/project.app/
To get all paths, call all() method:, (*29)
$root = $paths->all(); // Array // ( // [base] => /home/vagrant/code/project.app // [app] => /home/vagrant/code/project.app/app // [public] => /home/vagrant/code/project.app/public // [routes.php] => /home/vagrant/code/project.app/app/Http/routes.php // )
Pass false to return the same array, but with relative paths., (*30)
Set additional paths new path using set():, (*31)
$paths->set('plugins', 'support/plugins/');
There are various options to control the loading and conversion of paths., (*32)
By default they are set to mimic PHP's realpath() which outputs differently depending on the platform it's running on., (*33)
To set a new base path:, (*34)
$paths->option('base', $value);
Note that the base path can be set only before paths are loaded., (*35)
To automatically convert slashes (on by default):, (*36)
$paths->option('convertslashes', true);
There are 3 options which include conversion of the base path, configured paths, and generated paths:, (*37)
Some frameworks expect trailing slashes, some don't. To preserve trailing slashes passed in the config file (they are trimmed by default), call:, (*38)
$paths->option('trimslashes', false);
Note that none of the slash-related options will take effect after loading paths., (*39)
By default the library doesn't test passed in paths to see if they exist in the way that PHP's realpath does. To mimic this behaviour call:, (*40)
$paths->option('testpaths', true);
The library allows only allows you to set paths once, but you can override this by setting the mutable option to false:, (*41)
$paths->option('mutable', 'false');
It might be incovenient to pass around a $paths variable. You can alias the method with a helper in one of two ways:, (*42)
function path($key = '', $filepath = '')
{
return pathconfig\PathConfig::instance()->get($key, $filepath);
}
alias() method:pathconfig\PathConfig::alias('path');
Both methods will create a global helper method called path() than you can use from anywhere:, (*43)
$path = path('config', 'email.php');
If you want to move your paths config file to a custom location, you'll need to set both the basepath and config paths manually:, (*44)
pathconfig\PathConfig::instance()
->option('basepath', __DIR__ . '/../../')
->load('config/paths.php');
Note that base paths should be absolute, but the config path:, (*45)
paths.php)my-paths.php