This repository has been archived by the owner on Mar 3, 2023. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.txt
148 lines (109 loc) · 5.27 KB
/
README.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
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.