Download the PHP package karlnack/packmule without Composer

Pack Mule

Pack Mule is a PHP autoloader that takes advantage of PHP namespaces to implement the concept of modules and packages. This means multiple classes (along with functions and constants, although these cannot be autoloaded) can be defined in a file and successfully autoloaded.

Pack Mule happily coexists with other autoloaders, so use it fearlessly.

Overview

A module is simply a file of PHP source code. A package is then simply a directory containing one or more modules or packages. A namespace can then be used to identify a module (or package) as follows:

1. A namespace corresponds to a file path relative to some starting point, called the "base directory", with namespace separators representing directory separators. Note that a class name, function name, constant name, etc., are NEVER part of a namespace.

2. The "project namespace" is an initial hierarchy of one or more names in the namespace and constitutes a project's top-level namespace. The project namespace represents the module or package that is your project and corresponds to a exactly one file (in the case of a module) or one directory (in the case of a package) in the base directory.

3. If a project namespace is longer than one name, everything except the rightmost name constitutes the "vendor prefix". The vendor prefix is excluded when mapping a namespace to a file path in the base directory.

4. File path names that correspond to a namespace name MUST be lowercase, and the file name identified by the namespace must end in ".php". This is because identifiers are case insensitive in PHP and clients may specify a namespace in whatever case they like. Consequently, Pack Mule standardizes all names to lowercase.

The following examples show how Pack Mule resolves fully-qualified class names to a file name (which presumably contains the class definition).

     Class Name: \foo\Bar

Project Namespace: foo Vendor Prefix: Base Directory: /path/to/foo/src Resulting File Path: /path/to/foo/src/foo.php

     Class Name: \Fee\Fie\Foe

Project Namespace: Fee\Fie Vendor Prefix: Fee Base Directory: /path/to/fie Resulting File Path: /path/to/fie/fie.php

     Class Name: \Acme\Logger\File\Writer

Project Namespace: Acme\Logger Vendor Prefix: Acme Base Directory: ./acme/logger/lib Resulting File Path: ./acme/logger/lib/logger/file.php

     Class Name: \com\example\web\response\Status

Project Namespace: com\example\web Vendor Prefix: com\example Base Directory: /usr/includes/example.com Resulting File Path: /usr/includes/example.com/web/response.php

     Class Name: \framework\database\mysql\Database

Project Namespace: framework Vendor Prefix: Base Directory: ./framework/ Resulting File Path: ./framework/framework/database/mysql.php

NOTE: Nothing currently prevents both a module and a package of the same name from existing side by side in the same directory, although doing this is perhaps inadvisable, and future support of this is not guaranteed.

Requirements

Pack Mule supports PHP 5.3 through 7.4.

Installation

Use Composer to install Pack Mule by adding the following configuration to your project's "composer.json":

"require": {
    "karlnack/packmule": "1.0.*"
}

Usage

With a bootstrap file

Use this method if your project is NOT to be used as a library in others' projects and you are using Composer to manage your project's dependencies. In this case, you must register your project namespace and its base directory with Pack Mule in your project's bootstrap process.

bootstrap.php: <?php

// Initialize Composer's autoloader, which will in turn load Pack Mule.
require __DIR__ . '/vendor/autoload.php';

// Register your project namespace and its base directory with Pack Mule.
// Replace 'vendor\\project' with your actual project namespace and
// __DIR__ with the actual base directory. Always use an absolute path
// when specifying the base directory.
\karlnack\packmule\Autoloader::add('vendor\\project', __DIR__);

With an autoload file

Use this method if your project is to be used as a library in others' projects. In this case, the client code will initialize Composer's autoloader during their bootstrap process (which will, in turn, initialize Pack Mule) and your project must simply ensure its namespace is registered with Pack Mule. This can be done by using an autoload file.

Create a file "autoload.php" in your project's root directory and register your project namespace and its base directory with Pack Mule as follows:

autoload.php: <?php

// Register your project namespace and its base directory with Pack Mule.
// Replace 'vendor\\project' with your actual project namespace and
// __DIR__ with the actual base directory. Always use an absolute path
// when specifying the base directory.
\karlnack\packmule\Autoloader::add('vendor\\project', __DIR__);

Now register the autoload file with Composer by adding the following configuration to your project's "composer.json":

"autoload": {
    "files": ["autoload.php"]
}

Client projects now simply need to declare a dependency on your project in their "composer.json" and everything will work.