Download the PHP package aura/includer without Composer
On this page you can find all versions of the php package aura/includer. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
All versions of includer with dependencies
Informations about the package includer
Provides a facility to include multiple files from specified directories, in order, with variables extracted into a limited include scope.
This library requires PHP 5.3 or later; we recommend using the latest available version of PHP as a matter of principle. It has no userland dependencies.
It is installable and autoloadable via Composer as aura/includer.
Alternatively, download a release or clone this repository, then require or include its autoload.php file.
To run the unit tests at the command line, issue
phpunit at the package root. (This requires PHPUnit to be available as
The Example Scenario
Let's say you have a series of packages, modules, plugins, etc. To do its setup work, your framework or foundation needs to include certain files from each of thse modules, such as configuration or routing files.
For our examples, the module directory structure will look like this:
modules/ foo/ autoload.php config/ default.php testing.php routes.php bar/ autoload.php baz/ autoload.php config/ default.php
An example autoload.php file might look like this:
An example config file might look like this:
An example routes.php file might look like this:
Because of the shared variables being used in each file, we need them to be available, but we also want each file to be kept separate from the global scope.
When including the configuration files, we need both the default and an additional "mode" for overrides to the defaults.
If a file is missing, we can skip it without ill effect.
Accomplishing The Task
The Includer makes this scenario, and others like it, relatively easy. First, we instantiate the Includer:
Next, we set the various directories we need to look through for files to include:
Then we set the files to look for in each of the directories (we will include both the default config and an override testing config):
Because the files happen to need local variables, we create them first, then make them available to the include files:
Finally, after setting up the directory, files, and variables, we call the
This will create a separate scope for each include file, extract the variables into that limited scope, and then include the file within that limited scope. This means that no include file can affect the global state of the application, except through the injected variables.
By default, the Includer will include files in "directory order", represented
by the constant
Includer::DIR_ORDER. This means that the Includer visits the
first directory and attemps to load all the files noted in that directory,
then proceeds to the next directory. Given our above example, the loading
Includer::DIR_ORDER would be:
# first dir modules/foo/autoload.php modules/foo/config/default.php modules/foo/config/testing.php modules/foo/routes.php # second dir modules/bar/autoload.php # third dir modules/baz/autoload.php modules/baz/config/default.php
Alternatively, you can specify
load(Includer::FILE_ORDER) to load files in
"file order". This means that the loader attemps to load the first file from
each directory, then the second file from each directory, and so on. Given our
above example, the loading for
Includer::FILE_ORDER would be:
# first file modules/foo/autoload.php modules/bar/autoload.php modules/baz/autoload.php # second file modules/foo/config/default.php modules/baz/config/default.php # third file modules/foo/config/testing.php # fourth file modules/foo/routes.php
By default, the Includer is relatively strict about what path combinations
it will actually include. It will convert the directory + file path using
realpath() to get the absolute path, and then check
to see if that absolute path is in the same directory as specified in the
Includer. (This is because it's possible to use
../ and symbolic links to
point to file locations outside the specified directory.) Files that are not
readable, or that are outside the specified directory, will not be included.
This type of processing is sometimes too strict; if you use symbolic links,
for example, the strict processing may exclude those files. To turn off strict
process, and only check if the file is readable, call
Under the hood, the Includer uses glob() to find files. This means you can use wildcards in the filenames to include files.
If you have dozens or scores of files that need to be included, that amount of file system activity can be a performance drain. To mitigate this, it can be useful to cache the files that would have been included.
The Includer has a
read() method to get the contents of the files to be
included and concatenate them, returning the concatenated contents for you to
cache in a file of your choosing. You can then point the Includer to that
cached file; if it exists, the Includer will use that file instead of
including the various different directory and file path combinations.
First, we get the text of the concatenated files using the
By default, it will concatenate the files in
Includer::DIR_ORDER, but you
read(Includer::FILE_ORDER) if you prefer.
read() method will get the contents of each file, trim it, strip any
leading and trailing
` tags, replace theFILE
constant with the equivalent string file name, and replace theDIR` constant with the
equivalent string directory name. (These replacements reflect the fact that
the code is being copied from its original location to a new location, and
the constants expect the value of thr original location.)
Now that we have the contents of the files, we add an opening
<?php tag and
the time we created it, and then save it as a cache file:
Finally, we tell the Includer where the cache file is. If it is readable,
the Includer will use it on
load(); otherwise, it will include the various
directory and file combinations.
Sometimes it will be useful to see what files the Includer actually found.
getDebug() method to return an array of information about what
the Includer found, in what order, and in what mode.