Class: Loader
- Package: saf.Loader
- Author: John Luxford <lux@simian.ca>
- Copyright: Copyright (C) 2001-2003, Simian Systems Inc.
- License: http://www.sitellite.org/index/license Simian Open Software License
- Version: 2.4, 2003-08-08, $Id: Loader.php,v 1.13 2008/03/14 16:57:25 lux Exp $
- Access: public
Loader is a class that creates more of a Java-like 'import' mechanism
for including libraries and files. That way you can specify include
files not by their location but by which library they correspond to
(ie. org.sitellite.XML.XSLT).
New in 1.2:
- Added a 'return' option to the import() method's $method parameter. Also
created three new methods which act as aliases to import() with the $method
already specified. These are inc(), req(), and ret(). They are abbreviated
not for brevity's sake, but because include, require, and return are all
reserved words in PHP.
- Separated the path translation logic into its own methods, translatePath() and
translateRealPath(), which cleaned up the code a lot and made the import()
method nice and small.
New in 1.4:
- Fixed a regex bug in translateRealPath().
New in 1.6:
- Added an $extension parameter to translatePath(), translateRealPath(),
import(), inc(), req(), and ret().
New in 1.8:
- Fixed a bug in the loading order in translatePath(), where the file
foo/bar.php should be chosen before foo/bar/bar.php, which it wasn't
before.
New in 2.0:
- Added box(), form(), getBoxSettings(), getFormSettings(), boxAllowed(),
and formAllowed() methods.
- Added global functions that alias methods of a global $loader object. These
include: loader_import(), loader_include(), loader_require(), loader_return(),
loader_box(), loader_form(), loader_box_get_settings(), loader_box_allowed(),
loader_form_get_fields(), and loader_form_allowed().
- Added conf() function which aliases the values from a global $conf 2D array.
New in 2.2:
- Added a 'dl' $method to import(), which calls dl() on the specified $lib in
one of the following directories: saf/dl/dll, saf/dl/dylib, or saf/dl/so.
Note that the suffix (.dl, .dylib, or .so) is provided by the
PHP_SHLIB_SUFFIX constant, which is also used to determine which directory
to find the extension in.
- Added loader_dl() as an alias to the new import() $method.
- Removed the html_marker() calls from box() and form() -- they now reside in
saf.XML.XT, so as not to interfere with the creation of web services,
command-line utilities, and reusable components, with predictable output
based on actions.
New in 2.4:
- Box/form changes: added new access.php parameters.
- Added $app property and getApp() method. This introduces a new SCS
directory layout, being inc/app/$app/(boxes|forms|etc.)/$request.
- Added the ability in translatePath() to call paths within custom apps
by specifying the app name instead of a defined path name.
Usage Example
<?php
$loader = new Loader (
array (
'sitellite' => 'J:/devel/inc/lib',
'pear' => 'D:/PHP/pear'
)
);
$loader->import ('sitellite.Cookie');
$loader->import ('pear.Date.Human');
$cookie = new Cookie;
$cookie->set ('icamehereat', serialize (Date_Human::gregorianToHuman (29, 10, 2001)));
?>
Return to Top
Properties
$paths = array ()
Contains a list of the different libraries and their locations.
Some methods of Loader assume there is a 'default' location, and the
constructor may set 'default' to the current directory if unspecified.
$included = array ()
Contains a list of the libraries that have already been included.
Note: libraries included through the find () method will not be listed here.
$boxPath = 'boxes'
The path to the boxes directory.
$formPath = 'forms'
The path to the forms directory.
$app
The name of the default SCS app.
$prefix = 'inc/app'
This is the prefix to the app directories.
Return to Top
Methods
Loader ($path = '.')
Constructor method. If $path is a string, it specifies the 'default'
path location. If $path is an associative array, it specifies a list of libraries
and their locations, and 'default' is set to the current directory (unless overridden
by being specified in $path).
import ($lib, $method = 'include', $extension = 'php')
This is the method that translates the library name, etc. and makes the
PHP '(include|require)_once' call. $lib is the class to include (adds .php for you),
and $method is the method to import the file with (either 'include', 'require', or
'return', which returns the contents of the specified package as opposed to simply
including it and returning true if it succeeded). If the $lib specified
points to a directory, import () will look for a file with the same file name as
that directory with a .php extension inside the directory (ie. ('sitellite.Database'
would import 'sitellite/Database/Database.php'). You can optionally use a '.*' to
tell Loader to load each file in a particular directory as well. It will then
proceed to load the entire directory, starting with the file of the same name as the
directory, then in the order that readdir() reads them on your system. Please Note:
import() always calls include_once() or require_once(). If you need to call just
include() or require(), you will have to do so manually.
addPath ($new)
This method controls your access to the $paths associative array, allowing
you to add new libraries to it. $new must be an associative array.
path ($lib = 'default')
- Access: public
- Return: string
Returns the path to the library specified (which it gets from the $paths
associative array). This makes Loader potentially useful for directory-related
tasks other than as an (include|require)_once replacement. If $lib is not specified,
it uses the 'default' path.
_recurse ($dir, $package, $load)
Recursively searches a directory structure for the specified filename, and
optionally includes that file.
find ($package, $lib = '', $load = 0)
- Access: private
- Return: string
Search the Loader directories recursively for packages. If $lib
is unspecified, find () searches all of the Loader directories. Returns
the directory path to the file, if found.
translatePath ($lib, $extension = 'php')
Translates a Loader-style path (ie. saf.MailForm.Widget.File) into
the actual file name or names (for paths ending in .*), which can then be
used by the import() method. This can also be useful if you want to find
out the actual file name that corresponds to the Loader path (since for
instance saf.MailForm could mean either saf/lib/MailForm.php or
saf/lib/MailForm/MailForm.php). Returns the file name and path on success,
an array of file names if the path ends in .* and it is successful, or
false on failure. Note that the first component to a path, which is
considered the root of the path, must be either defined in the $paths
property or else exist as an SCS app in inc/app.
translateRealPath ($lib, $extension = 'php')
Translates an actual path into a Loader-style path.
inc ($lib, $extension = 'php')
- Access: public
- Return: boolean
Alias for import(), with the $method always specified as 'include'.
req ($lib, $extension = 'php')
- Access: public
- Return: boolean
Alias for import(), with the $method always specified as 'require'.
ret ($lib, $extension = 'php')
- Access: public
- Return: string
Alias for import(), with the $method always specified as 'return'.
box ($name, $parameters = array (), $context = 'normal')
- Access: public
- Return: string
Executes the specified box using the Sitellite box API,
which is essentially just an include.
boxRewrite ($data)
form ($name, $context = 'normal')
- Access: public
- Return: string
Executes the specified form using the Sitellite form API,
which is essentially just an include of a file that defines a
subclass of saf.MailForm.
getBoxSettings ($name, $app)
getBoxAccess ($name, $app)
getFormAccess ($name, $app)
boxAllowed ($name, $context = 'normal')
- Access: public
- Return: mixed
Checks recursively in the box directory and parent directories
until it checks $boxPath finally for an access.php file. It then
parses that file as an INI file and determines whether the box is
accessible by the current user. If a template is specified in the
access.php file, that template name is returned on success, otherwise
a boolean true value is returned on success. False is always returned
if the user is not allowed. Allowed access values are:
- sitellite_access - string - the access level of the box
- sitellite_status - string - the status of the box
- sitellite_action - boolean - whether the box can be called as an action
- sitellite_inline - boolean - whether the box can be called inline within a page
- sitellite_goto - string - the location to redirect to if the box permissions fail
- sitellite_template - string - template to use for this box, applies only to boxes called as actions
- sitellite_template_set - string - template set to use for this box, applies only to boxes called as actions
- sitellite_chdir - boolean - whether to change the base directory during the execution of the box,
to more easily resolve includes in ported apps
- sitellite_fname - boolean - whether to check for filenames other than index.php to execute
(ie. myapp-hello-world-action resolving to inc/boxes/hello/world.php or inc/boxes/hello/world/index.php
-- note that Loader resolves the latter first, if available)
- sitellite_rewrite_pattern - string - a pattern within the box output (usually urls from ported apps) to rewrite
- sitellite_rewrite_replace - string - the replacement for the rewrite pattern
- sitellite_exit - boolean - calls exit() at the end of the box, bypassing all post-output processing.
getFormSettings ($name)
getFormFields ($name)
formAllowed ($name, $context = 'normal')
- Access: public
- Return: mixed
Checks recursively in the form directory and parent directories
until it checks $formPath finally for an access.php file. It then
parses that file as an INI file and determines whether the form is
accessible by the current user. If a template is specified in the
access.php file, that template name is returned on success, otherwise
a boolean true value is returned on success. False is always returned
if the user is not allowed.
getApp ($request)
- Access: public
- Return: string
Determines which SCS app to run, based on the request path
and the default provided.
removeApp ($request, $app = false)
- Access: public
- Return: string
Removes the $app name from the $request path.
app ()
- Access: public
- Return: string
Gets the current running app -- used by appconf() and appconf_set()
or inside a box or form that needs to know. Basically returns the top
item on the $apps stack.
Return to Top