Introduction

The PtcHandyMan component is a great tool that can assist you with autoloading classes and manage application paths.This class can be used to autoload class files saving a lot of time compared to including files manually. The tool can autoload classes based on custom naming conventions aswell, and will try to guess the file name to be loaded. The PtcHandyMan logs all actions to the PtcDebug class, making the process of debugging loaded classes a lot easear. This class can also be used to store and retrieve directory paths acting as an application paths manager. The component also supports autoloading classes with namespaces.

Main Features:

Loads all classes in given directory
Namespace support for loading classes
Raw files can be added to the autoloader
Can store and retrieve application paths
All actions can be logged with the PtcDebug class
Helper functions can be added with the ptc-helpers.php file

Getting Started

To start using the PtcHandyMan component to autoload our classes, we just need to register the autoloader:

require_once( 'PtcHm.php' );
// register the autoloader
PtcHandyMan::register( );

Note: The PtcHandyMan::register( ) method will automatically add the folder where it resides, as a directory to autoload components from the PhpToolCase library.

Pointing The Autoloader To Files

To tell the autoloader where the files to be loaded reside, the methods PtcHandyMan::addFiles( ) and PtcHandyMan::addDirs( ) can be used. The following paragraphs will explain in details the usage of these methods.

Adding Files

Adding raw files to the autoloader can be convenient sometimes, here's how to do it:

// adding class files
PtcHandyMan::addFiles( array
(
  'HmTestClassFile'       => $_SERVER[ 'DOCUMENT_ROOT' ] . 'class-file.php' , // adding a class file to the autoloader
  'ns\HmTestClassFile'    => $_SERVER[ 'DOCUMENT_ROOT' ] . 'ns-class-file.php' , // adding a namespace class file
) );
// loading the class
$class1 = new HmTestClassFile( ); 
// loading the namespaced class
$lowercase = new ns\HmTestClassFile( );   

Adding Directories

Adding directories to the autoloader is quite usefull if you want to autoload all classes inside a directory. To add directories, the method PtcHandyMan::addDirs can be used:

// adding directories with classes to the autoloader

PtcHandyMan::addDirs( 'full_pat_to_some_directory' );

The autoloader will load all classes that match the file names.

Note: File names matching class names will load faster, second guess will be filename lowercase.

Adding Namespace Directories

To add directories with classes that use namespaces, is very similar to adding directories:

// ADDING A NAMESPACED DIRECTORY WITH CLASSES TO THE AUTOLOADER
PtcHandyMan::addDir( array
( 
  'nsTest' => 'full_path_to_namespace_directory'    // adding a namespaced directory
) );
// loading a namespaced class
$class_ns = new nsTest\HmTestNs( );
  
// loading a namespaced class inside subfolder "hmNsDeep"
$class_ns_deep = new nsTest\hmNsDeep\HmTestNsDeep( );

As you can see, the only difference with the Adding Directories example, is the use of an array key to define the namespace.

Note: File names matching class names will load faster, second guess will be filename lowercase.

Using Separators

Different Naming conventions can also be used to autoload classes, all we need to do is add sperators and naming conventions to the PtcHandyMan autoloader.
Here is an example using wordpress naming conventions to autoload classes:

// wordpress separator for class names
PtcHandyMan::addSeparator( '-' );
  
// wordpress name convention for classes
PtcHandyMan::addConvention( 'class{SEP}{CLASS}' );    
// will load the file "class-wp-debug.php" by using the name convention given,
// and replacing underscore with separators added
WP_PtcDebug::load( );

As you can see naming convention can use 2 {placeholders}, which are {CLASS} for the class name and {SEP} for the separators added.

Here is another example that uses "class.{CLASS}" as naming convention:

// adding a separator for class names
  PtcHandyMan::addSeparator( '-' );
// adding another naming convention
PtcHandyMan::addConvention( 'class.{CLASS}' );    
// loads the file "class.hm-test-sep.php" by replacing the "_" with "-" added separator in the class name
$sep_class1 = new Hm_Test_Sep( ); 

Note: Using custom naming conventions and separators to autoload classes, is slower then using the standard naming convention logic ( ClassName.php ).

Retrieving Autoloader Directories

To retrieve the list of directories that the autoloader uses, the method PtcHandyMan::getDirs( ) can be used:

// getting all directories of the autoloader
$dirs = PtcHandyMan::getDirs( );
var_dump( $dirs );

To retrieve only part of the directories, like just the files for example, we can use the "$type" argument:

// getting all files added to the autoloader
$files = PtcHandyMan::getDirs( 'files' );     
var_dump( $dirs );

This are the possible options for the "$type" argument:

files ( retrieves all added files )
directories ( retrieves all added directories )
ns ( retrieves all added namespace directories )

Using The Application Paths Manager

The PtcHandyMan component also provides an elegant way to manage application paths, have a look at the following paragraphs to understand how this can be done.

Adding Paths

The PtcHandyMan::addAppPaths( ) can store application paths inside an array, to be later retrieved by the unique name that we will set as array key.

Here's an example using "lib" as unique identifier for the added path:

// adding application paths for later usage
PtcHandyMan::addAppPaths( array
( 
  'lib'   =>   dirname( __FILE__ ) . '/autoloader-example-files'
) );

Retrieving Added Paths

To retrieve previously added application paths, the method PtcHandyMan::getAppPaths( ) can be used. The following example will add a directoy to the autoloader, using a previously configured application path:

// adding directories with classes to the autoloader

PtcHandyMan::addDir( PtcHandyMan::getAppPath( 'lib' ) ); // using a previously created path

If the argument "$name" is not used, all currently configured paths will be returned.

Note: The ptc-helpers.php function file, provides helper functions to interact with the application path management logic of the PtcHandyMan.
See Using The Library Helpers.

Reading Inaccessible Properties

The PtcHandyMan component provides a couple of "handy methods", and one of them certainly is the PtcHandyMan::getProperty( ) method. This method can be used to read the value of a protected / private property from an object.

The following example shows how to read inaccessible properties:

// reading a protected property from an initialized object
$property_value = PtcHandyMan::getProperty( $some_object , 'propertyName' );
// reading a protected static property from a singleton class
$property_value = PtcHandyMan::getProperty( 'class_name' , 'propertyName' );

Using The Library Helpers

The PhpToolCase library, provides helper functions for the PtcHandyMan component. To start using these functions, the ptc-helpers.php file needs to be present and declared with the same namespace as the PtcHandyMan. The PtcHandyMan::register( ) method will include this file automatically.

See Helper Functions (ptc-helpers.php) for example usage of these library helpers.

Table of Contents